HealthKit 用于在 Apple 设备上读取和写入健康与健身数据。该技能文档的目标环境为 Swift 6.3 / iOS 26+,涵盖授权、查询、写入样本、后台投递和体能训练会话。
一、用途 面向需要在 iOS 应用中接入 Apple Health 数据的开发者,提供从项目配置、权限申请到数据读写与后台更新的完整参考实现,帮助规避常见的权限与查询错误。
二、主要能力
- 设置与可用性:在 Xcode 中启用 HealthKit 能力(添加 entitlement);在 Info.plist 中加入 NSHealthShareUsageDescription(读取)和 NSHealthUpdateUsageDescription(写入);如需后台投递,启用 Background Delivery 子能力。访问前必须调用 HKHealthStore.isHealthDataAvailable() 检查,iPad 及部分设备不支持;建议创建单个 HKHealthStore 实例并在全应用复用(线程安全)。
- 授权:仅请求应用真正需要的类型,过度请求会被 App Review 拒绝。文档给出 requestAuthorization(toShare:read:) 的 async 写法。授权状态判断方面,应用只能确定“尚未请求授权”;用户拒绝后 HealthKit 返回空结果而非错误。状态枚举包括 .notDetermined、.sharingAuthorized、.sharingDenied。
- 样本查询:使用 HKSampleQueryDescriptor(async/await)进行一次性读取,优先于旧的基于回调的 HKSampleQuery;示例为读取最近心率样本并按结束时间倒序、限制条数,并演示用 doubleValue(for:) 取单位换算后的数值。
- 统计查询:使用 HKStatisticsQueryDescriptor 获取聚合单值(求和、平均、最小、最大)。累计型数据(步数、卡路里)使用 .cumulativeSum;离散型数据(心率、体重)使用 .discreteAverage、.discreteMin、.discreteMax。
- 统计集合查询:使用 HKStatisticsCollectionQueryDescriptor 将时序数据按间隔分组,适合图表展示(如按天汇总步数),并说明用 results(for:)(复数)获取 AsyncSequence 以接收数据更新。
- 写入数据:创建 HKQuantitySample 并保存。应用只能删除自己创建的样本,来自其他应用或 Apple Watch 的样本为只读。
- 后台投递:使用 enableBackgroundDelivery(for:frequency:) 注册后台更新(频率有 .immediate、.hourly、.daily、.weekly),需后台投递权限;需搭配 HKObserverQuery,并始终调用 completionHandler,否则系统不会安排下一次投递。enableBackgroundDelivery 只需在应用启动等时机调用一次,系统会持久保存注册。
- 体能训练会话:使用 HKWorkoutSession 与 HKLiveWorkoutBuilder 跟踪实时训练,支持 watchOS 2+ 与 iOS 17+;示例包含开始(配置 activityType、locationType,设置 HKLiveWorkoutDataSource)与结束(end、endCollection、finishWorkout)流程。暂停/恢复、代理处理和跨设备镜像等完整生命周期请参见 references/healthkit-patterns.md。
三、使用方式 按“设置与可用性 → 授权 → 读取(样本/统计/统计集合查询)→ 写入 → 后台投递 → 训练会话”的顺序实现,代码示例以 async/await 描述符为主。常见数据类型表列出 HKQuantityTypeIdentifier(如 .stepCount 单位 .count()、.distanceWalkingRunning 单位 .meter()、.activeEnergyBurned 单位 .kilocalorie()、.heartRate 单位 .count()/.minute()、.oxygenSaturation 单位 .percent()、.bodyMass 单位 .gramUnit(with: .kilo)、.bloodGlucose 单位 .gramUnit(with: .milli).unitDivided(by: .literUnit(with: .deci)) 等)、HKCategoryTypeIdentifier(如 .sleepAnalysis、.mindfulSession、.appleStandHour)以及只读的 HKCharacteristicType(.dateOfBirth、.biologicalSex、.bloodType、.fitzpatrickSkinType)。HKUnit 参考涵盖基本单位、复合单位(如 bpm、m/s)和带前缀单位。
四、适用场景 需要读取或写入 Apple Health 数据的 iOS/watchOS 应用,例如步数与活动能量统计、心率与体征数据展示、体重/身高/体脂等身体数据、血糖等实验室数据、睡眠与正念等分类数据,以及跑步等实时体能训练记录。
五、限制与常见错误
- 过度请求数据类型会被 App Review 拒绝,应只申请实际使用的类型。
- 未处理授权拒绝:直接强制解包(如 result!.sumQuantity()!.doubleValue(...))会崩溃,应使用可选链加默认值。
- 假设 HealthKit 始终可用:iPad 上直接创建 HKHealthStore 并请求授权会崩溃,必须先做可用性检查。
- 在主线程执行重量级查询:应使用 async 描述符而非基于回调的查询。
- 观察者查询中忘记调用 completionHandler,导致系统不再安排下一次投递。
- 统计选项与数据类型不匹配:对离散型(如心率)使用 .cumulativeSum 会返回 nil。
六、审查清单 文档提供一份落地检查项,包括:访问前检查 isHealthDataAvailable();仅请求必要数据类型;Info.plist 包含相应用途说明;Xcode 中启用 HealthKit 能力;优雅处理授权拒绝(返回 nil 而非崩溃);复用单个 HKHealthStore 实例;使用异步查询描述符;重量级查询不阻塞主线程;统计选项与数据类型匹配;后台投递搭配 HKObserverQuery 并调用 completionHandler;如使用后台投递则启用对应 entitlement;正确结束训练会话并完成 builder;写入操作仅针对应用自己创建的样本类型。
七、参考资料 扩展模式(训练、锚点查询、SwiftUI 集成)见 references/healthkit-patterns.md;其余为 HealthKit 框架、HKHealthStore、各查询描述符、HKWorkoutSession、HKLiveWorkoutBuilder 相关文档以及“Setting up HealthKit”“Authorizing access to health data”等主题。文档未提供具体价格、收费或商业条款信息。