HarmonyOS 7API 26Beta2 新增自定义控件走焦顺序指南。开启屏幕朗读后用户可通过单指左右滑动切换焦点当默认顺序不符合业务语义时应用可以重新定义下一个焦点。视觉页面常按位置排列组件但读屏用户依赖的是语义顺序。一个双栏页面在 DOM 或组件树中可能先创建完整左栏再创建右栏读屏却应该按“标题—摘要—主要操作—次要信息”移动。默认顺序一旦与视觉和业务不一致用户会在页面中迷路。本文以“订单详情”页面为例说明如何设计焦点图、处理动态组件、弹窗与错误信息并建立可自动化的无障碍验收。一、先画语义焦点图不要从 API 开始。先列出用户完成任务所需节点页面标题、订单状态、商品、金额、地址、主要按钮、帮助入口。装饰图片、分隔线和重复文案不应获得焦点。interfaceFocusNode{id:stringrole:heading|text|button|link|input|grouplabel:stringrequired:booleannextId?:stringpreviousId?:string}interfaceFocusGraph{route:stringnodes:FocusNode[]}焦点图是页面语义契约可由设计、开发和测试共同评审。二、顺序遵循任务而非组件树订单页优先宣布状态和主要操作错误页面优先错误标题、原因与恢复按钮表单按标签—输入—说明—错误移动。不要为了视觉左右布局就让焦点在两列之间来回跳。constorderFocus:FocusGraph{route:order-detail,nodes:[{id:title,role:heading,label:订单详情,required:true,nextId:status},{id:status,role:text,label:待支付,required:true,nextId:items},{id:items,role:group,label:商品列表,required:true,nextId:pay},{id:pay,role:button,label:立即支付,required:true,nextId:help},{id:help,role:link,label:需要帮助,required:false}]}实际绑定属性以当前 Accessibility Kit 文档为准。三、名称、角色、状态缺一不可“按钮”不是完整标签“提交订单按钮已禁用”才让用户知道对象和状态。图标按钮必须提供可读名称选中、展开、加载和错误状态要随 UI 更新。functionpaymentLabel(state:PaymentState):string{if(state.kindloading)return正在提交支付请稍候if(state.kinddisabled)return立即支付不可用${state.reason}return立即支付金额${state.amountText}}不要把视觉文案简单拼接成冗长朗读应以任务所需信息为准。四、动态内容必须维护焦点商品删除、折叠区域展开和异步刷新会改变节点。如果当前焦点节点消失应移动到合理邻居而不是回到页面顶部或丢失焦点。functionnextAfterRemoval(removedId:string,order:string[]):string|null{constindexorder.indexOf(removedId)if(index0)returnorder[0]??nullreturnorder[index1]??order[index-1]??null}列表使用稳定业务 ID避免排序后焦点落到错误商品。五、错误出现时要主动可感知表单错误不能只把边框变红。提交失败后先宣布摘要再允许用户跳到首个错误字段。若自动移动焦点会打断输入可使用无障碍提示并让用户选择跳转。interfaceFormErrorSummary{count:numberfirstFieldId:stringmessage:string}functionbuildSummary(errors:FieldError[]):FormErrorSummary|null{if(!errors.length)returnnullreturn{count:errors.length,firstFieldId:errors[0].fieldId,message:有${errors.length}项需要修改第一项是${errors[0].label}}}六、弹窗必须形成焦点闭环模态框打开后焦点进入标题或首个主要元素并限制在弹窗内部关闭后恢复到触发按钮。背景内容不应继续被读屏遍历。嵌套弹窗尽量避免。如果无法避免使用栈保存每层触发节点按后进先出恢复。classFocusReturnStack{privateids:string[][]push(id:string){this.ids.push(id)}pop():string|undefined{returnthis.ids.pop()}}七、分栏和折叠屏按语义重排手机单栏与平板双栏可能共享组件但走焦顺序不必跟随组件创建顺序。容器宽度变化后重新生成焦点图并尽量保持当前业务节点 ID。在平行视界中还要区分左右页面所有权右侧详情关闭后焦点回到左侧触发项而不是跳到左栏第一项。八、不要制造焦点陷阱轮播图、可滚动容器、Web 内容和自定义画布最容易形成陷阱。用户必须能进入、操作并离开。长列表不要让每个装饰元素都可聚焦成组内容先提供摘要再允许深入浏览。触控可点击区域与无障碍可操作对象保持一致避免读屏宣布可点击但实际没有响应。九、减少动态与大字体兼容字体放大后文本换行可能改变视觉位置但语义顺序不应变化。关闭动画或减少动态时焦点移动不能依赖转场结束事件。横竖屏切换后重新验证当前元素仍存在。十、自动化检查与人工读屏functionvalidateGraph(graph:FocusGraph):string[]{constidsnewSet(graph.nodes.map(xx.id))consterrors:string[][]for(constnodeofgraph.nodes){if(!node.label.trim())errors.push(${node.id}: empty label)if(node.nextId!ids.has(node.nextId))errors.push(${node.id}: invalid nextId)}returnerrors}describe(order focus graph,(){it(contains no broken edge,()expect(validateGraph(orderFocus)).toEqual([]))})自动化能发现空标签、重复 ID 和断边但不能判断朗读是否自然。必须使用真机屏幕朗读完成核心任务覆盖正向、错误、弹窗和动态更新。十一、上线清单页面有经过评审的语义焦点图装饰元素不聚焦交互元素名称和角色完整选中、禁用、展开和错误状态可朗读动态删除后焦点移动到合理邻居弹窗形成焦点闭环并能返回触发点手机、平板、分栏和大字体顺序一致自动化检查与真机读屏任务均通过。结语自定义走焦不是“给组件编号”而是把页面任务转换成线性、可预测的语义路径。以稳定 ID 管理动态焦点以弹窗闭环和错误摘要保护上下文再通过真机读屏完成验收复杂布局才能真正对所有用户可用。官方参考2026 年 7 月开发者月刊https://developer.huawei.com/consumer/cn/monthly/202607HarmonyOS 无障碍开发资源https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/accessibility-development