如何为HealthKit Workout Builder添加iOS 18估算运动强度值？

问题原因 #

你直接用HKQuantitySample初始化estimatedWorkoutEffortScore类型是错误的——iOS 18中，估算运动强度对应的样本类型是**HKWorkoutEffortSample**，而非普通的HKQuantitySample。强行用不匹配的样本类型初始化并添加，会导致运行时类型错误崩溃。

正确实现步骤 #

1. 确保已申请对应权限 #

在请求HealthKit权限时，必须包含estimatedWorkoutEffortScore的读写权限：

let typesToShare: Set<HKSampleType> = [
    HKObjectType.workoutType(),
    HKObjectType.quantityType(forIdentifier: .estimatedWorkoutEffortScore)!
]
let typesToRead: Set<HKObjectType> = [
    HKObjectType.workoutType(),
    HKObjectType.quantityType(forIdentifier: .estimatedWorkoutEffortScore)!
]

HealthKitStore.requestAuthorization(toShare: typesToShare, read: typesToRead) { success, error in
    // 处理权限申请结果
}

2. 使用专属API创建并添加样本 #

HKWorkoutEffortSample有专属初始化方法，且需通过iOS 18新增的HKWorkoutBuilder方法添加：

static func addWorkout(start: Date, end: Date) async {
    let config = HKWorkoutConfiguration()
    config.activityType = .traditionalStrengthTraining

    // 1. 初始化估算运动强度样本
    guard let effortType = HKQuantityType.quantityType(forIdentifier: .estimatedWorkoutEffortScore) else {
        // 仅iOS18+支持，此处处理版本不兼容逻辑
        return
    }
    let effortQuantity = HKQuantity(unit: .percent(), doubleValue: 50)
    let effortSample = HKWorkoutEffortSample(
        quantityType: effortType,
        quantity: effortQuantity,
        startDate: start,
        endDate: end,
        metadata: nil
    )

    let builder = HKWorkoutBuilder(healthStore: HealthKitStore, configuration: config, device: .local())
    do {
        try await builder.beginCollection(at: start)
        // 2. 使用iOS18新增方法添加强度样本
        if #available(iOS 18.0, *) {
            try await builder.addWorkoutEfforts([effortSample])
        }
        try await builder.endCollection(at: end)
        _ = try await builder.finishWorkout()
    } catch {
        print("添加失败：\(error.localizedDescription)")
    }
}

3. 关键注意事项 #

• 版本适配：estimatedWorkoutEffortScore和HKWorkoutEffortSample仅在iOS 18及以上可用，必须添加版本判断
• 时间范围：运动强度样本的时间区间必须包含在对应workout的时间范围内，否则会保存失败
• 权限校验：必须确保用户已授权该类型的读写权限，否则会抛出权限错误

内容的提问来源于stack exchange，提问作者Ilja