# @capgo/capacitor-watch 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-watch/

版本：8\.1\.19
npm 元数据更新时间：2026-11-02T13:02:18.643Z
中文译文更新时间：2026-11-09T08:57:46.820Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-watch
原文对照：https://npmcn.com/package/%40capgo/capacitor-watch/?lang=original
项目主页：https://capgo.app/docs/plugins/watch/
源码仓库：https://github.com/Cap-go/capacitor-watch

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：157 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-01-04T16:27:48.046Z
- 最新版本发布：2026-11-02T13:02:18.309Z
- 近 30 天下载量：3193（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

具有双向消息支持的 Apple Watch 通信电容插件

## 安装

```sh
npm install @capgo/capacitor-watch
```

也可以使用：`pnpm add @capgo/capacitor-watch`、`yarn add @capgo/capacitor-watch`、`bun add @capgo/capacitor-watch`

## README

# @ capgo/ 电容器监视

与来自您 Capacitor app 的伴侣手表应用交谈:发送消息,同步状态并接收回复,与 iOS 上的 Apple Watch 和 Android 上的 Wear OS.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-watch)](https://capgo.app/?ref=plugin_watch)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_watch)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_watch) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-watch` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _加上@capgo/capor-watch到我的Capacitor应用上并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_watch) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_watch)

![@capgo/capacitor-watch for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-watch/main/assets/github-social-preview.png)

## 主要特点

-   **信件**数字 : `sendMessage()` 用于交互式信息和 `replyToMessage()` 来答表.
-   **共享状态**数字 : `updateApplicationContext()` 同步最新状态到手表.
-   **背景传输**数字 : `transferUserInfo()` 队列数据以交付.
-   **活动**:消息,应用程序上下文和用户信息收听器,加上iOS上的可达性和激活收听器.
-   **状态**数字 : `getInfo()` 报告对齐、可达到性和支持.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. iOS使用与 Capgo WatchSDK 手表应用的WatchConnectivity. Android使用Wear OS数据层. 在网上不可用.

## 为什么是控制者观察?

唯一兼容的 Capacitor 8 插件 **双向苹果观察通信**数字 :

-   **双向通讯** - 在iPhone和苹果观察之间发送和接收信息
-   **应用程序上下文** - 用最新的唯值语义同步应用程序状态
-   **用户信息传输** - 可靠的排队送货,即使手表下线
-   **请求/回复模式** - 互动工作流程和基于召回的反应
-   **快速UI准备** - 包括有可观察对象支持的监视侧SDK
-   **iOS 15+ (英语)** - 由Swift软件包管理器为现代iOS所建

对于健康应用,健身跟踪器,遥控器,以及任何延伸至苹果观察的应用都至关重要.

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/watch/ (中文(简体) )](https://capgo.app/docs/plugins/watch/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

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

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

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

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-watch
npx cap sync
```

## 所需资源

-   **iOS系统**: iOS 15.0+(最低8号电机). 需要监视连接能力.
-   **监视系统**: watchOS 9.0+. (中文(简体) ). 需要配有 Capgo WatchSDK 的相伴应用 .
-   **机器人**: 不支持(Apple Watch是只使用iOS). 方法返回适当的错误.
-   **硬件**: real Apple Watch 需要 - 模拟器不支持WatchConnective.

* * *

## 完成设置教学

这个教程会引导您在您的 Capacitor app 和 Apple Watch 之间设置双向交流. 每一步都要小心一点.

### 步骤1:安装插件

首先,将插件添加到您的 Capacitor 工程中 :

```bash
npm install @capgo/capacitor-watch
npx cap sync ios
```

然后以 Xcode 打开您的 iOS 项目 :

```bash
npx cap open ios
```

### 步骤2: 添加 iOS 应用程序能力

您的 iOS app 需要特定的能力与 Apple Watch 通信.

1.  选择您的 **应用目标** xcode (不是项目) 中
2.  转到 **签名能力( C)** 选项卡
3.  点击 **\+ 能力** 按钮

![Add capability in Xcode](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/add-capability.png)

4.  增加以下能力:
    -   **背景模式** - 启用“背景获取”和“转发通知”
    -   **推动通知** (需要为背景醒悟)

你的能力应该这样 当完成:

![Final capabilities configuration](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/capabilities-final.png)

### 第3步:配置 AppDelegate.swift

> \[注\] 现在这不会编译。 没关系,我们以后再修

```swift
import UIKit
import Capacitor
import WatchConnectivity
import CapgoWatchSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Initialize WatchConnectivity session
        if WCSession.isSupported() {
            WCSession.default.delegate = CapWatchSessionDelegate.shared
            WCSession.default.activate()
        }
        return true
    }

    // ... rest of your AppDelegate code
}
```

### 步骤 4: 创建监视 App 目标

现在创建 WatchOS 同伴应用程序 :

1.  在 Xcode 中,转到 **文件 > 新建 > 目标**
2.  选择 **监视系统** 选项卡
3.  选择 **应用** 下一个

![Create watch target](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/target-watch.png)

4.  配置手表应用程序 :
    -   **产品名称**:您的应用名(例如"MyApp Watch")
    -   **套装标识符**: 必须遵循模式 `[your-app-bundle-id].watchkitapp`
        -   示例:如果您的应用程序是 `com.example.myapp`,使用时 `com.example.myapp.watchkitapp`
    -   **语言**页:1
    -   **用户界面**缩写:SwiftUI

![Watch target options](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-target-options.png)

### 步骤5: 添加 Capgo WatchSDK 软件包

手表应用需要我们的SDK与电话通信. 添加为 Swift 包 :

1.  选择您的 **项目** 在导航器中(顶层,蓝色图标)
2.  转到 **软件包依赖性** 选项卡
3.  点击 **\+ 键** 按钮以添加软件包

![Project package dependencies](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/spm-project-dependancies.png)

4.  点击加号按钮添加软件包

![Plus button](https://npmcn.com/package/%40capgo/capacitor-watch/docs/plus_button.png)

5.  点击 **添加软件包**

![Add local SPM package](https://npmcn.com/package/%40capgo/capacitor-watch/docs/add_watch_sdk.png)

6.  当提示时,选择 **Capgo 监视系统** 并把它加进你的 **监视 App 目标** (不是主要应用)

![Pick target for package](https://npmcn.com/package/%40capgo/capacitor-watch/docs/target.png)

添加后, 您的软件包依赖性应该显示 Capgo WatchSDK :

![SPM finished](https://npmcn.com/package/%40capgo/capacitor-watch/docs/added.png)

### 步骤6: 修复主应用程序的构建

现在,你的主要应用 丢失了Capgo WatchSDK。 我们需要把它添加到主应用程序.

1.  在导航器中选择您的工程( 顶级, 蓝色图标)
2.  转到您的 iOS 应用程序目标
3.  转到 `general`
4.  滚动至 `Frameworks, Libraries, and Embedded Content`
5.  单击加号按钮以添加框架

![Add framework](https://npmcn.com/package/%40capgo/capacitor-watch/docs/add_framework.png)

7.  点击 `CapgoWatchSDK` 框架和单击 `Add`

![Add framework](https://npmcn.com/package/%40capgo/capacitor-watch/docs/add_framework_2.png)

### 步骤6:配置监视应用程序

更新您的 Watch app 主文件以初始化连接 :

**MyApp Watch/MyAppWatch App.swift: 页面存档备份,存于互联网档案馆**

```swift
import SwiftUI
import WatchConnectivity
import CapgoWatchSDK

@main
struct MyAppWatchApp: App {
    init() {
        // Activate the watch connector
        WatchConnector.shared.activate()
    }

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

**MyApp Watch/ ContentView.swift: 页面存档备份,存于互联网档案馆 :**

```swift
import SwiftUI
import CapgoWatchSDK

struct ContentView: View {
    @ObservedObject var connector = WatchConnector.shared

    var body: some View {
        VStack(spacing: 20) {
            // Connection status indicator
            HStack {
                Circle()
                    .fill(connector.isReachable ? Color.green : Color.red)
                    .frame(width: 12, height: 12)
                Text(connector.isReachable ? "Connected" : "Disconnected")
                    .font(.caption)
            }

            // Send message button
            Button("Send to Phone") {
                connector.sendMessage(["action": "buttonTapped", "timestamp": Date().timeIntervalSince1970]) { reply in
                    print("Phone replied: \(reply)")
                }
            }
            .disabled(!connector.isReachable)

            // Display received context
            if let context = connector.receivedContext {
                Text("Last update: \(context["status"] as? String ?? "none")")
                    .font(.caption2)
            }
        }
        .padding()
    }
}
```

你的表应用结构应该是这样的:

![Watch sources added](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-sources-added.png)

### 第7步: 添加监视辅助能力

Watch应用还需要背景能力:

1.  选择您的 **监视 App 目标** xcode 编码
2.  转到 **签名能力( C)** 选项卡
3.  点击 **\+ 能力**
4.  添加 **背景模式**
5.  启用 **远程通知**

![Watch remote notifications capability](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/watch-remote-not.png)

### 第8步: 使用您控制器 App 中的插件

现在在您的 Capacitor app 中设置 JavaScript 侧:

```typescript
import { Watch } from '@capgo/capacitor-watch';

// Check watch connectivity status
async function checkWatchStatus() {
  const info = await Watch.getInfo();
  console.log('Watch supported:', info.isSupported);
  console.log('Watch paired:', info.isPaired);
  console.log('Watch app installed:', info.isWatchAppInstalled);
  console.log('Watch reachable:', info.isReachable);
}

// Listen for messages from watch
Watch.addListener('messageReceived', (event) => {
  console.log('Message from watch:', event.message);
  // Handle the message (e.g., event.message.action === 'buttonTapped')
});

// Listen for messages that need a reply
Watch.addListener('messageReceivedWithReply', async (event) => {
  console.log('Watch asking:', event.message);

  // Send reply back to watch
  await Watch.replyToMessage({
    callbackId: event.callbackId,
    data: { response: 'acknowledged', processed: true }
  });
});

// Listen for connection changes
Watch.addListener('reachabilityChanged', (event) => {
  console.log('Watch reachable:', event.isReachable);
  // Update UI to show connection status
});

// Send data to watch (latest value wins)
async function updateWatchContext(data: Record<string, unknown>) {
  await Watch.updateApplicationContext({ context: data });
}

// Send message to watch (requires watch to be reachable)
async function sendMessageToWatch(data: Record<string, unknown>) {
  await Watch.sendMessage({ data });
}

// Queue data for reliable delivery (even when watch is offline)
async function queueDataForWatch(data: Record<string, unknown>) {
  await Watch.transferUserInfo({ userInfo: data });
}
```

### 第9步:构建和运行

使用 Xcode 中的目标投放来切换您的手机或手表的建筑间:

![Target dropdown](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/target-dropdown.png)

**构建顺序 :**

1.  首先,建造和运行 **iOS 应用程序** 在您的 iPhone 上
2.  然后,建造和运行 **监视 App** 在您的苹果观察中

**重要注释 :**

-   您必须使用真实的设备 - 模拟器不支持 WatchConnectity
-   两个应用程序必须运行双向通信
-   手表应用程序将显示“ 断开连接, 直到手机应用程序激活

* * *

## 交流方法

选择合适的使用方法 :

| 方法 | 使用大小写 | 交付 | 监视必须可以到达 |
| --- | --- | --- | --- |
| `sendMessage()` | 实时互动 | 即时 | 对 |
| `updateApplicationContext()` | 同步应用程序状态 | 最近价值 | 没有 |
| `transferUserInfo()` | 重要数据 | 排队,按顺序 | 没有 |

### 示例:完整的通信流程

```typescript
import { Watch } from '@capgo/capacitor-watch';

class WatchService {
  private isReachable = false;

  async initialize() {
    // Check initial status
    const info = await Watch.getInfo();
    this.isReachable = info.isReachable;

    // Monitor reachability
    Watch.addListener('reachabilityChanged', (event) => {
      this.isReachable = event.isReachable;
    });

    // Handle incoming messages
    Watch.addListener('messageReceived', (event) => {
      this.handleWatchMessage(event.message);
    });

    // Handle request/reply messages
    Watch.addListener('messageReceivedWithReply', async (event) => {
      const reply = await this.processWatchRequest(event.message);
      await Watch.replyToMessage({
        callbackId: event.callbackId,
        data: reply
      });
    });
  }

  async syncAppState(state: Record<string, unknown>) {
    // Always works - queues if watch is unreachable
    await Watch.updateApplicationContext({ context: state });
  }

  async sendInteractiveMessage(data: Record<string, unknown>) {
    if (!this.isReachable) {
      console.log('Watch not reachable, queueing message');
      await Watch.transferUserInfo({ userInfo: data });
      return;
    }
    await Watch.sendMessage({ data });
  }

  private handleWatchMessage(message: Record<string, unknown>) {
    // Process message from watch
    console.log('Watch action:', message.action);
  }

  private async processWatchRequest(message: Record<string, unknown>) {
    // Process and return reply
    return { status: 'ok', timestamp: Date.now() };
  }
}
```

* * *

## SwiftUI 监视 App 示例

### 基本监视 UI

![Example watch UI](https://raw.githubusercontent.com/ionic-team/CapacitorWatch/main/img/example-watchui.png)

### 带有数据显示的高级监视应用程序

```swift
import SwiftUI
import CapgoWatchSDK

struct ContentView: View {
    @ObservedObject var connector = WatchConnector.shared
    @State private var lastMessage = "No messages yet"

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                // Status header
                StatusView(isConnected: connector.isReachable)

                Divider()

                // Action buttons
                Button("Request Data") {
                    connector.sendMessage(["action": "requestData"]) { reply in
                        if let status = reply["status"] as? String {
                            lastMessage = "Got: \(status)"
                        }
                    }
                }
                .buttonStyle(.borderedProminent)
                .disabled(!connector.isReachable)

                Button("Send Tap") {
                    connector.sendMessage(["action": "tap", "time": Date().timeIntervalSince1970])
                }
                .disabled(!connector.isReachable)

                Divider()

                // Message display
                Text(lastMessage)
                    .font(.caption)
                    .foregroundColor(.secondary)
            }
            .padding()
        }
    }
}

struct StatusView: View {
    let isConnected: Bool

    var body: some View {
        HStack {
            Image(systemName: isConnected ? "iphone.radiowaves.left.and.right" : "iphone.slash")
                .foregroundColor(isConnected ? .green : .red)
            Text(isConnected ? "Phone Connected" : "Phone Disconnected")
                .font(.caption)
        }
    }
}
```

## API 密码

-   [`sendMessage(...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-sendmessage)
-   [`updateApplicationContext(...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-updateapplicationcontext)
-   [`transferUserInfo(...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-transferuserinfo)
-   [`replyToMessage(...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-replytomessage)
-   [`getInfo()`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-getinfo)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-getpluginversion)
-   [`addListener('messageReceived', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlistenermessagereceived-)
-   [`addListener('messageReceivedWithReply', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlistenermessagereceivedwithreply-)
-   [`addListener('applicationContextReceived', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlistenerapplicationcontextreceived-)
-   [`addListener('userInfoReceived', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlisteneruserinforeceived-)
-   [`addListener('reachabilityChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlistenerreachabilitychanged-)
-   [`addListener('activationStateChanged', ...)`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-addlisteneractivationstatechanged-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-type-aliases)

为 Capacitor 监视 / 戴 OS 通讯插件 . 提供电话和一对手表之间的双向通讯.

-   **iOS系统**:使用Apple WatchConnectivity框架与Apple Watch通信.
-   **机器人**:使用Google Wear OS Data Layer API(游戏服务-可穿戴)与一台Wear OS手表通信.
-   **网页**: 不支持; 所有方法抛出或返回安全默认值.

### 发送消息(...)

```typescript
sendMessage(options: SendMessageOptions) => Promise<void>
```

向手表发送交互信息. 手表必须能够达到这一点才能取得成功. 用于时间敏感,互动的交流.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[SendMessageOptions](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-sendmessageoptions)` | \- 信息选项 |

**自:** 8.0.0 (单位:千美元)

* * *

### 更新应用程序Context(...)

```typescript
updateApplicationContext(options: UpdateContextOptions) => Promise<void>
```

更新与手表共享的应用程序上下文 . 只保留最近的上下文 - 这覆盖了任何先前的上下文 . 用于同步应用声明表需要显示 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[UpdateContextOptions](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-updatecontextoptions)` | \- 上下文选项 |

**自:** 8.0.0 (单位:千美元)

* * *

### 传输用户信息(...)

```typescript
transferUserInfo(options: TransferUserInfoOptions) => Promise<void>
```

将用户信息传输到手表 . 传输被排队并按顺序交付,即使表目前无法到达. 用于必须可靠交付的重要数据.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[TransferUserInfoOptions](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-transferuserinfooptions)` | \- 用户信息选项 |

**自:** 8.0.0 (单位:千美元)

* * *

### 回复Message(...)

```typescript
replyToMessage(options: ReplyMessageOptions) => Promise<void>
```

答复表上要求答复的信息. 使用此选项来响应信件 Reply 事件 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[ReplyMessageOptions](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-replymessageoptions)` | \- 答复选项,包括召回Id |

**自:** 8.0.0 (单位:千美元)

* * *

### 获取信息 ()

```typescript
getInfo() => Promise<WatchInfo>
```

获取手表连接状态信息.

**回返情况:** `Promise<[WatchInfo](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchinfo)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地 Capacitor 插件版本 .

**回返情况:** `Promise<{ version: string; }>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加Listener( 消息收到",...)

```typescript
addListener(eventName: 'messageReceived', listenerFunc: (event: MessageReceivedEvent) => void) => Promise<PluginListenerHandle>
```

听从表收到的消息.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'messageReceived'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [MessageReceivedEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-messagereceivedevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加 listener( 以 Reply 方式收到消息),..

```typescript
addListener(eventName: 'messageReceivedWithReply', listenerFunc: (event: MessageReceivedWithReplyEvent) => void) => Promise<PluginListenerHandle>
```

听从表里需要回复的信息.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'messageReceivedWithReply'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [MessageReceivedWithReplyEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-messagereceivedwithreplyevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加聆听器( “ 应用程序已接收 ” ,...)

```typescript
addListener(eventName: 'applicationContextReceived', listenerFunc: (event: ContextReceivedEvent) => void) => Promise<PluginListenerHandle>
```

从手表中聆听应用程序上下文更新 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'applicationContextReceived'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [ContextReceivedEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-contextreceivedevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加 listener('userInfoeived',...)

```typescript
addListener(eventName: 'userInfoReceived', listenerFunc: (event: UserInfoReceivedEvent) => void) => Promise<PluginListenerHandle>
```

听从手表的用户信息传输.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'userInfoReceived'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [UserInfoReceivedEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-userinforeceivedevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 可获取性改变 ” ,...)

```typescript
addListener(eventName: 'reachabilityChanged', listenerFunc: (event: ReachabilityChangedEvent) => void) => Promise<PluginListenerHandle>
```

听看表的可达性变化.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'reachabilityChanged'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [ReachabilityChangedEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-reachabilitychangedevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 添加倾听器( “ 激活状态改变 ” ,...)

```typescript
addListener(eventName: 'activationStateChanged', listenerFunc: (event: ActivationStateChangedEvent) => void) => Promise<PluginListenerHandle>
```

听听会话激活状态变化 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'activationStateChanged'` | \- 活动名称 |
| **`listenerFunc`** | `(event: [ActivationStateChangedEvent](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-activationstatechangedevent)) => void` | \- 回调函数 |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-pluginlistenerhandle)>`

**自:** 8.0.0 (单位:千美元)

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 8.0.0 (单位:千美元)

* * *

### 接口

#### 发送信件选项

发送信件到手表的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`data`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 送去表上的数据 必须是可序列的(字符串、数字、布尔、阵列或嵌入对象). |

#### 更新文本选项

更新应用程序上下文的选项.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`context`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 要与手表同步的上下文数据 。 只有最新的上下文被保存 - 以前的值被覆盖 . |

#### 传输用户信息选项

传输用户信息选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`userInfo`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 要传输的用户信息数据 。 传输排队并按顺序交付. |

#### 回信选项

对手表中的消息进行回复的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`callbackId`** | `string` | 在信件Reply事件收到回调ID . |
| **`data`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 回复数据发回表. |

#### 监视信息

关于Watch/Wear OS连接状态的信息.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isSupported`** | `boolean` | 此设备是否支持手表通信 API 。 - iOS:在iPad上作假;在WatchConnectity可用时iPhone上作真. - Android:在提供Google Play Services并配有Wear OS支持时为真;否则为假. - Web:总是虚假的. |
| **`isPaired`** | `boolean` | 手表目前是否对齐/连接 。 - iOS:苹果卫视是否与这个iPhone配对. -Android:目前是否至少一个Wear OS节点连接. |
| **`isWatchAppInstalled`** | `boolean` | 是否安装了表伴应用程序 。 - iOS:配对的Apple Watch是否安装了相伴应用程序. - Android:至少一个连接的Wear OS节点能否被达到(用作代用). |
| **`isReachable`** | `boolean` | 手表目前是否可以直接发送 . |
| **`activationState`** | `number` | 当前会话激活状态 。 - iOS:0=未激活,1=不活动,2=已激活(WCSession Activation State). -Android:2 当一个穿戴OS节点连接,0 否则. |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 信件收到事件

收到信息的事件数据.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`message`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 从手表收到的消息数据. |

#### 信件以回信方式收到

需要回复的信息的事件数据.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`message`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 从手表收到的消息数据. |
| **`callbackId`** | `string` | 在回复ToMessage()时使用的回调ID . |

#### 收到的活动

用于应用程序上下文更新的事件数据 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`context`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 从手表收到的上下文数据. |

#### 用户信息接收事件

用户信息传输事件数据.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`userInfo`** | `[WatchMessageData](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-watchmessagedata)` | 从手表收到的用户信息数据. |

#### 可达到性 更改事件

可达到性变化的事件数据.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`isReachable`** | `boolean` | 手表现在能否到达 . |

#### 激活 变相事件

激活状态变化的事件数据 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`state`** | `number` | 新激活状态. 0=未激活,1=不活动,2=已激活 |

### 类型异名

#### 监视MessageData

可以在iPhone和Apple Watch之间发送的数据. 数值必须是可序列的(字符串、数字、布尔、数组或嵌入对象).

`[Record](https://npmcn.com/package/%40capgo/capacitor-watch/#readme-record)<string, unknown>`

#### 记录

构造 T 类型 K 的一组属性类型

`{ [P in K]: T; }`

## 贷项

基于加强的WatchConnectity执行: [观测增强](https://github.com/macsupport/CapacitorWatchEnhanced)。 。 。 . 谁是叉子 [电容监视器](https://github.com/ionic-team/CapacitorWatch)

## 常见问题

### @capgo/capacitor-watch 是什么？

具有双向消息支持的 Apple Watch 通信电容插件

### 如何安装 @capgo/capacitor-watch？

在项目目录运行 npm install @capgo/capacitor-watch，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-watch 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-watch 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-watch 可以商用吗？

@capgo/capacitor-watch 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-watch 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-watch 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,193 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-watch 还在维护吗？

最新版本 8\.1\.19 发布于 2026/11/02（6 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 42 个；首次发布于 2026/01/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。