创建一个watchOS应用

GitHub

可复制

本指南将指导您从零开始创建一个 watchOS 配件应用程序，包括在 Xcode 中设置项目、集成 CapgoWatchSDK 和使用 SwiftUI 构建功能齐全的智能手表应用。

对于 智能手表，请使用创建 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 项目

Navigate to your Capacitor project’s ios/App folder
文件夹 App.xcworkspace 打开 .xcodeproj(不是
)通过双击它

步骤 2：添加 watchOS 目标

步骤 2：添加 watchOS 目标 在 Xcode 中，转到
文件 → 新建 → 目标…
- 在模板选择器中：选择 watchOS
- 顶部选项卡选择
- Click Next
Configure your watch app:
- Product Name: MyWatch (or your preferred name)
- Team: Select your Apple Developer team
- Organization Identifier: Should match your iOS app (e.g., app.capgo)
- Bundle Identifier: Will be auto-generated (e.g., app.capgo.myapp.watchkitapp)
- Language: Swift
- 用户界面: SwiftUI
- 手表应用类型: App (不适用于现有iOS应用)
- 取消 包含通知场景 (除非您需要)
- 取消 包含复杂情景 (除非您需要)
点击完成
当提示“激活 ‘MyWatch’ 方案？”时，点击激活

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

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

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

CapgoWatchSDK 提供用于通信的 WatchConnector 类

在 Xcode 中，转到 文件 → 添加包依赖项...

In 搜索栏中，输入：

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

按下 Enter，等待 Xcode 下载包。
按 Enter 并等待 Xcode 获取包
- 配置包依赖规则
- Click 点击
添加包
- 选择要添加的产品：重要提示 CapgoWatchSDK
- : 只选择 watch 目标 例如，“我的手表”（MyWatch），而不是iOS应用
- 点击 添加包

步骤 5：实现 Watch App

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

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()
        }
    }
}

上下文：Capgo营销网站。角色：UI标签。见于：页面代理/[slug].astro。消息键`agents_page_copy_label`（代理页面复制标签）。

编辑 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()
}

标题：5.2 创建主视图

上下文：关于Capgo页面。角色：UI标签。见于：页面about.astro。消息键`about_how_step_label`（关于如何步骤标签）。

标题：步骤6：为WatchConnectivity配置iOS应用
选择您的 iOS App目标 (不是手表目标)
转到 签名和功能 选项卡
点击 +功能
查找并添加 WatchConnectivity (如果可用)或它可能会自动添加

Capacitor 插件会自动处理 iOS 端，但确保您的 Info.plist 中有：

<key>WKCompanionAppBundleIdentifier</key>
<string>app.capgo.myapp.watchkitapp</string>

第 7 步：构建和运行

在模拟器上运行

从 Xcode 窗口顶部的方案选择器中选择您的 watch 方案
选择一个模拟器：
- 点击设备选择器旁边的按钮
- 选择一个 Apple Watch 模拟器（例如“Apple Watch Series 9 (45mm)”）
点击运行点击按钮（▶️）或按 Cmd + R
iOS模拟器将同时启动iPhone和Apple Watch

在物理设备上运行

连接您的iPhone通过USB
确保您的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

手表应用使用 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()

故障排除

手表应用未在手表上显示

确保 bundle ID 正确关联 (手表应用 bundle ID 应该是 iOS 应用 bundle ID +) .watchkitapp)
检查两款应用都使用相同的团队签名
在物理设备上：在 iPhone 上打开手表应用 → 我的手表 → 滚动找到您的应用 → toggle 开启

未接收消息

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

“会话未激活”错误

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

CapgoWatchSDK 构建错误

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

模拟器问题

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

下一步

创建 Wear OS 应用适用于 Android watches
API 参考文档 - 完整的 API 文档
通信模式 - 使用每种方法的时机
示例应用 - 全功能工作示例

从创建 watchOS 应用程序继续

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