Getting Started

安装

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

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

然后使用以下提示：

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 应用添加 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);
   });

观察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)

参数：

__CAPGO_KEEP_0__

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

updateApplicationContext(options: UpdateContextOptions)

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

参数：

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

transferUserInfo(options: TransferUserInfoOptions)

可靠传递用户信息。

参数：

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

replyToMessage(options: ReplyMessageOptions)

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

参数：

• callbackId: __CAPGO_KEEP_0__ - __CAPGO_KEEP_1__
• data: __CAPGO_KEEP_0__

getInfo()

获取手表连接状态。

返回: WatchInfo 对象中包含:

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

getPluginVersion()

获取原生插件版本。

事件

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

通信模式

即时通讯（sendMessage)

• 需要手表保持可达
• 最佳用于交互式、实时通信
• 如果手表不可用，立即失败

应用上下文（updateApplicationContext)

• 仅保留最新值，之前值会被覆盖
• 最佳用于同步当前应用状态
• 当手表可用时发送

用户信息传输（transferUserInfo)

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

平台说明

iOS

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

安卓

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

Web

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

常见用例

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

故障排除

手表不可达

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

未接收到消息

• 检查监听器是否注册在发送之前
• 在手表应用程序中实现WCSessionDelegate
• 使用 transferUserInfo 确保消息可靠送达

会话无法激活

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

继续从 Getting Started

如果您正在使用 Getting Started 来规划原生插件工作，连接它与 使用 @capgo/capacitor-watch 为原生能力在使用 @capgo/capacitor-watch 中 Capgo 插件目录 为产品工作流程在 Capgo 插件目录 Capacitor 插件由 Capgo 为 Capacitor 插件由 Capgo 的实现细节 添加或更新插件 为添加或更新插件的实现细节, 和 Ionic 企业插件替代方案 为 Ionic 企业插件替代方案的产品工作流程