文章目录前言为什么要做无障碍无障碍能力概览改动 1语义化标签accessibilityText改动 2焦点管理改动 3朗读支持改动 4高对比度适配改动 5触摸目标扩大测试验证方法写在最后前言说实话我之前写代码从来不考虑无障碍——觉得那是加分项不是必选项。直到有天看到一个视障朋友用读屏软件操作手机那个体验让我破防了。一个没有语义化标签的按钮读屏软件只能读出未命名按钮——你让人家怎么用无障碍不是锦上添花是基本的尊重。好消息是HarmonyOS7 的无障碍适配门槛很低5 个改动就能覆盖大部分场景。今天逐个讲清楚。无障碍Accessibility的目标很简单让所有人都能用你的 App。不只是视障用户还有老年人、手部不便的用户、甚至在强光下看不清屏幕的普通人。你以为无障碍是少数人的需求全球有超过 10 亿残障人士中国超过 8500 万。而且很多应用商店包括 AppGallery已经开始把无障碍作为审核指标了。不做无障碍迟早要补课。为什么要做无障碍不只是道德层面还有实际利益用户覆盖—— 不做无障碍 直接放弃大量潜在用户应用审核—— 部分应用商店已把无障碍纳入评分代码质量—— 语义化标签让代码更清晰方便维护SEO 类比—— 就像网页做 SEO 一样做好无障碍 做好应用优化无障碍能力概览HarmonyOS7 提供的无障碍能力一览能力属性/方法说明|语义化文本|accessibilityText| 给组件添加读屏文本 ||语义化提示|accessibilityHint| 提示操作结果如点击后打开设置 ||焦点管理|accessibilityNextFocusId| 控制焦点移动顺序 ||组件角色|accessibilityRole| 标记组件类型按钮/链接/标题等 ||朗读支持|accessibilityLevel| 控制组件是否可被朗读 ||触摸目标|hitTestBehavior/responseRegion| 扩大可点击区域 ||高对比度|colorMode| 适配高对比度模式 ||分组|accessibilityGroup| 将多个组件作为整体朗读 |改动 1语义化标签accessibilityText这是最重要、最优先要做的一件事。没加accessibilityText的图标按钮读屏软件只能读按钮——用户根本不知道这个按钮是干嘛的。EntryComponentstruct AccessibilityTextDemo{build(){Row({space:16}){Image($r(app.media.icon_search)).width(24).height(24).fillColor(#333333).accessibilityText(搜索).accessibilityHint(点击打开搜索页面)Image($r(app.media.icon_settings)).width(24).height(24).fillColor(#333333).accessibilityText(设置).accessibilityHint(点击打开设置页面)Image($r(app.media.icon_notification)).width(24).height(24).fillColor(#333333).accessibilityText(通知).accessibilityHint(点击查看通知消息)}.padding(16)}}关键代码讲解accessibilityText(搜索)——读屏时会朗读搜索而不是图片或未命名accessibilityHint(点击打开搜索页面)—— 提示操作结果用户知道点了会发生什么所有纯图标按钮必须加这是最低要求原则如果一个组件去掉视觉样式后你不知道它是啥就必须加accessibilityText。改动 2焦点管理默认的焦点移动顺序是按布局从上到下、从左到右。但有些场景需要自定义顺序——比如表单里密码输完后应该跳到确认密码而不是跑到旁边的广告位。EntryComponentstruct FocusOrderDemo{build(){Column({space:12}){TextInput({placeholder:用户名}).width(100%).height(48).id(input_username).accessibilityNextFocusId(input_password)TextInput({placeholder:密码}).width(100%).height(48).id(input_password).type(InputType.Password).accessibilityNextFocusId(input_confirm)TextInput({placeholder:确认密码}).width(100%).height(48).id(input_confirm).type(InputType.Password).accessibilityNextFocusId(btn_register)Button(注册).width(100%).height(48).id(btn_register)}.padding(24)}}关键代码讲解.id(input_username)—— 给组件设 ID焦点管理要用accessibilityNextFocusId(input_password)——指定下一个焦点跳转目标从用户名直接跳到密码这样焦点顺序就是用户名 → 密码 → 确认密码 → 注册按钮不会跳到不该跳的地方改动 3朗读支持有些装饰性元素分割线、背景图、间距不需要被朗读有些关键信息又容易漏掉。用accessibilityLevel和accessibilityGroup来控制EntryComponentstruct ReadLevelDemo{build(){Scroll(){Column({space:16}){Text(今日推荐).fontSize(24).fontWeight(FontWeight.Bold).accessibilityLevel(yes).accessibilityRole(HEADER)Row(){Image($r(app.media.icon_decoration)).width(40).height(40).accessibilityLevel(no)}Row(){Image($r(app.media.icon_avatar)).width(36).height(36).accessibilityText(用户头像)Column(){Text(张三).fontSize(16).fontWeight(FontWeight.Bold)Text(3 分钟前发布).fontSize(12).fontColor(#999)}.margin({left:8}).accessibilityGroup(true).accessibilityText(张三3分钟前发布)}.padding(12).backgroundColor(#f5f5f5).borderRadius(8)}.padding(16)}}}关键代码讲解accessibilityLevel(yes)—— 明确可被朗读默认就是 yes显式写出来更清晰accessibilityLevel(no)——不可朗读装饰性图片用这个读屏会跳过accessibilityGroup(true)——把子组件合并为整体朗读不会分别读张三和3分钟前发布而是一次性读张三3分钟前发布accessibilityRole(HEADER)—— 标记这是标题读屏软件会额外提示标题级别改动 4高对比度适配部分用户会开启系统的高对比度模式如果你的 App 用了浅灰色文字#999999配白色背景高对比度模式下可能直接看不见。EntryComponentstruct HighContrastDemo{StorageLink(isHighContrast)isHighContrast:booleanfalsebuild(){Column({space:12}){Text(普通模式下的提示文字).fontSize(14).fontColor(this.isHighContrast?#000000:#999999)Divider().color(this.isHighContrast?#000000:#e0e0e0).strokeWidth(this.isHighContrast?2:1)Button(确认操作).width(100%).height(48).backgroundColor(#007DFF).fontColor(Color.White)}.padding(24)}}关键代码讲解StorageLink(isHighContrast)—— 监听系统高对比度状态变化fontColor(this.isHighContrast ? #000000 : #999999)——高对比度模式用纯黑普通模式用灰色按钮颜色不用改蓝底白字本身对比度就够实际项目中可以用资源限定词目录resources/high_contrast/自动适配不用手动判断。改动 5触摸目标扩大小图标是触屏的噩梦——看得见点不着。HarmonyOS7 规范建议触摸目标最小 44x44vp但很多图标只有 24x24vp。用responseRegion扩大点击区域EntryComponentstruct TouchTargetDemo{build(){Row({space:24}){Image($r(app.media.icon_back)).width(24).height(24).fillColor(#333333).accessibilityText(返回).responseRegion({x:-10,y:-10,width:44,height:44}).onClick((){console.info(返回被点击)})Image($r(app.media.icon_close)).width(24).height(24).fillColor(#333333).accessibilityText(关闭).responseRegion({x:-10,y:-10,width:44,height:44}).onClick((){console.info(关闭被点击)})}.padding(16)}}关键代码讲解responseRegion({ x: -10, y: -10, width: 44, height: 44 })——扩大可点击区域到 44x44vpx: -10, y: -10—— 向左上各扩展 10vp因为图标本身是 24x24扩展后刚好 44x44视觉大小不变但点击范围变大了——用户感知不到区别但操作准确率大幅提升测试验证方法代码写完了怎么验证无障碍是否生效开启读屏模式设置 → 辅助功能 → 屏幕朗读开启后触摸屏幕即可听到朗读内容焦点导航用音量键上下切换焦点检查焦点顺序是否正确Accessibility InspectorDevEco Studio 自带的检查工具可以查看组件的无障碍属性高对比度测试设置 → 辅助功能 → 高对比度文字开启后检查 UI 是否正常快速自测清单所有图标按钮有accessibilityText装饰性元素有accessibilityLevel(no)表单焦点顺序正确触摸目标 ≥ 44x44vp高对比度模式下文字可读写在最后无障碍适配的 5 个改动按优先级排accessibilityText—— 最重要没这个读屏就是瞎子触摸目标扩大—— 影响所有用户不只是残障用户焦点管理—— 表单场景必做朗读控制—— 避免信息过载或遗漏高对比度适配—— 锦上添花但体现专业度这 5 个改动加起来可能也就半天工作量但对用户的体验提升是质的飞跃。别等应用商店强制要求了再补现在就做。