快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-watch` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

1. 安装软件包

   bun add @capgo/capacitor-watch

2. 与原生项目同步

   bunx cap sync

3. 配置插件

   基础用法示例：

   import { CapgoWatch } from '@capgo/capacitor-watch';
   
   // Check watch connectivity status
   const info = await CapgoWatch.getInfo();
   console.log('Watch paired:', info.isPaired);
   console.log('Watch reachable:', info.isReachable);
   
   // Listen for messages from watch
   await CapgoWatch.addListener('messageReceived', (event) => {
     console.log('Message from watch:', event.message);
   });

   向 Watch 发送消息：

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOS

   iOS 必要配置：

   1. 在 Xcode 中为你的 iOS App 添加 WatchConnectivity capability
   2. 在 Xcode 项目中创建一个 watchOS app target
   3. 在您的 watchOS 应用中实现 WatchConnectivity（请参阅下文的“Watch App 实现”）

   插件加载时会自动激活 WCSession。

   Android

   Wear OS 必要配置：

   1. 添加一个 Wear OS 模块 至您的 Android 项目（与手机端应用 applicationId 及签名保持一致）。
   2. 在 wear 模块中声明 capgo_watch 能力（请参阅 创建 Wear OS 应用).
   3. 使用插件路径在 watch 上实现 Data Layer 监听器（/capgo/message, /capgo/context以及其他）。

   手机端插件在加载时会注册 Wearable API 监听器。使用 getInfo() 来检查已连接的节点以及是否检测到手表应用。

   完整步骤： 创建 Wear OS 应用.

4. 处理需要回复的消息

   // Listen for messages that need a response
   await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
     console.log('Request from watch:', event.message);
   
     // Process the request
     const result = await processWatchRequest(event.message);
   
     // Send reply back to watch (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         result,
       },
     });
   });

5. 同步应用状态

   // Update application context (latest value only)
   await CapgoWatch.updateApplicationContext({
     context: {
       theme: 'dark',
       userId: '123',
       lastSync: Date.now()
     }
   });
   
   // Listen for context updates from watch
   await CapgoWatch.addListener('applicationContextReceived', (event) => {
     console.log('Context from watch:', event.context);
   });

6. 可靠地传输用户信息

   // Queue data for reliable delivery (even when watch is offline)
   await CapgoWatch.transferUserInfo({
     userInfo: {
       recordId: '456',
       action: 'created',
       data: { name: 'Item 1' }
     }
   });
   
   // Listen for user info transfers
   await CapgoWatch.addListener('userInfoReceived', (event) => {
     console.log('User info from watch:', event.userInfo);
   });

7. 监控连接状态

   // Track reachability changes
   await CapgoWatch.addListener('reachabilityChanged', (event) => {
     console.log('Watch reachable:', event.isReachable);
     if (event.isReachable) {
       // Watch is now available for interactive messaging
     }
   });
   
   // Track session activation state
   await CapgoWatch.addListener('activationStateChanged', (event) => {
     // 0 = notActivated, 1 = inactive, 2 = activated
     console.log('Session state:', event.state);
   });

快速入门

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

示例：updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

示例：transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

常见坑点

• 监听器: 在页面卸载时移除句柄。
• 原生同步：运行 bunx cap sync 在插件升级后。
• 唯一可信来源：信任 src/definitions.ts 在 GitHub 仓库中。

Watch App 实现

您的 watchOS App 需要实现 WatchConnectivity。以下是一个 SwiftUI 示例：

import SwiftUI
import WatchConnectivity

@main
struct MyWatchApp: App {
    init() {
        WatchViewModel.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class WatchViewModel: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WatchViewModel()

    @Published var lastMessage: [String: Any] = [:]

    func activate() {
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    // Send message to iPhone
    func sendToPhone(_ data: [String: Any]) {
        guard WCSession.default.isReachable else {
            print("iPhone not reachable")
            return
        }
        WCSession.default.sendMessage(data, replyHandler: nil)
    }

    // Send message with reply
    func sendToPhoneWithReply(_ data: [String: Any], completion: @escaping ([String: Any]) -> Void) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(data, replyHandler: completion)
    }

    // Receive message from iPhone
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = message
        }
    }

    // Receive application context
    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = applicationContext
        }
    }

    // Required delegate methods
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        print("Watch session activated: \(activationState.rawValue)")
    }
}

API 参考

方法

sendMessage(options: SendMessageOptions)

向 watch 发送交互式消息。要求 watch 处于可连接状态。

参数：

• data: Object - 要发送给 watch 的数据

updateApplicationContext(options: UpdateContextOptions)

更新应用上下文。仅保留最新值。

参数：

• context: Object - 要同步的上下文数据

transferUserInfo(options: TransferUserInfoOptions)

将用户信息加入队列以确保可靠送达。

参数：

• userInfo: Object - 要传输的用户信息

replyToMessage(options: ReplyMessageOptions)

回复一条请求响应的消息。

参数：

• callbackId: string - 来自 messageReceivedWithReply 事件的回调 ID
• data: Object - 回复数据

getInfo()

获取 Watch 的连接状态。

返回值： WatchInfo 包含以下内容的 object：

• isSupported: boolean - 当前平台是否支持 watch API
• isPaired: boolean - 已配对 Apple Watch (iOS) 或已连接至少一个 Wear OS 节点 (Android)
• isWatchAppInstalled: boolean - 已安装配套手表 app (iOS) 或 capgo_watch 检测到相关能力 (Android)
• isReachable: boolean - 手表是否可达以进行即时消息通信
• activationState: number - 会话状态 (iOS WCSession；Android 连接节点时为 2，否则为 0)

getPluginVersion()

获取原生插件版本。

事件

事件	描述
messageReceived	来自 watch 的简单消息
messageReceivedWithReply	等待回复的消息 (包含 callbackId)
applicationContextReceived	来自 watch 的 Context 更新
userInfoReceived	来自 watch 的用户信息传输
reachabilityChanged	Watch 连接状态已变更 (仅限 iOS)
activationStateChanged	Session 激活状态已变更 (仅限 iOS)

通信模式

即时消息 (sendMessage)

• 要求 watch 可达
• 最适合交互式、时效性强的通信
• 若 watch 不可用则立即失败

应用上下文 (updateApplicationContext)

• 仅保留最新值 - 旧值会被覆盖
• 最适合同步当前应用状态
• 在 watch 可用时送达

用户信息传输 (transferUserInfo)

• 按顺序排队并送达
• 最适合必须送达的重要数据
• 即使 watch 暂时无法连接也能工作

平台注意事项

请参阅 平台支持表 （见插件概览），查看逐方法矩阵。

iOS (Apple Watch)

• 需要 iOS 15.0 或更高版本
• 使用 WatchConnectivity framework
• Session 会在插件加载时自动激活
• 支持 context 和 user info 的后台传输
• 触发 reachabilityChanged 以及 activationStateChanged

Android (Wear OS)

• 需要带有 Wear OS Data Layer 的 Google Play services（play-services-wearable插件中已包含）
• 手机端和手表端的 APK 必须共享 相同的 applicationId 以及 签名密钥
• 手表端 App 必须声明能力 capgo_watch
• 是否 不会 触发 reachabilityChanged 或 activationStateChanged; 轮询 getInfo() 需要时
• 设置指南： 创建 Wear OS 应用

Web 端

• 浏览器不支持 Watch 消息传递
• getInfo() resolve 为 isSupported: false 并将其他字段设为安全默认值
• getPluginVersion() resolve 为 { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo，以及 replyToMessage 以不可用错误拒绝
• addListener 通过 Capacitor 解析句柄 WebPlugin，但浏览器不支持 watch 事件（回调不会执行）

常见用例

1. 数据同步：保持手表与手机数据同步
2. 远程控制：通过手表控制手机功能
3. 通知：向手表发送自定义通知
4. 健康数据: 分享健身与健康指标
5. 媒体控制: 通过手表控制音乐播放
6. 智能家居: 通过手腕控制设备

故障排除

手表无法连接：

• 确保手表在蓝牙范围内
• 检查两个 App 是否都在运行
• 确认双方的 WCSession 已激活

未收到消息：

• 发送前检查监听器是否已注册
• 验证 Watch App 是否实现了 WCSessionDelegate
• 使用 transferUserInfo 以确保消息送达

Session 未激活：

• 确保已在 Xcode 中添加 WatchConnectivity capability
• 检查 Watch App 是否配置了对应的 companion bundle ID
• 验证两个 App 的目标 OS 版本是否兼容

从入门指南继续

如果你正在使用 快速入门 要规划原生插件工作，请将其与 使用 @capgo/capacitor-watch 用于《使用 @capgo/capacitor-watch》中的原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。