开始使用

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 Implementation）

   插件在加载时自动激活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);
   });

观察App实现

您的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: number - 会话状态 (0/1/2)

getPluginVersion()

获取本地插件版本。

事件

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

通信模式

即时通讯（sendMessage）sendMessage)

• 适合交互式、时间敏感的通信
• 即时通讯（sendMessage）
• 如果 watch 不可用，立即失败

应用上下文（updateApplicationContext)

• 仅传递最新值，之前的值会被覆盖
• 最佳选择，用于同步当前应用状态
• 当 watch 可用时传递

用户信息传输（transferUserInfo)

• 有序传递，按顺序传递
• 最佳选择，用于传递重要数据
• 即使 watch 临时不可用，也能正常工作

平台说明

iOS

• 需要 iOS 15.0 或更高版本
• 使用 WatchConnectivity 框架
• 会话在插件加载时自动激活
• 支持背景传递上下文和用户信息

Android

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

Web

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

常见用例

1. 数据同步:手机和手表数据保持同步
2. :从手表控制手机功能:接收通知
3. :接收来自手机的通知:
4. ,:
5. ,:
6. ,:

,

,

• :
• ,Troubleshooting
• 验证 WCSession 在两边都激活

未接收到的消息：

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

会话未激活：

• 确保在 Xcode 中添加了 WatchConnectivity 能力
• 检查手表应用是否具有伴侣包 ID
• 验证两款应用都支持兼容的操作系统版本