创建一个 watchOS 应用

GitHub

复制一个包含安装步骤和本插件的完整Markdown指南的设置提示。

本指南将指导您从零开始创建一个 watchOS 配套应用

For 对于Wear OS , 请使用创建 Wear OS 应用

。

在开始之前，请确保您有：

Xcode 15 或更高版本 （从 Mac App Store 下载）
macOS Sonoma 或更高版本 （用于最新的 watchOS SDK）
一个现有的 Capacitor iOS 项目 （运行 npx cap add ios 如果您还没有）
Apple Developer 账户 （开发环境下免费账户即可）

项目结构概览

完成本指南后，项目将具有以下结构：

目录ios/
- 目录App/
  - 目录App/ (您的主 iOS 应用)
    …
  - App.xcodeproj
  - App.xcworkspace (使用此文件打开项目)
  - Podfile
- 目录MyWatch/ (新手表应用)
  - 目录MyWatch/ (手表应用源码)
    MyWatchApp.swift
    ContentView.swift
    目录Assets.xcassets/
    …
  - MyWatch.xcodeproj

步骤 1：在 Xcode 中打开您的 iOS 项目

导航到您的 Capacitor 项目的 ios/App 文件夹
打开 App.xcworkspace (不是 .xcodeproj)通过双击它
等待 Xcode 索引项目

步骤 2：添加 watchOS 目标

在 Xcode 中，转到 文件 → 新建 → 目标…
在模板选择器中：
- 选择 watchOS 顶部选项卡
- 选择 应用程序
- 点击 下一步
配置您的手表应用：
- 产品名称: MyWatch (或您的喜好名称)
- 团队: 选择您的Apple Developer团队
- 组织标识符: 应该与您的iOS应用匹配（例如， app.capgo)
- 包标识符: 将自动生成（例如， app.capgo.myapp.watchkitapp)
- 语言: Swift
- 用户界面: SwiftUI
- Watch 应用类型: App (非现有 iOS 应用)
- 取消 包含通知场景 (除非您需要)
- 取消 包含复杂情景 (除非您需要)
点击完成
当弹出“激活‘MyWatch’方案？”提示时，点击激活

步骤 3：配置手表应用设置

步骤 3：配置手表应用设置
在项目导航器（左侧边栏）中，选择您的项目（顶部蓝色图标)
去到应用设置转到常规
- 选项卡：显示名称
- :应用图标下显示的名称（例如，“My App”）: 应该以 .watchkitapp
- Version: 与 iOS 应用程序版本匹配
- Buildcontext
前往 : 与 iOS 应用程序构建号匹配 Go to
- Enable tab:
- Enable 自动管理签名
- Xcode将自动创建配置文件
设置 Capgo将自动为您创建配置文件:
- 部署信息最小部署

: watchOS 9.0或更高

步骤 4: 添加 CapgoWatchSDK via Swift Package Manager WatchConnector CapgoWatchSDK提供了一个用于通信的

类 在Xcode中，前往

文件→添加包依赖项…

https://github.com/Cap-go/capacitor-watch.git

按 Enter 并等待 Xcode 获取包
配置包:
- 依赖规则: “到下一个重大版本”与“8.0.0”
- 点击 添加包
选择要添加的产品:
- 重要提示: 只选择 CapgoWatchSDK
- 确保它添加到你的 watch目标 例如（“MyWatch”），而不是iOS应用
- 点击 添加包

步骤5：实现手表应用

现在让我们创建一个手表应用 code. 将以下自动生成的文件替换掉。

现在让我们创建手表应用 __CAPGO_KEEP_0__。用以下文件替换自动生成的文件：

编辑 MyWatch/MyWatchApp.swift:

import SwiftUI
import CapgoWatchSDK

@main
struct MyWatchApp: App {
    init() {
        // Activate WatchConnectivity when app launches
        WatchConnector.shared.activate()
    }

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

5.2 创建主视图

编辑 MyWatch/ContentView.swift:

import SwiftUI
import CapgoWatchSDK

struct ContentView: View {
    // Observe the WatchConnector for automatic UI updates
    @ObservedObject var connector = WatchConnector.shared

    // Local state
    @State private var messageText = ""
    @State private var statusMessage = "Ready"

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                // Connection Status
                ConnectionStatusView(connector: connector)

                Divider()

                // Message Input
                TextField("Message", text: $messageText)
                    .textFieldStyle(.roundedBorder)

                // Send Buttons
                HStack {
                    Button("Send") {
                        sendMessage()
                    }
                    .disabled(!connector.isReachable || messageText.isEmpty)

                    Button("Request") {
                        sendWithReply()
                    }
                    .disabled(!connector.isReachable || messageText.isEmpty)
                }

                Divider()

                // Status
                Text(statusMessage)
                    .font(.caption)
                    .foregroundColor(.secondary)

                // Last Received Message
                if !connector.lastMessage.isEmpty {
                    VStack(alignment: .leading) {
                        Text("Last Message:")
                            .font(.caption)
                            .foregroundColor(.secondary)
                        Text(formatMessage(connector.lastMessage))
                            .font(.caption2)
                    }
                    .frame(maxWidth: .infinity, alignment: .leading)
                }
            }
            .padding()
        }
    }

    private func sendMessage() {
        connector.sendMessage(["text": messageText, "timestamp": Date().timeIntervalSince1970])
        statusMessage = "Message sent"
        messageText = ""
    }

    private func sendWithReply() {
        connector.sendMessage(["text": messageText, "needsReply": true]) { reply in
            DispatchQueue.main.async {
                statusMessage = "Reply: \(formatMessage(reply))"
            }
        }
        messageText = ""
    }

    private func formatMessage(_ message: [String: Any]) -> String {
        message.map { "\($0.key): \($0.value)" }.joined(separator: ", ")
    }
}

// Separate view for connection status
struct ConnectionStatusView: View {
    @ObservedObject var connector: WatchConnector

    var body: some View {
        HStack {
            Circle()
                .fill(connector.isReachable ? Color.green : Color.red)
                .frame(width: 12, height: 12)

            Text(connector.isReachable ? "Connected" : "Disconnected")
                .font(.headline)

            Spacer()

            if connector.isActivated {
                Image(systemName: "checkmark.circle.fill")
                    .foregroundColor(.green)
            }
        }
    }
}

#Preview {
    ContentView()
}

第 6 步：配置 iOS 应用程序以支持 WatchConnectivity

Section titled “第 6 步：配置 iOS 应用程序以支持 WatchConnectivity”

您的 iOS 应用程序还需要 WatchConnectivity 能力。
选择您的 iOS App目标 （不是手表目标）
前往 签名与能力 选项卡
点击 + 能力
查找并添加 WatchConnectivity The __CAPGO_KEEP_0__ 插件会自动处理 iOS 端，但确保您的 Info.plist 有：
The Capacitor 插件会自动处理 iOS 端，但确保您的 Info.plist 文件包含：
```
<key>WKCompanionAppBundleIdentifier</key>
<string>app.capgo.myapp.watchkitapp</string>
```

第 7 步：构建和运行

在模拟器上运行

从 Xcode 窗口顶部的方案选择器中选择您的 watch 方案
选择 Apple Watch 模拟器：
- 点击设备选择器
- 选择 Apple Watch 模拟器（例如，“Apple Watch Series 9 (45mm)”）
点击运行在 Capgo UI 中，选择 Apple Watch 模拟器（例如，“Apple Watch Series 9 (45mm)”） Cmd + R
在 Capgo UI 中，选择 Apple Watch 模拟器（例如，“Apple Watch Series 9 (45mm)”）

在物理设备上运行

通过USB连接您的iPhone
确保您的Apple Watch与iPhone配对
选择您的watch方案
从设备列表中选择您的物理Apple Watch
点击运行
首次使用：您可能需要在两台设备上信任您的计算机

步骤 8：测试通信

从 iPhone (Capacitor) 到手表

在您的 Capacitor 应用程序中：

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

// Check connection
const info = await CapgoWatch.getInfo();
console.log('Watch reachable:', info.isReachable);

// Send a message
if (info.isReachable) {
  await CapgoWatch.sendMessage({
    data: { action: 'update', value: 'Hello from iPhone!' }
  });
}

从手表到 iPhone

步骤 8:测试通信 WatchConnector:

// Send message (fire and forget)
WatchConnector.shared.sendMessage(["action": "buttonTapped"])

// Send message with reply
WatchConnector.shared.sendMessage(["request": "getData"]) { reply in
    print("Got reply: \(reply)")
}

iPhone消息处理

// Listen for messages from watch
await CapgoWatch.addListener('messageReceived', (event) => {
  console.log('Message from watch:', event.message);
  // { action: 'buttonTapped' }
});

// Handle messages that need a reply
await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
  console.log('Request from watch:', event.message);

  // Send reply back
  await CapgoWatch.replyToMessage({
    callbackId: event.callbackId,
    data: { status: 'success', items: ['item1', 'item2'] }
  });
});

高级：自定义委托

如果您需要更多控制，请实现 WatchConnectorDelegate:

import SwiftUI
import CapgoWatchSDK

class WatchHandler: WatchConnectorDelegate {
    func didReceiveMessage(_ message: [String: Any]) {
        print("Received: \(message)")
        // Handle incoming message
    }

    func didReceiveMessageWithReply(_ message: [String: Any],
                                     replyHandler: @escaping ([String: Any]) -> Void) {
        print("Received request: \(message)")
        // Process and send reply
        replyHandler(["status": "processed"])
    }

    func didReceiveApplicationContext(_ context: [String: Any]) {
        print("Context updated: \(context)")
    }

    func didReceiveUserInfo(_ userInfo: [String: Any]) {
        print("User info received: \(userInfo)")
    }

    func reachabilityDidChange(_ isReachable: Bool) {
        print("Reachability changed: \(isReachable)")
    }

    func activationDidComplete(with state: WCSessionActivationState) {
        print("Activation completed: \(state.rawValue)")
    }
}

// In your app setup:
let handler = WatchHandler()
WatchConnector.shared.delegate = handler
WatchConnector.shared.activate()

故障排除

手表应用未在手表上显示

确保包ID正确相关（手表应用包ID应为iOS应用包ID + .watchkitapp)
确保两款应用程序都使用相同的团队签名
物理设备上：在iPhone上打开Watch应用程序 → 我的Watch → 滚动找到您的应用程序 → toggle ON

未接收消息

验证两款应用程序都启用了WCSession
检查 isReachable 在发送消息之前
为了保证消息的可靠传递，使用 transferUserInfo 而不是 sendMessage
确保在另一台设备发送消息之前注册了监听器

“会话未激活”错误

立即呼叫 WatchConnector.shared.activate() 在应用程序生命周期的早期阶段
在 iOS 上，插件会自动激活 - 确保插件已导入
检查 iOS 目标中是否添加了 WatchConnectivity 能力

CapgoWatchSDK 构建错误

确保包添加到 watch目标而不是 iOS 目标
清理构建文件夹： 产品 → 清理构建文件夹 ( Cmd + Shift + K )
重置包缓存： 文件 → 包 → 重置包缓存

模拟器问题

重置模拟器： 设备 → 擦除所有内容和设置
确保 iOS 和 watchOS 模拟器是兼容的对
两台模拟器都需要运行才能进行通信

下一步

创建 Wear OS 应用为 Android 手表
API 参考文档 API 文档
通信模式每种模式何时使用
示例应用完整工作示例

继续从创建 Apple Watch 应用

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