入门指南

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 应用程序的 WatchConnectivity 能力
   2. 在 Xcode 项目中创建一个 watchOS 应用程序目标
   3. 在您的 watchOS 应用程序中实现 WatchConnectivity（请参见 Watch App 实现）

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

   Android

   Apple Watch 只在 iOS 上受支持。 在 Android 上，所有方法都会以“Apple Watch 只在 iOS 上受支持”错误拒绝。 getInfo() 方法返回 isSupported: false.

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
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { 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);
   });

查看应用程序实现

您的 watchOS 应用程序需要实现 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)

向手表发送一个交互式消息。需要手表保持可达。

参数：

• data: Object - 要发送到手表的数据

updateApplicationContext(options: UpdateContextOptions)

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

参数：

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

transferUserInfo(options: TransferUserInfoOptions)

将用户信息排队以确保可靠的传递。

参数：

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

replyToMessage(options: ReplyMessageOptions)

回复一个要求回复的消息。

参数：

• callbackId: string - 从 messageReceivedWithReply 事件中获取的回调 ID
• data: Object - 回复数据

getInfo()

获取手表连接状态。

返回： WatchInfo 对象中包含：

• isSupported: boolean - 是否可用
• isPaired: boolean - 是否配对
• isWatchAppInstalled: boolean - 是否安装手表应用
• isReachable: boolean - 是否可达
• activationState数字 - 会话状态 (0/1/2)

getPluginVersion()

获取本机插件版本。

事件

事件	描述
messageReceived	来自手表的简单消息
messageReceivedWithReply	来自手表的消息，期待回复（包含callbackId）
applicationContextReceived	来自手表的上下文更新
userInfoReceived	来自手表的用户信息传输
reachabilityChanged	手表连接状态改变
activationStateChanged	会话激活状态已改变

通信模式

即时消息（sendMessage)

• 需要手表可达成
• 适合交互式、时间敏感的通信
• 如果手表不可用，立即失败

应用上下文（updateApplicationContext)

• 仅最新值 - 前一次值将被覆盖
• 适合同步当前应用状态
• 当手表可用时即时传递

用户信息传输（transferUserInfo）transferUserInfo)

• 按顺序排队并传递
• 适用于必须传递的重要数据
• 即使手表暂时不可用也能正常工作

平台说明

iOS

• 使用 WatchConnectivity 框架
• __CAPGO_KEEP_0__
• Session自动激活于插件加载时
• 支持背景传递上下文和用户信息

Android

• 不受支持（Apple Watch仅限iOS）
• 所有方法都以适当的错误拒绝
• getInfo() 返回 isSupported: false

Web

• 不受支持
• 所有方法都以不可用错误拒绝
• getInfo() 返回 isSupported: false

常见用例

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

故障排除

手表不可达:

• 确保手表在蓝牙范围内
• 检查两款应用程序是否正在运行
• 检查两边都激活了WCSession

未接收到消息:

• 检查监听器在发送之前是否已注册
• 检查手表应用程序是否实现了WCSessionDelegate
• 使用 transferUserInfo 确保交付

会话未激活：

• 确保在 Xcode 中添加 WatchConnectivity 功能
• 检查手表应用程序是否具有伴侣包 ID
• 检查两个应用程序是否目标兼容的操作系统版本