写入分类数据（HealthCategorySample）#

Scripting 应用支持将分类健康数据（如睡眠状态、冥想记录、月经流量、排卵测试结果等）写入 Apple HealthKit。你可以通过 HealthCategorySample 类创建分类数据样本，并使用 Health.saveCategorySample() 方法将其保存到健康数据库中。

使用前提#

• 确保设备支持 HealthKit：

  1if (!Health.isHealthDataAvailable) {
  2  throw new Error("此设备不支持健康数据。")
  3}

• 确保脚本具备目标分类数据类型的写入权限。Scripting 会在首次保存时自动请求授权。

一、创建 HealthCategorySample 实例#

使用 HealthCategorySample.create() 方法创建分类数据样本。

参数说明#

枚举值说明#

• 不同类型的分类数据需要传入不同的枚举类型：

  • 对于 "sleepAnalysis"，应使用 HealthCategoryValueSleepAnalysis 枚举，如：

    • HealthCategoryValueSleepAnalysis.asleepCore
    • HealthCategoryValueSleepAnalysis.awake

  • 对于 "menstrualFlow"，应使用 HealthCategoryValueSeverity 枚举，如：

    • HealthCategoryValueSeverity.mild、moderate、severe

  请参考具体分类类型所支持的枚举列表。

示例代码#

1const sample = HealthCategorySample.create({
2  type: "sleepAnalysis",
3  startDate: new Date("2025-07-03T23:00:00"),
4  endDate: new Date("2025-07-04T07:00:00"),
5  value: HealthCategoryValueSleepAnalysis.asleepCore,
6  metadata: {
7    source: "ScriptingApp"
8  }
9})
10
11if (!sample) {
12  throw new Error("创建 HealthCategorySample 失败")
13}

二、保存样本到 HealthKit#

使用 Health.saveCategorySample() 方法将创建的样本写入 HealthKit：

1await Health.saveCategorySample(sample)

如果保存失败（如权限不足），该方法将抛出错误。

完整示例#

1async function writeSleepData() {
2  const sample = HealthCategorySample.create({
3    type: "sleepAnalysis",
4    startDate: new Date("2025-07-03T23:00:00"),
5    endDate: new Date("2025-07-04T07:00:00"),
6    value: HealthCategoryValueSleepAnalysis.asleepCore,
7  })
8
9  if (!sample) {
10    console.error("创建样本失败")
11    return
12  }
13
14  try {
15    await Health.saveCategorySample(sample)
16    console.log("睡眠数据写入成功")
17  } catch (err) {
18    console.error("保存失败：", err)
19  }
20}
21
22writeSleepData()

注意事项#

• value 参数必须是指定 type 类型对应的合法枚举值，否则创建将失败。
• startDate 与 endDate 应表示事件的发生时间段，例如一次睡眠或一次冥想。
• metadata 是可选的，适用于添加数据来源或标识用途。