React Native鸿蒙PHQ-9/GAD-7评分：索引映射与踩坑实践

最近刚好在做鸿蒙版的心理健康评估模块，接手了一个看似简单、细想却有不少讲究的需求：用 React Native 实现 PHQ-9 / GAD-7 标准化量表的评分功能，核心机制是“选项索引映射评分”——用户从“完全没有”“几天”“一半以上天数”“几乎每天”这类选项里选一个，系统把选项对应的索引值转成分数，累加出总分。接到这个需求的第一反应是“这不就是个数组下标取值吗”，真正落地时才发现，跨端一致性、量表规则的严谨性、鸿蒙适配的兼容性，每一样都是坑。这篇文章就把完整实现思路、鸿蒙实测踩坑记录和评分校验方法一次说清楚，给正在做跨平台健康类 App 的开发者一个可复用的参考。

1. 需求拆解与整体设计思路

1.1 量表的评分规则，和普通问卷到底差在哪

PHQ-9（患者健康问卷抑郁量表）和 GAD-7（广泛性焦虑障碍量表）都是临床上广泛使用的标准化自评工具。它们的计分方式很明确：每个条目按症状出现频率分为四级，依次对应 0 到 3 分，所有条目得分相加得到总分，再用总分区间划分严重程度。

以 PHQ-9 为例，9 个条目，每个条目 0 到 3 分，总分范围是 0 到 27 分。GAD-7 是 7 个条目，总分范围 0 到 21 分。评分的核心难点不在加法本身，而在“选项文本”和“分值”的映射关系不能出错。用户看到的是中文选项“几天”，程序内部必须稳定地把它识别为 1 分，而不是靠字符串匹配时多一个空格、换一个语言就崩掉。

这里的关键认知是：标准化量表的评分依据是“选项所在的位置”，而不是选项文本本身。换句话说，无论选项文案怎么翻译、怎么改写，只要它在选项列表里的顺序不变，对应的分值就不变。这就是“索引映射”的底层逻辑。

1.2 为什么不能把分数直接硬编码到选项对象里

很多同学第一版会这么写：

typescript复制const options = [
  { label: '完全没有', value: 0 },
  { label: '几天', value: 1 },
  { label: '一半以上天数', value: 2 },
  { label: '几乎每天', value: 3 },
];

看起来没问题，但一旦遇到这几种情况就会翻车：

• 产品经理说“我要在‘几天’和‘一半以上天数’之间加一个选项”，直接在所有选项对象里插入一项，后面所有 value 都要跟着改。
• 多语言版本中，日文、英文的选项中“几天”的排序可能不同，字符串匹配就会错位。
• 如果选项列表被服务端动态下发，服务端给数组重新排序后，value 字段就会和排序产生冲突。

用索引值作为分数依据，本质上是一种“约定优于配置”的思路：选项数组的顺序就是分值的顺序，数组第几项就代表几分。这样一来，选项文案、翻译、增删都不会影响计分逻辑，只需要保证数组顺序和量表标准一致。

1.3 方案选型：为什么在鸿蒙场景下选 React Native

这个项目原本的跨平台诉求是 iOS、Android、鸿蒙三端共用一套逻辑。React Native 的跨平台能力成熟，社区生态丰富，而鸿蒙这边也有 React Native for OpenHarmony（社区简称 RNOH）的适配版本，基础组件和核心 API 已经能做到大部分兼容。

选 React Native 而不是纯 ArkUI 开发，原因很实际：团队已经有一套完整的 RN 组件库和业务代码，直接迁移到鸿蒙可以省掉大量重复开发。但要注意的是，RN 在鸿蒙上的兼容性没有 iOS/Android 那么“无脑”，UI 组件层级复杂时尤其需要做真机验证。

在我实际测试中，React Native 的老架构（Bridge 模式）在鸿蒙上兼容性更好，新架构（Fabric + TurboModule）虽然官方适配持续推进，但部分第三方原生模块还没有完全迁移。所以核心原则是：业务逻辑全用纯 JS 实现，不依赖原生模块，评分计算这种逻辑放在逻辑层，完全避开鸿蒙适配差异的风险点。

2. 核心实现：选项索引映射评分的完整设计

2.1 选项模型与分数映射表的定义

第一步，定义一套和量表规则严格对应的选项模型。这里不直接用 value 字段存分数，而是用一个独立的常量数组来定义选项顺序：

typescript复制// 频率选项，顺序对应 PHQ-9 / GAD-7 的标准计分规则
export const FREQUENCY_OPTIONS = [
  { key: 'not_at_all', label: '完全没有' },
  { key: 'several_days', label: '几天' },
  { key: 'more_than_half', label: '一半以上天数' },
  { key: 'nearly_every_day', label: '几乎每天' },
] as const;

再看分数映射表。这个表是整个评分机制的核心，它不依赖选项对象里的某个字段，而是直接建立“选项 key 到分值”的稳定对应关系：

typescript复制export const SCORE_MAP: Record<string, number> = {
  not_at_all: 0,
  several_days: 1,
  more_than_half: 2,
  nearly_every_day: 3,
};

为什么要用 key 而不是 index？因为我们在多语言场景下，数组顺序可能因为翻译语法调整发生变化——实际上这个场景不太常见，但用 key 的好处是在组件渲染时可以直接通过 key 定位到选项，而把分数计算独立出去，逻辑更清晰。

有一种偷懒写法是直接用数组下标当分数：const score = FREQUENCY_OPTIONS.findIndex(o => o.key === selectedKey); 这样做在“所有量表都是统一四级选项”的前提下没问题，但不具备通用性。比如后续遇到 PHQ-9 里第 9 题有特殊计分规则（自杀意念相关的特殊处理），或者遇到其他量表不是从 0 开始计分的场景，findIndex 这种写法就不够灵活。所以我强烈建议保留独立的 SCORE_MAP。

2.2 核心映射函数：从选中项到分数的完整流程

接下来是评分计算的核心函数。这个函数接收当前问卷所有条目的答案集合，输出总分和严重程度分级。

typescript复制export type AnswerMap = Record<number, string>; // 题目序号 -> 选项 key

export interface AssessmentResult {
  totalScore: number;
  maxScore: number;
  severityLevel: 'none' | 'mild' | 'moderate' | 'severe';
  answeredCount: number;
  totalCount: number;
}

const PHQ9_SEVERITY_CUTOFFS = [
  { max: 4, level: 'none' },
  { max: 9, level: 'mild' },
  { max: 14, level: 'moderate' },
  { max: 19, level: 'moderately_severe' },
  { max: 27, level: 'severe' },
];

export function calculatePhq9Score(answers: AnswerMap): AssessmentResult {
  let totalScore = 0;
  let answeredCount = 0;
  const totalCount = 9;

  for (let i = 1; i <= totalCount; i++) {
    const selectedKey = answers[i];
    if (selectedKey && SCORE_MAP[selectedKey] !== undefined) {
      totalScore += SCORE_MAP[selectedKey];
      answeredCount++;
    }
  }

  const severity = PHQ9_SEVERITY_CUTOFFS.find(c => totalScore <= c.max)?.level ?? 'severe';

  return {
    totalScore,
    maxScore: totalCount * 3,
    severityLevel: severity,
    answeredCount,
    totalCount,
  };
}

几个关键点在这里展开说明：

• answers 的类型是 Record<number, string>，键是题目编号，值是用户在界面上选中的选项 key。这种结构天然适合表单类场景，后续要做持久化、服务端上报，直接序列化这一个对象就可以。
• 计算时用 SCORE_MAP[selectedKey] !== undefined 做兜底校验，防止脏数据。实际开发中我遇到过用户端因缓存问题提交了空字符串，如果直接用 SCORE_MAP[selectedKey] 相加，undefined 加数字会变成 NaN，整个总分直接崩掉。
• answeredCount 是必须统计的。量表完整性是医疗场景的硬要求：只答了 6 题的 PHQ-9，和答满 9 题的 PHQ-9，其解释方式完全不同。产品逻辑上，未答完时总分可以实时计算，但结果页必须提示“本次评估未完成，结果仅供参考”。

2.3 状态管理与数据流设计

React Native 中管理问卷答案的状态，我用的是 useReducer 而不是多个 useState，原因在于问卷的每个答案都在同一个数据流里，需要支持“修改某一题答案”“清空全部答案”“从服务端回填答案”这些批量操作，useReducer 能把所有状态变更收敛到几个固定的 action 中。

typescript复制type AssessmentState = {
  currentQuestion: number;
  answers: AnswerMap;
};

type AssessmentAction =
  | { type: 'ANSWER_QUESTION'; questionIndex: number; optionKey: string }
  | { type: 'RESET' }
  | { type: 'LOAD_ANSWERS'; answers: AnswerMap };

function assessmentReducer(state: AssessmentState, action: AssessmentAction): AssessmentState {
  switch (action.type) {
    case 'ANSWER_QUESTION':
      return {
        ...state,
        answers: {
          ...state.answers,
          [action.questionIndex]: action.optionKey,
        },
      };
    case 'RESET':
      return { currentQuestion: 0, answers: {} };
    case 'LOAD_ANSWERS':
      return { ...state, answers: action.answers };
    default:
      return state;
  }
}

在组件里，用户点击某个选项时，只派发一个 action，由 reducer 统一更新状态。总分计算不放在 reducer 里，而是通过 useMemo 根据 answers 实时计算。这样做的优点是计算逻辑和状态管理解耦，后续如果要加 GAD-7 或者其他量表，只需要替换计算函数即可，数据处理流程完全复用。

数据持久化方面，我强烈建议在用户每答完一题后，就把 answers 对象写入 AsyncStorage（鸿蒙上也可以使用 @react-native-async-storage/async-storage 的兼容版本）。这样即使用户中途杀进程或切后台被回收，下次打开还能从上次断点继续。实测下来，简单的对象序列化写入对性能影响微乎其微，但用户体验的提升是质的。

3. 鸿蒙适配实战：React Native 跑在鸿蒙上的那些坑

3.1 RNOH 的选型与兼容性问题

鸿蒙上跑 React Native，目前主要有两个方案：一个是 OpenHarmony 社区维护的 React Native for OpenHarmony（RNOH）框架，另一个是通过 DevEco Studio 将 RN 代码打包成 hap 后集成。我给的建议是：优先走 RNOH 的 Release 版本，不要用 nightly build，除非你团队有足够的耐心处理每日变更带来的兼容问题。

我在集成过程中遇到的最大坑是第三方原生模块的鸿蒙适配。我在项目里最初用了 @react-native-async-storage/async-storage 的旧版本，鸿蒙上运行时直接报 Cannot find native module 'RNCAsyncStorage'。查了日志发现是这个模块的 Android 实现和鸿蒙的 Registrar 注册机制不完全兼容。解决办法是参考 RNOH 官方文档，使用他们维护的 fork 版本或者其他鸿蒙适配过的存储方案。

总结一下选型要点：

• 能用纯 JS 实现的功能，不要依赖原生模块。比如评分计算全写在 TypeScript 里，跨端完全一致。
• 第三方库先查 RNOH 的兼容性列表，再进入开发。不要想当然认为 iOS/Android 能跑，鸿蒙就一定没问题。
• 鸿蒙真机调试时，建议把 Metro 的缓存清掉再启动，否则容易出现 bundle 更新不及时导致的“改了代码但界面没变化”的假象。

3.2 启动白屏问题的排查实录

React Native 鸿蒙版的启动白屏，是社区里反馈最多的问题之一。我这边的实测情况是：App 冷启动时，Bundler 加载 JS 代码需要时间，鸿蒙原生页面已经渲染完成，但 JS 侧还没有执行完，就出现了一段白屏窗口。尤其是 debug 模式下走 Metro 热更新，白屏时间会更明显。

排查白屏问题时，我建议按以下顺序逐步定位：

第一，确认 Bundle 是否成功加载。在鸿蒙的 DevEco Studio 控制台或者 logcat 里搜 ReactNative、Bundle 关键字。如果看到 Loading JS bundle 之后长时间没有 Running application 的日志，说明是加载阶段卡住了。

第二，检查字体和图片资源路径。鸿蒙的文件系统路径和 Android 有差异，如果代码里通过 require('./image.png') 引用了图片，而 Metro 在鸿蒙上没有正确映射资源路径，会导致图片加载失败，间接表现为白屏。

第三，排查自定义组件注册。如果入口组件用了 AppRegistry.registerComponent，要确认注册名和原生侧 loadModule 传入的名称完全一致。大小写不一致在 iOS/Android 可能兼容过去了，鸿蒙上会卡在启动阶段。

针对白屏，我的方案是在入口文件做启动等待逻辑，在应用根组件渲染前先加载好关键配置：

typescript复制import { AppRegistry } from 'react-native';
import App from './src/App';
import { name as appName } from './app.json';

// 在应用启动时干一些初始化操作
async function bootstrap() {
  // 初始化本地存储等
  await initStorage();
  return App;
}

const Root = () => {
  return <App />;
};

AppRegistry.registerComponent(appName, () => Root);

虽然这段代码本身不直接解决白屏，但它避免了初始化时序问题导致的启动失败。真正解决白屏，核心还在于确认原生侧组件加载、Metro 连接、资源映射这三件事都正常。

3.3 选项选择器在鸿蒙上的交互适配

量表页面最核心的交互是四个选项的单选题，一般来说用 TouchableOpacity 加自定义样式就足够。不过如果产品要求用“循环滚轮”或“滑动选择器”的形式来展示频率选项，就需要额外考虑鸿蒙适配。

我最初尝试用 @react-native-picker/picker 来实现滚轮效果，在 iOS 上表现为原生滚轮，Android 上是下拉列表，鸿蒙上这个库并没有完整适配，直接使用会出现弹窗高度异常、触摸事件无响应等问题。实测后我决定自绘一个简易滚轮，用 ScrollView + snapToInterval 加 FlatList 实现。实现要点是：

• 每个选项固定行高，比如 44，snapToInterval 设成 44，保证滚动停止时恰好对齐一项。
• 用 onMomentumScrollEnd 回调计算当前停在哪个索引，再同步到状态。
• 滚轮的视觉中间层用一个半透明遮罩标识当前选中项，提升交互清晰度。

自绘滚轮的兼容性最好，在 iOS、Android、鸿蒙上表现一致。缺点是开发成本高一些，但考虑到量表页的交互体验相当重要，这个投入是值得的。

4. 从评分到报告：完整流程中的边界处理

4.1 未完成量表的处理策略

心理量表测评有一个很重要的伦理问题：不能强制用户答完所有题目，但在给出结果时必须明确说明“当前结果不完整，不具备诊断参考价值”。

功能设计上，我做了这样几件事：

• 用户未答完时，总分照常计算，但结果页展示一个明显的“评估未完成”标识。
• 如果未答题数超过总题数的 30%（比如 PHQ-9 超过 3 题未答），则隐藏严重程度分级，只展示“答题进度不足，无法给出参考分级”。
• 用户在量表页面主动点击“重新作答”时，清空所有答案并二次确认，避免误触导致数据丢失。

这些逻辑在评分函数里通过 answeredCount / totalCount 的比例来控制，实现起来不复杂，但对产品专业度的提升非常重要。

4.2 严重程度分级的展示与免责提示

PHQ-9 和 GAD-7 的结果分级有公开的标准切分点，我在这里直接列出来供参考。

注意，这些切分点只用于自评参考，不能作为临床诊断依据。我在结果页底部固定展示一行提示语：“本评估结果仅供个人参考，不构成医疗诊断。如有需要，请前往专业医疗机构就诊。”这是医疗健康类应用的合规底线，不能省略。

4.3 多语言场景下选项 key 的稳定性

在前面的设计中，所有的选项都用 key 而不是 label 来参与计算。这个设计在多语言场景下尤其关键。假设中文版选项顺序是“完全没有-几天-一半以上天数-几乎每天”，而英文版的文案变成“Not at all-Several days-More than half the days-Nearly every day”，此时如果评分逻辑用文案匹配，英文版只要有一个字符不匹配，分数就全乱了。

用 key 做映射后，多语言只影响 UI 展示的 label，计算逻辑完全不受影响。组件里可以这样使用：

typescript复制const OPTIONS = FREQUENCY_OPTIONS.map(opt => ({
  key: opt.key,
  label: t(`frequency.${opt.key}`), // i18n 翻译函数
}));

这里 t 函数根据当前语言环境返回对应文案，但 key 始终保持不变。评分函数拿到的是 opt.key，再通过 SCORE_MAP 转成分数，整个链路是语言无关的。

5. 常见问题与排查技巧实录

5.1 经典 Bug 回顾与修复过程

第一个经典 Bug：选项索引错位。现象是用户明明选了“几天”，结果页总分为 0。排查后发现，我在某个版本里直接在 FREQUENCY_OPTIONS 数组最前面插入了一个“全部选项”的占位项，导致所有 index 向后偏移了一位。但 SCORE_MAP 是按 key 映射的，理论上不该受影响。进一步追查才发现，问题出在另一个地方——某个第三方组件的受控组件用数组下标作为选中状态，插入占位项后组件内部的 selectedIndex 没同步更新，提交数据时传了错误的 index。这就是典型的“隐式约定”带来的坑。后来我把所有和选项相关的 index 全部改成 key 后，该问题彻底消失。

第二个 Bug：总分出现小数。某次测试反馈，用户总分显示 8.5 分。查下来是后端返回的选项数据里，分值字段被服务端序列化成了字符串 "1"，前端 1 + "2" 拼接成了 "12"，之后 parseFloat 又给出了各种奇怪结果。修法就是在计算入口统一做类型保护：

typescript复制const rawScore = SCORE_MAP[selectedKey];
const score = typeof rawScore === 'number' ? rawScore : Number(rawScore) || 0;

这个教训告诉我：评分模块的输入数据不能完全信任前后端约定，能多做一层类型保护就多做一层。

第三个 Bug：答案闪失。用户答到第 8 题时杀进程，重进后第 3、4 题的答案丢了。原因是我在答案变化时异步写入 AsyncStorage，但写入顺序没保证。用户在快速连续作答时，异步写操作是串行的，但开始时读取的却是旧值，导致后写覆盖先写。修复方案是引入一个简单的写入队列，同一个 key 的写入操作排成队列按顺序执行，同时每次加载时都读取最新值。

5.2 评分正确性验证速查表

在交付前，我整理了一份自查清单，每一条都是踩过坑后的经验总结。这里分享给你参考。

5.3 一份额外的建议：评分模块的单元测试

这种评分逻辑非常适合写单元测试。我这边用 Jest 给评分函数建了完整的测试用例，覆盖所有边界条件。核心测试片段如下：

typescript复制describe('calculatePhq9Score', () => {
  it('should sum all selected scores correctly', () => {
    const answers = {
      1: 'several_days', // 1
      2: 'nearly_every_day', // 3
      3: 'not_at_all', // 0
      4: 'several_days', // 1
      5: 'more_than_half', // 2
      6: 'several_days', // 1
      7: 'not_at_all', // 0
      8: 'several_days', // 1
      9: 'more_than_half', // 2
    };
    const result = calculatePhq9Score(answers);
    expect(result.totalScore).toBe(11);
    expect(result.severityLevel).toBe('moderate');
  });

  it('should handle empty answers', () => {
    const result = calculatePhq9Score({});
    expect(result.totalScore).toBe(0);
    expect(result.answeredCount).toBe(0);
  });

  it('should ignore unknown option keys', () => {
    const answers = { 1: 'unknown_opt' };
    const result = calculatePhq9Score(answers);
    expect(result.totalScore).toBe(0);
    expect(result.answeredCount).toBe(0);
  });
});

有了这层测试保障，后续重构选项数据结构、调整展示样式时，我都敢放心大胆地改，只要测试不挂，计分逻辑就不会出错。这是我认为这个项目里性价比最高的一笔投入。

从需求评审到鸿蒙真机验证，整条链路走下来，最大的感受是：看起来越简单的需求，越要在一开始把数据模型设计清楚。索引映射评分本身不难，难的是它背后“跨端一致”“多语言稳定”“边界可兜底”这些隐藏要求。希望这篇文章能帮你少踩几个坑。