Creating a watchOS App

GitHub

__CAPGO_KEEP_11__

{"targetLanguage":"Simplified Chinese"}

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

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

项目结构概览

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

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

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

导航到您的 Capacitor 项目的 ios/App 文件夹
打开 App.xcworkspace （不是”，）通过双击它 .xcodeproj等待 Xcode 索引项目
注意

步骤 2：添加 watchOS 目标

在 Xcode 中，转到 文件 → 新建 → 目标…
在模板选择器中：
- 选择 watchOS 顶部的标签
- 选择 App
- 点击 下一步
配置您的手表应用：
- 产品名称: MyWatch （或您的偏好名称）
- 团队: 选择您的Apple Developer团队
- 组织标识符: 应该与您的iOS应用（例如 app.capgo)
- 包标识符: 将自动生成（例如 app.capgo.myapp.watchkitapp)
- 语言: Swift
- 安全回算器: SwiftUI
- 笔记类型不支付帮常用的常用iOS常用器
- 开始 安全提示回算器 不会会
- 安全提示回算器 不会会 点击了
点击了完成
当提示“激活 ‘MyWatch’ 方案？”时，点击激活

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

在项目导航器（左侧边栏）中，选择您的项目（顶部蓝色图标）
从目标列表中选择您的手表目标（例如，“MyWatch”）
转到常规选项卡：
- 显示名称: 应用程序图标下显示的名称（例如，“My App”)
- 应用程序标识符: 应该以 .watchkitapp
- 版本: 匹配您的iOS应用程序版本
- 构建: 匹配您的iOS应用程序构建号
前往 签名 & Capabilities 选项卡:
- : 启用 自动管理签名
- 选择您的团队
- Xcode将自动创建配置文件
设置 部署信息:
- 最小部署: watchOS 9.0或更高

步骤 4: 使用 Swift Package Manager 添加 CapgoWatchSDK

CapgoWatchSDK提供一个 WatchConnector 用于通信的

类。 在 Xcode 中，转到“文件”→“添加包依赖项…”

在搜索栏中输入：

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

按 Enter 并等待 Xcode 获取包
配置包：
- 依赖规则： “到下一个重大版本” 与 “8.0.0”
- 点击 添加包
选择要添加的产品：
- 重要提示：只选择 CapgoWatchSDK
- 确保它已添加到你的 watch target (e.g., “MyWatch”), not the iOS app
- Click Add Package

Step 5: Implement the Watch App

Now let’s create the watch app code. Replace the auto-generated files with the following:

5.1 创建应用入口点

编辑 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

您的 iOS 应用程序还需要 WatchConnectivity 能力。

在项目导航器中，选择您的项目
选择你的 iOS App目标 (不是手表目标)
转到 签名 & 能力 选项卡
点击 + 能力
搜索并添加 WatchConnectivity (如果可用)或它可能会自动添加

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)”）
点击运行或按 Cmd + R
The iOS Simulator will launch with both iPhone and Apple Watch

在物理设备上运行

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

第 8 步：测试通信

从 iPhone (Capacitor) 到 Watch

在您的 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!' }
  });
}

从 Watch 到 iPhone

watch 应用使用 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 上打开手表应用 → 我的手表 → 滚动找到您的应用 → 打开开关

未接收到的消息

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

会话未激活

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

CapgoWatchSDK 构建错误

确保该包添加到 watch目标而不是 iOS 目标
清理构建文件夹： Product → Clean Build Folder (Cmd + Shift + K)
Reset package caches: File → Packages →

Simulator Issues

Reset simulators: Device →
Ensure iOS and watchOS simulators are compatible pairs
需要确保iOS和watchOS模拟器是兼容的对

需要同时运行两个模拟器才能进行通信

API - 完整的API文档
通信模式 - 使用每种方法的时机
示例应用 - 全功能的工作示例

从创建watchOS应用程序继续

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