ios-watchos

ios-watchos

用途

此技能支持使用 Swift 和 Apple 框架开发 watchOS 应用，重点包括用于复杂功能的 WidgetKit、用于设备同步的 WatchConnectivity、用于界面的 SwiftUI、用于访问健康数据的 HealthKit，以及用于自定义功能的 OpenClaw Watch 扩展。

适用场景

如果要构建需要动态复杂功能（例如更新时间线）、从 iOS 设备实时传输数据、在 Watch 上创建自定义 SwiftUI 布局、查询锻炼等健康指标，或集成 OpenClaw 以扩展功能的 watchOS 应用，请使用此技能。适用于健身追踪应用或基于通知的工具等场景。

主要功能

• WidgetKit 复杂功能：创建基于时间线的更新，例如使用 TimelineProvider 每 15 分钟刷新一次数据。
• WatchConnectivity：建立会话，在 iOS 和 watchOS 之间发送和接收数据，并处理每条消息最大 100KB 的传输。
• Watch 上的 SwiftUI：使用 NavigationView 和 List 等组件构建响应式界面，并针对小屏幕（例如 44mm 显示屏）进行优化。
• HealthKit：访问 HKWorkout 和 HKQuantityTypeStepCount 等健康数据类型，并通过后台传送实时更新。
• OpenClaw Watch 扩展：利用自定义 API 增强应用功能，并通过 $OPENCLAW_API_KEY 进行身份验证，以确保连接安全。

使用模式

遵循以下模式以有效实现功能：

1. 复杂功能：在 Xcode 中设置 WidgetKit 扩展，实现 TimelineProvider 子类，并使用 getTimeline(in:completion:) 生成条目。示例：在提供器中返回一个包含日期和视图的 TimelineEntry 对象数组。
2. 集成 HealthKit：请求特定数据类型的授权，然后查询样本。示例：检查权限后，使用 HKSampleQuery 获取锻炼数据。
3. 常见模式：使用 WatchConnectivity 同步数据；在 AppDelegate 中激活 WCSession，并在 didReceiveMessage 中处理传入消息。
4. 集成 OpenClaw：使用 API 密钥初始化扩展，并在委托中处理事件。示例：在应用启动流程中调用 OpenClawSession.shared.start(with: $OPENCLAW_API_KEY)。
5. 具体用法示例 1：为健身应用构建复杂功能——创建一个 TimelineProvider，查询 HealthKit 中的步数并每小时更新一次：let entry = TimelineEntry(date: Date(), stepCount: 500); provider.getTimeline(in: context, completion: { timeline in ... })。
6. 具体用法示例 2：将锻炼数据从 iOS 同步到 Watch——在 iOS 应用中使用 WCSession.default.sendMessage(["workoutID": "123"], replyHandler: nil)，并在 Watch 应用的 session(didReceiveMessage: handler) 中处理消息。

常用命令/API

• Xcode 命令：使用 xcodebuild -scheme WatchAppExtension -destination 'platform=watchOS Simulator,name=Apple Watch Series 6' -configuration Debug 构建并运行 watchOS 应用。在 CI/CD 流水线中使用此命令。
• WidgetKit API：实现一个简单的 TimelineProvider：class MyProvider: TimelineProvider { func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) { let entry = SimpleEntry(date: Date()); completion(entry) } }。
• WatchConnectivity API：使用 WCSession.default.activate(); 激活会话；发送数据：WCSession.default.sendMessage(["key": "value"], replyHandler: nil, errorHandler: nil)。
• HealthKit API：请求授权：let typesToRead = Set([HKObjectType.workoutType()]); HKHealthStore().requestAuthorization(toShare: nil, read: typesToRead) { granted, error in if granted { // Proceed } }。
• OpenClaw API：使用身份验证进行初始化：let session = OpenClawSession(apiKey: ProcessEnv.get("OPENCLAW_API_KEY")); session.connect(endpoint: "wss://api.openclaw.com/watch"); 在 session.delegate.didReceiveData 中处理响应。
• 配置格式：为 OpenClaw 使用 JSON 配置：{ "apiKey": "$OPENCLAW_API_KEY", "endpoint": "wss://api.openclaw.com/watch", "watchID": "device-uuid" }。使用 let config = try JSONDecoder().decode(OpenClawConfig.self, from: data) 加载配置。

集成说明

在 Xcode 中添加 watchOS 目标以集成此技能：前往 File > New > Target > watchOS > Watch App，然后通过组功能将其关联到 iOS 应用。对于 HealthKit，在项目设置中启用 HealthKit 功能，并将 NSHealthShareUsageDescription 键添加到 Info.plist。使用 WatchConnectivity 时，请确保 iOS 和 watchOS 应用共享相同的 App Group 权限。对于 OpenClaw，在构建脚本中设置 $OPENCLAW_API_KEY 环境变量（例如，export OPENCLAW_API_KEY=your_key），并通过 Swift Package Manager 导入 OpenClaw SDK：.package(url: "https://github.com/openclaw/sdk.git", from: "1.0.0")。使用模拟器测试集成：在 Apple Watch Simulator 上运行 watchOS 应用，并使用 Console 应用检查数据流和日志。

错误处理

主动处理错误：对于 WidgetKit，检查 getTimeline 中的时间线错误，并在失败时重试（例如，如果 context 无效，则记录日志并返回空时间线）。对于 WatchConnectivity，捕获 .notReachable 等 WCSession 错误，并将消息排队以供稍后发送。在 HealthKit 中，查询前验证授权状态——例如，如果出现 HKError.Code.errorAuthorizationDenied，则通过带有重试按钮的 UIAlertController 提示用户。对于 OpenClaw，解析 API 错误（例如，401 Unauthorized），并在 $OPENCLAW_API_KEY 过期时刷新它。对 API 调用使用 Swift 的 try-catch：do { try OpenClawSession.shared.connect() } catch let error as OpenClawError { print(error.localizedDescription); retry after delay }。使用 os_log 记录所有错误以便调试。

图关系

• 相关项：mobile 集群（例如，与 ios 技能共享标签以支持跨平台功能）。
• 链接至：通过 WatchConnectivity 实现 iOS 与 Watch 同步的 ios 技能。
• 关联方式：watchos 标签、与健身相关技能的 healthkit 集成，以及用于自定义扩展的 openclaw-watch。