【HarmonyOS 7新能力｜099】Accessibility Kit性能验证：设计可复现的指标与测试清单

Accessibility Kit接入成功后，团队经常只拿一张“运行正常”的截图就宣布完成。但 屏幕朗读开启后的自定义控件走焦、弹窗和动态内容更新 会受到设备档位、冷暖状态、网络、数据规模和生命周期影响。本文给出一套可复现的性能验证方案，重点观察 走焦正确率、焦点丢失次数、播报延迟、不可达控件数，同时把正确性和资源释放设为硬门槛。

一、先写性能假设，而不是先跑工具

假设必须包含改动、预期影响、主要指标和不可退化项。例如“减少重复初始化后，P95 时延下降，同时成功率和峰值资源不恶化”。没有假设的测试容易变成挑选好看的数字。

interface Hypothesis { change: string; primaryMetric: string; expectedDelta: number; guardrails: string[] }
const hypothesis: Hypothesis = { change: '自定义控件走焦顺序', primaryMetric: '走焦正确率', expectedDelta: -0.15, guardrails: ['成功率不下降','资源可释放'] }

expectedDelta 是项目目标，不是平台承诺。

二、固定设备、版本和环境指纹

每个样本都记录设备型号、系统/API 版本、应用构建号、温度区间、电量模式、网络类型和数据集版本。环境指纹不同的样本不能直接合并。

interface EnvironmentFingerprint { device: string; api: string; build: string; network: string; dataset: string; thermal: string }
function sameEnv(a: EnvironmentFingerprint,b: EnvironmentFingerprint): boolean { return JSON.stringify(a) === JSON.stringify(b) }

尤其要区分模拟器、开发签名包和目标设备上的发布候选包。

三、设计覆盖真实负载的数据集

数据集至少包含小、中、大三个规模，以及一个故障样本。针对 屏幕朗读开启后的自定义控件走焦、弹窗和动态内容更新，数据必须稳定可复用并提供摘要，避免测试期间内容变化。

interface Fixture { id: string; size: 'small'|'medium'|'large'|'fault'; digest: string; expectedCode: string }
const fixtures: Fixture[] = [
  { id:'s',size:'small',digest:'fixture-s-v1',expectedCode:'OK' },
  { id:'l',size:'large',digest:'fixture-l-v1',expectedCode:'OK' },
  { id:'f',size:'fault',digest:'fixture-f-v1',expectedCode:'EXPECTED_FAIL' }
]

涉及真实用户数据时只保留脱敏样例，不能把生产内容复制到测试包。

四、冷态、暖态与恢复态分组

冷态用于观察首次初始化，暖态用于观察缓存复用，恢复态覆盖前后台、断连重连或窗口重建。三组各自统计，不能先混合再求平均。

type RunMode = 'cold'|'warm'|'resume'
interface RunPlan { mode: RunMode; warmup: number; samples: number; pauseMs: number }
const plans: RunPlan[] = [
  { mode:'cold',warmup:0,samples:20,pauseMs:2000 },
  { mode:'warm',warmup:5,samples:50,pauseMs:300 },
  { mode:'resume',warmup:2,samples:30,pauseMs:1000 }
]

样本量应根据波动继续扩大，示例数字不是固定标准。

五、沿关键路径分段打点

将一次运行拆成准入、准备、调用、回调、校验、渲染和释放。视觉顺序等同语义顺序、隐藏控件仍获焦、弹窗关闭后焦点丢失、tabIndex与焦点域混用 都能在这些阶段中找到更具体的证据。

type Stage = 'eligibility'|'prepare'|'invoke'|'callback'|'verify'|'render'|'release'
interface Span { traceId:string; stage:Stage; startNs:number; endNs:number; code:string }
function durationMs(s: Span): number { return (s.endNs - s.startNs) / 1_000_000 }

打点本身也有成本，正式采样要验证日志量不会反过来改变结果。

六、统一采样模型和错误码

interface AccessibilityKitSample { traceId: string scene: string m1: number m2: number m3: number m4: number startedAt: number endedAt: number resultCode: string }

function validSample(s: AccessibilityKitSample): boolean {
  return s.endedAt >= s.startedAt && s.scene.length > 0 && s.resultCode.length > 0
}

失败样本不能从统计中删除，应按错误码单独展示成功率和耗时分布。

七、用分位数代替单次最好成绩

平均值会掩盖长尾。报告至少给出样本数、成功率、P50、P95、最大值和异常样本数，并保留原始样本用于复算。

function percentile(values:number[],q:number):number {
  const a=[...values].sort((x,y)=>x-y); if(!a.length) return 0
  return a[Math.min(a.length-1,Math.floor((a.length-1)*q))]
}
function summary(v:number[]){ return { n:v.length,p50:percentile(v,.5),p95:percentile(v,.95),max:Math.max(...v) } }

如果 P50 变好而 P95 变差，说明优化可能引入偶发阻塞。

八、同时设置正确性与资源护栏

性能更快不能以错误结果、内存不释放或后台耗电换取。为每次测试设置结果摘要、资源前后差值和释放完成标记。

interface Guardrail { resultDigestOk:boolean; memoryDeltaMb:number; handlesAfter:number; released:boolean }
function passes(g:Guardrail):boolean { return g.resultDigestOk && g.memoryDeltaMb < 20 && g.handlesAfter === 0 && g.released }

阈值要按项目基线制定，不要直接复制示例。

九、用故障注入验证恢复路径

按能力选择网络抖动、权限拒绝、输入损坏、连接断开、窗口变化或资源不足。故障注入要可撤销，并确认不会触碰生产账号和真实数据。

type Fault = 'timeout'|'cancel'|'disconnect'|'invalid-input'|'unsupported'
interface FaultRun { fault:Fault; injectedAtStage:Stage; expectedCode:string; sideEffectAllowed:boolean }
const faultRun:FaultRun={fault:'timeout',injectedAtStage:'invoke',expectedCode:'TIMEOUT',sideEffectAllowed:false}

恢复成功不仅是页面没崩，还要验证状态、游标、连接和资源数量。

十、对照组和灰度组必须可解释

同一环境按稳定哈希分组，基线组保持旧策略，实验组只改变一个变量。不要让设备档位、网络和数据规模在两组中严重失衡。

function bucket(key:string):number { let h=0; for(const c of key) h=(h*31+c.charCodeAt(0))>>>0; return h%100 }
function variant(key:string):'control'|'experiment' { return bucket(key)<50?'control':'experiment' }

分组键应是稳定、非敏感且符合隐私要求的项目内标识。

十一、结果判定与常见误区

现象	可能原因	结论处理
平均值下降但P95上升	出现偶发阻塞或回退	不通过，定位长尾阶段
速度变快但失败率上升	跳过校验或超时过短	不通过，恢复正确性
暖态明显、冷态无变化	优化只命中缓存	分别报告，不混称整体提升
单设备很好、低档设备变差	资源预算不适配	按设备档位调整策略

对 视觉顺序等同语义顺序、隐藏控件仍获焦、弹窗关闭后焦点丢失、tabIndex与焦点域混用 要逐项建立可观测证据。

十二、形成可复跑的验收清单

最终交付包括环境指纹、固定数据集、运行脚本说明、原始样本、统计摘要、Trace 位置、故障注入结果、正确性护栏和回滚条件。核心指标 走焦正确率、焦点丢失次数、播报延迟、不可达控件数 达标且护栏不退化，才进入小比例灰度。

官方参考：

• https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/improve-screen-reader-experience
• https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V14/ts-universal-attributes-focus-V14

实测中容易翻车的四个细节

无障碍能力的性能验证有三个高频翻车点。第一，播报耗时和播报完成不是一回事：接口返回只代表请求入队，屏幕阅读器真正念完要受语速、播报队列和用户中断影响，验证必须以完成回调或可观测状态为准。第二，焦点序列要在真实手势下采集：脚本模拟的焦点跳转和用户实际滑动路径往往不同，焦点乱序问题只会在真机手势里暴露。第三，勿打扰窗口要单独建模：系统提示、来电、输入法弹层都会打断播报，测试清单里必须有"播报中被打断后的恢复"用例。

把指标变成看门基线

建议固化三组基线并纳入回归：焦点标记到播报启动的 P95 耗时、连续滑动三十个节点的焦点丢失次数、打断恢复的完成率。每次系统升级后重跑，偏差超过两成就按故障排查。基线每个季度用最新回归数据滚动一次，机型换代导致失真的旧数字及时淘汰。测试样本同样固化为只读资产——页面结构、节点树快照、手势序列打包进版本库，谁复现谁拉取。

最后注明验证环境三要素：系统版本、设备形态、无障碍服务开关状态。缺一项，报告就只能算参考材料；守住这条线，数据才配得上"可复现"三个字。

还有一个边界值得单独立项：多模态并存时的指标口径。振动、播报、高亮对比三种反馈同时触发时，各自的耗时口径要拆开统计，合并统计会把慢的那一路拖快、快的那一路拖慢，得出的均值毫无诊断价值。清单里按反馈通道分列，各自记录首帧耗时与完成耗时，再单独加一组"三通道并发"的对照样本。这组数据在低端机型上尤其有价值——资源紧张时系统会主动降级某一路反馈，降级策略是否可控、用户是否可感知，都要有数字支撑。

最后把验收口径写死：任何一项无障碍指标不达基线，视为功能缺陷而非体验优化项，随版本闭环。无障碍的可复现性不只为报告好看，它直接决定老年用户和视障用户每天打开应用时得到的是不是同一种体验。

补充一条：验证脚本要记录每次运行的服务版本号，无障碍框架的底层实现随系统小版本也会变，同样的用例在两个小版本间的差异，往往是排查回归的第一线索。