Back to Details

create-watchos-version

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create watchOS Version

创建watchOS版本

Analyzes existing Apple platform projects and creates detailed, phased implementation plans for watchOS apps that are elegant, top-tier experiences—not naive skins of the parent app.
分析现有的苹果平台项目，为watchOS应用制定详细的分阶段实施计划，打造优雅、顶级的使用体验——而非简单照搬主应用的界面。

Workflow

工作流程

  1. Project Discovery - Analyze project structure, patterns, architecture
  2. Feature Mapping - Identify watchOS-suitable features and priorities
  3. API Compatibility - Search web for current watchOS API availability
  4. Architecture Planning - Design watchOS-specific architecture
  5. Plan Generation - Create phased plan with warnings and alternatives
  6. User Review - Present plan for approval before implementation
  1. 项目发现 - 分析项目结构、模式、架构
  2. 功能映射 - 识别适合watchOS的功能及优先级
  3. API兼容性 - 查阅最新的watchOS API可用性
  4. 架构规划 - 设计watchOS专属架构
  5. 计划生成 - 创建带有警告和替代方案的分阶段计划
  6. 用户审核 - 在实施前提交计划供用户批准

Phase 1: Project Discovery

第一阶段：项目发现

Scan project root for:
├── App Architecture (SwiftUI, UIKit, AppKit, hybrid)
├── Data Layer (Core Data, SwiftData, Realm, custom)
├── Networking (URLSession, Alamofire, custom)
├── State Management (ObservableObject, TCA, Redux-like)
├── Navigation (NavigationStack, Coordinator)
├── Shared Frameworks (SPM packages, shared targets)
├── Assets (colors, images, SF Symbols)
├── Existing Watch Target (if any)
└── Minimum iOS Version (affects watchOS targeting)
Key files: 
*.xcodeproj
, 
Package.swift
, 
Info.plist
, App entry points, ViewModels, Models.
扫描项目根目录，查找以下内容：
├── 应用架构（SwiftUI, UIKit, AppKit, 混合架构）
├── 数据层（Core Data, SwiftData, Realm, 自定义）
├── 网络模块（URLSession, Alamofire, 自定义）
├── 状态管理（ObservableObject, TCA, 类Redux架构）
├── 导航（NavigationStack, Coordinator）
├── 共享框架（SPM包、共享Target）
├── 资源文件（颜色、图片、SF Symbols）
├── 现有Watch Target（若存在）
└── 最低iOS版本（影响watchOS目标版本）
关键文件：
*.xcodeproj
, 
Package.swift
, 
Info.plist
, 应用入口文件, ViewModels, Models。

Phase 2: Feature Mapping

第二阶段：功能映射

Glanceable (High Priority): Status displays, counters, progress, recent items, quick stats
Quick Actions (High Priority): Single-tap toggles, shortcuts, haptic confirmations
Complications/Widgets (Critical): Map data to WidgetKit families—accessoryCircular, accessoryRectangular, accessoryInline, accessoryCorner. Consider Smart Stack relevance.
Background: HealthKit integration, background refresh, Watch Connectivity sync
Defer/Exclude: Complex data entry, long-form content, sustained screen time features
快速查看类（高优先级）：状态展示、计数器、进度条、最近项、快速统计
快捷操作类（高优先级）：单触开关、快捷方式、触觉反馈确认
复杂功能/小组件（关键）：将数据映射到WidgetKit组件类型——accessoryCircular、accessoryRectangular、accessoryInline、accessoryCorner。需考虑智能堆叠的相关性。
后台功能：HealthKit集成、后台刷新、Watch Connectivity同步
延迟/排除：复杂数据录入、长文本内容、长时间亮屏功能

Phase 3: API Compatibility

第三阶段：API兼容性

CRITICAL: Always search web for current watchOS docs before finalizing. APIs change frequently.
Search: 
[FrameworkName] watchOS availability site:developer.apple.com
关键提示：在最终确定前务必查阅最新的watchOS文档，API更新频繁。
搜索格式：
[FrameworkName] watchOS availability site:developer.apple.com

Quick Reference

快速参考

Available: SwiftUI, SwiftData (10+), WidgetKit (9+), HealthKit, WorkoutKit, CoreLocation (limited), WatchConnectivity, CloudKit, CoreMotion, AVFoundation (audio), CoreBluetooth, Combine, Swift Concurrency
Unavailable/Limited: UIKit, WebKit, MapKit (limited), CoreImage (limited), ARKit, RealityKit, StoreKit (limited), Background URLSession (limited)
See 
references/api-compatibility.md
for detailed compatibility matrix.
可用：SwiftUI, SwiftData（10+）, WidgetKit（9+）, HealthKit, WorkoutKit, CoreLocation（有限支持）, WatchConnectivity, CloudKit, CoreMotion, AVFoundation（音频）, CoreBluetooth, Combine, Swift Concurrency
不可用/有限支持：UIKit, WebKit, MapKit（有限支持）, CoreImage（有限支持）, ARKit, RealityKit, StoreKit（有限支持）, Background URLSession（有限支持）
详细兼容性矩阵请查看
references/api-compatibility.md
。

Phase 4: Architecture

第四阶段：架构设计

Version Targeting

版本对应关系

iOS 16+ → watchOS 9+  (WidgetKit complications)
iOS 17+ → watchOS 10+ (SwiftData, Smart Stack)
iOS 18+ → watchOS 11+ (Live Activities on Watch)
iOS 16+ → watchOS 9+ （WidgetKit复杂功能）
iOS 17+ → watchOS 10+（SwiftData、智能堆叠）
iOS 18+ → watchOS 11+（Watch端实时活动）

Structure

项目结构

Shared/
├── Models/           # Pure Swift, shared via target membership
├── Services/         # Platform-agnostic logic
└── Utilities/

WatchApp/
├── App.swift
├── Views/
├── ViewModels/
├── Complications/
└── WatchConnectivity/
Shared/
├── Models/           # 纯Swift代码，通过Target成员共享
├── Services/         # 平台无关逻辑
└── Utilities/

WatchApp/
├── App.swift
├── Views/
├── ViewModels/
├── Complications/
└── WatchConnectivity/

Design Principles

设计原则

  1. Glanceability - Visible within 2 seconds
  2. Minimal Interaction - 1-3 taps max
  3. Context Awareness - Time, location, activity
  4. Battery Conscious - Efficient refresh, TimelineSchedule
  5. Haptic Feedback - Confirm actions appropriately
  1. 快速可读性 - 2秒内可获取信息
  2. 最少交互 - 最多1-3次点击
  3. 情境感知 - 时间、位置、活动状态
  4. 电池友好 - 高效刷新、TimelineSchedule
  5. 触觉反馈 - 适当为操作添加确认反馈

SwiftUI Gotchas

SwiftUI注意事项

  • Avoid nested TabViews (memory leaks)
  • Use TimelineSchedule for efficient metric updates
  • Check 
    isLuminanceReduced
    to reduce work when dimmed
  • Don't use data-driven high-frequency UI refreshes
  • 避免嵌套TabViews（内存泄漏）
  • 使用TimelineSchedule实现高效指标更新
  • 检查
    isLuminanceReduced
    以在屏幕变暗时减少工作负载
  • 避免数据驱动的高频UI刷新

Phase 5: Plan Generation

第五阶段：计划生成

Use template in 
references/plan-template.md
to generate:
  1. Executive Summary
  2. ⚠️ API Compatibility Warnings table
  3. Phased implementation tasks
  4. Testing checklist
使用
references/plan-template.md
中的模板生成：
  1. 执行摘要
  2. ⚠️ API兼容性警告表格
  3. 分阶段实施任务
  4. 测试清单

Phase 6: User Review

第六阶段：用户审核

Present plan and ask for approval before implementing:
"I've analyzed your project and created a watchOS plan. Before proceeding:
  1. API Warnings: [N] APIs unavailable—alternatives documented.
  2. Recommended Features: [list] prioritized for Watch.
  3. Scope: [N] phases.
Proceed with implementation, or adjust the plan?"
Do not implement until user approves.
提交计划并在实施前请求用户批准：
"我已分析您的项目并创建了watchOS实施计划。在开始前：
  1. API警告：有[N]个API不可用——已记录替代方案。
  2. 推荐功能：[列表]为Watch端优先开发功能。
  3. 范围：共[N]个阶段。
是否继续实施，或需要调整计划？"
获得用户批准前请勿实施。

Best Practices Reference

最佳实践参考

Watch Connectivity

Watch Connectivity

swift
guard WCSession.default.activationState == .activated else { return }
// sendMessage: immediate, requires reachability
// transferUserInfo: queued, guaranteed
// transferCurrentComplicationUserInfo: complication priority
swift
guard WCSession.default.activationState == .activated else { return }
// sendMessage: 即时传输，要求设备在线
// transferUserInfo: 队列传输，保证送达
// transferCurrentComplicationUserInfo: 复杂功能优先传输

Complications

复杂功能

swift
// Use appropriate reload policy
Timeline(entries: entries, policy: .after(nextUpdateDate))
// Use .never for static complications
swift
// 使用合适的重载策略
Timeline(entries: entries, policy: .after(nextUpdateDate))
// 静态复杂功能使用.never

Battery Efficiency

电池效率

  • Timeline-based over active refresh
  • Check 
    isLuminanceReduced
  • Batch Watch Connectivity transfers
  • Significant location change vs continuous updates
  • 基于时间线的更新替代主动刷新
  • 检查
    isLuminanceReduced
    状态
  • 批量处理Watch Connectivity传输
  • 采用显著位置变化更新而非持续位置更新