Explore wellbeing APIs in HealthKit
Health & Fitness 进阶 20m

探索 HealthKit 中的心理健康 API

Explore wellbeing APIs in HealthKit

2024年6月10日

在 Apple 官方观看视频

一句话判断

HealthKit 新增了 State of Mind、GAD-7 和 PHQ-9 三种心理健康数据类型，让开发者可以在自己的 app 里集成情绪记录与焦虑/抑郁评估——这不只是健康类 app 的专利，任何 app 都值得考虑在合适场景加入情绪反思。

这场 Session 讲了什么

Apple 在去年推出了 Health app 中的心理健康功能，用户可以记录自己的情绪状态（State of Mind），也可以完成 GAD-7 焦虑评估和 PHQ-9 抑郁评估这两个标准化问卷。今年这些数据类型作为 HealthKit API 正式开放给开发者。

核心数据类型有三个。GAD-7 和 PHQ-9 是 Pfizer 开发的标准化临床问卷，分别通过 7 道题和 9 道题评估焦虑和抑郁风险，开发者可以读取和写入这些评估结果。State of Mind 是更轻量级的情绪记录机制，包含四个维度：feeling kind（情绪类型：日常心情或瞬时情绪）、valence（效价：-1 到 1 的连续值，代表从负面到正面）、labels（情绪标签如”激情""焦虑""释然”）和 associations（情绪关联如”家庭""工作""身份”）。

Session 用一个日历 app 的 Demo 展示了 State of Mind API 的实际用法：用户在完成一个日历事件后，通过 emoji 选择自己的感受，app 将其映射为 State of Mind 样本保存到 HealthKit。

值得深挖的点

State of Mind 的设计哲学：不仅仅是”心情打分”

Apple 对 State of Mind 的设计有着明确的临床意图。Session 中反复强调了一个来自情绪科学研究的核心发现：具体地命名自己的感受（而不是笼统地说”还行”），本身就有临床益处。如果你正在经历不愉快的感受，说出来可以缩短不良情绪持续的时间；如果是愉快的感受，表达出来可以延长这种积极体验。

这解释了为什么 API 设计中 valence 是一个连续值而不是简单的”好/中/差”三档，以及为什么 labels 提供了如此丰富的选项。Apple 希望开发者引导用户具体地描述自己的感受，而不是做简化处理。这意味着如果你只是放一个笑脸/哭脸让用户选，虽然技术上可行，但完全浪费了这个 API 的设计意图。

从工程角度看，State of Mind 不应该局限于健康类 app。Session 明确说了：任何场景下只要适合让用户停下来反思一下自己的状态，就是合理的使用场景。日历 app 关联事件和情绪是一个方向，健身 app 记录运动后的感受是另一个方向，甚至效率工具在完成一个深度工作时段后也可以问一句”现在感觉怎么样”。

Valence 的连续值设计

Valence 取值范围从 -1 到 1，这是一个很讲究的选择。二元分类（正面/负面）丢失了太多信息，而 1-5 分的量表又容易让用户纠结于”4 分和 5 分的区别是什么”。连续滑块让用户凭直觉拖动，反而更准确。

在 Demo 中，开发者将 5 个 emoji 映射到了不同的 valence 值——这是一种务实的做法，用 emoji 降低输入门槛，同时保留 valence 的精度。如果你打算做更精细的情绪记录 UI，可以考虑直接暴露滑块控件，让用户在连续值上自由选择。

代码片段

创建并保存 State of Mind 样本

最核心的用法：为日历事件关联一个情绪记录。

// 定义 emoji 到 valence 和 label 的映射
enum EmojiType: String, CaseIterable {
    case happy = "😊"
    case neutral = "😐"
    case stressed = "😤"
    case sad = "😢"
    case excited = "🤩"

    var valence: Double {
        switch self {
        case .happy: return 0.6
        case .neutral: return 0.0
        case .stressed: return -0.5
        case .sad: return -0.7
        case .excited: return 0.8
        }
    }

    var label: HKStateOfMindLabel? {
        switch self {
        case .happy: return .happy
        case .neutral: return .neutral
        case .stressed: return .stressed
        case .sad: return .sad
        case .excited: return .excited
        }
    }
}

// 创建并保存样本
func saveStateOfMind(for event: EKEvent, emoji: EmojiType) async throws {
    let sample = HKStateOfMind(
        kind: .momentaryEmotion,  // 瞬时情绪，适合事件关联
        valence: emoji.valence,
        date: event.startDate
    )
    // 设置标签和关联
    sample.label = emoji.label
    // 根据日历类型推断关联因素
    if event.calendar.title.contains("Office") {
        sample.associations = [.work]
    }

    try await healthStore.save(sample)
}

坑：kind 参数选 .momentaryEmotion 还是 .dailyMood 要根据场景来。记录”这个会议让我感觉如何”用 emotion，记录”今天整体怎么样”用 mood。

请求 HealthKit 授权

// 请求 State of Mind 读写权限
let types: Set<HKSampleType> = [
    HKObjectType.stateOfMindType()
]

healthStore.requestAuthorization(toShare: types, read: types) { success, error in
    if success {
        // 授权成功，可以读写 State of Mind 数据
    }
}

读取用户的 State of Mind 历史

// 查询最近一周的 State of Mind 记录
let predicate = HKQuery.predicateForSamples(
    withStart: Calendar.current.date(byAdding: .day, value: -7, to: Date()),
    end: Date()
)

let query = HKSampleQuery(
    sampleType: .stateOfMindType(),
    predicate: predicate,
    limit: HKObjectQueryNoLimit,
    sortDescriptors: [NSSortDescriptor(key: HKSampleSortIdentifierStartDate, ascending: false)]
) { _, samples, error in
    guard let stateOfMindSamples = samples as? [HKStateOfMind] else { return }
    for sample in stateOfMindSamples {
        print("效价: \(sample.valence), 标签: \(sample.label?.rawValue ?? "无")")
    }
}
healthStore.execute(query)

坑：State of Mind 数据属于敏感健康信息，用户可能在系统设置中随时撤销授权，每次读取前都应该确认授权状态。

最佳实践

新项目： 如果你正在做任何与时间管理、活动追踪、健身记录相关的 app，State of Mind 是一个低成本高价值的集成点。用 emoji 做输入，映射到 valence 和 label，保存到 HealthKit——几十行代码就能让 app 多一层情感维度。

已有项目： 先从读取开始。如果你的 app 已经在使用 HealthKit，查询用户的 State of Mind 数据可以为你的 app 提供额外的上下文。比如健身 app 可以对比运动量和心情之间的关系，帮助用户发现自己的行为模式。

GAD-7 / PHQ-9： 这两个问卷的使用场景更窄，主要面向心理健康类 app。如果你要做，务必按照 Pfizer 的标准流程执行，Apple 在文档中有详细说明。不要试图自创简化版问卷，临床有效性是这些工具的核心价值。

还有什么值得关注

  • State of Mind 支持多个 labels 和多个 associations，意味着一次情绪记录可以同时标记为”焦虑+疲惫”，关联到”工作+健康”——比单一标签灵活得多
  • Apple Watch 上也能记录 State of Mind，如果你的 app 有 Watch 端，可以在手腕上做更轻量的情绪 check-in
  • GAD-7 和 PHQ-9 的结果可以用于追踪治疗效果，适合心理治疗类 app 展示长期趋势
WWDC 2024