Build custom workouts with WorkoutKit
System & Services 进阶 20m

使用 WorkoutKit 构建自定义健身计划

Build custom workouts with WorkoutKit

2023年6月5日

在 Apple 官方观看视频

一句话判断

如果你在做健身类 App 并想让用户在你的 App 里设计训练计划然后在 Apple Watch 原生 Workout App 中执行，WorkoutKit 就是这个桥梁——支持自定义训练步骤、目标、提醒和计划调度。

这场 Session 讲了什么

iOS 17 引入的 WorkoutKit 是一个全新的 Swift 框架，让你在 App 中创建四种训练类型：目标训练（Goal）、配速训练（Pacer）、铁人三项训练（Swim-Bike-Run）和自定义训练（Custom Workout）。Session 重点讲解了自定义训练的构建方式。

自定义训练的结构。一个自定义训练由三个阶段组成：热身步骤（Warmup）开头、一系列可重复的训练块（Interval Blocks）作为主体、恢复步骤（Cooldown）结尾。每个训练块内包含工作步骤和恢复步骤，可以指定重复次数。

步骤的属性。每个步骤有两个核心属性：目标（Goal）和提醒（Alert）。目标定义步骤何时结束——可以是时间目标、距离目标或开放目标（用户手动推进）。提醒在特定指标达到阈值时通知用户，支持配速、踏频、功率和心率四种类型。

验证机制。CustomWorkoutComposition 的初始化器使用 try，因为框架会验证训练结构的合理性——比如距离目标不能用于不追踪距离的运动类型。

Session 还介绍了预览 UI（让用户在训练前查看计划）和计划同步（在特定时间自动将训练推送到 Apple Watch）。

值得深挖的点

训练验证的设计思路：框架在构造时就验证合理性，而不是等到运行时才报错。这把错误发现提前到了编码阶段，比在手表上运行时才发现问题要好得多。如果你的 App 允许用户自定义训练，也应该在编辑时就给出反馈。

HealthKit 的深度集成：目标、提醒等概念大量使用 HKQuantity 和 HKUnit。如果你的 App 已经使用 HealthKit，迁移到 WorkoutKit 会很自然。

从 App 到 Workout App 的桥梁：WorkoutKit 创建的训练可以直接在系统 Workout App 中执行，这意味着你的用户可以使用原生运动追踪的全部能力（心率监测、GPS、卡路里计算等），而不需要你自己实现这些功能。

代码片段

构建一个完整的自定义骑行训练：

import WorkoutKit
import HealthKit

// 热身步骤：开放目标（用户手动结束）
let warmupStep = WorkoutStep(goal: .open)

// 第一个训练块：4组 2英里工作 + 0.5英里恢复
let twoMileGoal = WorkoutGoal.distance(
    HKQuantity(unit: .mile(), doubleValue: 2)
)
let paceAlert = WorkoutAlert(
    target: .single(
        HKQuantity(unit: .milePerHour(), doubleValue: 10)
    ),
    type: .currentPace
)
let workStep1 = IntervalBlock.Step(
    type: .work, goal: twoMileGoal, alert: paceAlert
)

let halfMileGoal = WorkoutGoal.distance(
    HKQuantity(unit: .mile(), doubleValue: 0.5)
)
let hrAlert = WorkoutAlert.heartRate(zone: 1)
let restStep1 = IntervalBlock.Step(
    type: .rest, goal: halfMileGoal, alert: hrAlert
)

let block1 = IntervalBlock(
    steps: [workStep1, restStep1], iterations: 4
)

// 恢复步骤：5分钟时间目标
let fiveMinGoal = WorkoutGoal.time(
    HKQuantity(unit: .minute(), doubleValue: 5)
)
let cooldownStep = CooldownStep(goal: fiveMinGoal)

// 组合成完整训练
let workout = try CustomWorkout(
    activityType: .cycling,
    location: .outdoor,
    displayName: "间歇骑行训练",
    warmup: warmupStep,
    blocks: [block1],
    cooldown: cooldownStep
)

最佳实践

  • 使用 try 捕获训练验证错误，给用户提供清晰的修改提示
  • 为每个工作步骤设置明确的目标（时间或距离），避免用户在间歇训练中迷失节奏
  • 合理使用提醒——不要过度打扰用户，只在关键指标（如心率过高）时触发
  • 利用预览 UI 让用户在开始训练前确认计划
  • 计划同步适合周期性训练（如每周三的间歇跑），提升用户留存

还有什么值得关注

  • 铁人三项（Swim-Bike-Run）训练的构建方式
  • 计划同步 API 的具体用法和时间触发机制
  • 训练从 App 同步到 Apple Watch 后的数据回传
  • WorkoutKit 与现有 HealthKit 数据的整合方式
WWDC 2023