屏幕朗读顺序和视觉顺序不一致：HarmonyOS 自定义控件别再靠创建顺序碰运气
页面视觉顺序是搜索框、筛选按钮、内容列表，屏幕朗读却先钻进列表，最后才回到筛选。自定义控件的组件树、创建时机和视觉位置不一定一致，靠“看起来排在前面”无法保证焦点顺序。HarmonyOS 的无障碍指南已经把自定义控件走焦顺序列为单独场景；工程上应把顺序当成一张有向图来维护。
先把边界说明白
| 关注点 | 应该怎么理解 | 容易踩的坑 |
| 语义节点 | 用户能理解和操作的最小单元 | 装饰节点不应抢焦点 |
| next 关系 | 从当前节点到下一个节点 | 不能形成无出口循环 |
| 动态页面 | 筛选项、弹窗或空态会增删节点 | 状态变化后重新生成关系 |
这张表不是把官方文档换一种说法，而是把接口边界变成能检查的工程条件。适配前先确认当前应用是否命中条件，再决定是否改代码。没有命中的模块不应为了“统一写法”一起重构，命中的模块也不能只改到编译不报错。
案例一：把组合控件收敛成一个语义节点
价格卡片可能包含标题、单位、数值和趋势图。若四个子节点都可聚焦，用户需要滑动四次才能离开。先生成一段完整可理解的描述，把装饰性图形从走焦图中排除；卡片只有在本身可点击时才成为操作节点。
type PriceCard = { name: string; value: number; unit: string; trend: 'up'|'down'|'flat'; clickable: boolean }; function accessibilityText(card: PriceCard): string { const trendText = card.trend === 'up' ? '上涨' : card.trend === 'down' ? '下降' : '持平'; return card.name + '，' + card.value + card.unit + '，' + trendText; } const text = accessibilityText({ name: '内存占用', value: 128, unit: 'MB', trend: 'down', clickable: true }); if (!text.includes('下降')) throw new Error('语义信息不完整');这一段先验证外围决策。它的价值是让输入和结果可重复，不依赖页面当前碰巧处于什么状态；接入 ArkUI 或系统能力时，再把结果映射成实际节点、路由或接口调用。
案例二：弹窗出现后把焦点限制在弹窗内部
确认弹窗打开时，背景列表不能继续进入走焦序列。关闭弹窗后，焦点应回到触发它的按钮，而不是回到页面第一个元素。可以用纯函数根据页面状态生成顺序，再把结果映射到实际无障碍属性。
function focusOrder(dialogOpen: boolean): string[] { return dialogOpen ? ['dialog-title', 'dialog-cancel', 'dialog-confirm'] : ['search', 'filter', 'list']; } const modal = focusOrder(true); if (modal.includes('list') || modal[modal.length - 1] !== 'dialog-confirm') throw new Error('弹窗焦点泄漏'); const page = focusOrder(false); if (page.join('>') !== 'search>filter>list') throw new Error('页面顺序错误');第二个案例故意覆盖与第一个不同的失败条件。真实工程还应加入快速重复操作、前后台切换、窗口尺寸变化、空数据和恢复路径，避免只验证一次成功流程。
为什么选择这种做法
手工给几十个节点逐个写 next 容易在条件渲染后断链；按页面状态生成焦点图更容易检查。验收不能只看属性值，需要打开屏幕朗读，覆盖单指左右滑、弹窗开关、列表空态、字体放大和横竖屏。
如果团队准备封装，建议把公开接口保持在“输入事实、输出决策”的层级，不让调用方直接依赖底层节点对象。这样既方便复用，也便于写断言；需要系统能力的部分留在薄薄的适配层，升级时更容易定位。
怎样验证，哪些结论还不能提前说
先把验证分成三层。第一层是纯逻辑：输入、状态转换和边界条件可以在宿主环境运行断言；第二层是 API 26 编译：检查接口签名、系统能力和模型约束；第三层才是目标设备：检查触摸、键鼠、屏幕朗读、横竖屏、窗口缩放和前后台恢复。三层证据不能混在一句“已经跑通”里。
当前示例中的纯 TypeScript 决策函数可以独立测试，用于证明分支没有自相矛盾；涉及 ArkUI 节点、系统手势、跨设备能力和系统服务的片段，仍要使用 API 26 SDK 编译，并在支持该能力的 HarmonyOS 7 设备或云调试设备上验收。这样写不是保守，而是避免把没有发生过的真机结果当成事实。
动态页面还要观察状态变化后的第二次结果：首次进入正确，不代表弹窗关闭、列表更新或窗口缩放后仍然正确。每次状态切换都应重新核对当前节点、焦点目标、返回路径和数据快照，避免旧缓存继续影响新页面。
建议每次留下以下记录：
- DevEco Studio、SDK、targetSdkVersion 和设备系统版本。
- 触发输入、页面层级、窗口尺寸、操作方式与最终状态。
- 正常路径、空数据、快速重复操作、旋转或窗口缩放后的结果。
- 屏幕朗读、字体放大、深浅色和键盘焦点是否仍然可用。
- 性能对照使用同一批数据、同一设备状态和同一测量区间。
可以复用成什么
不要把适配判断散落在页面 Builder 中。更稳的结构是“能力探测或尺寸输入 -> 纯函数决策 -> 页面渲染 -> 设备证据”。纯函数负责输出稳定的布局或交互意图，页面只消费结果；下一次系统升级时，优先修改边界层和测试样本，不必把所有页面重新翻一遍。
发布前自查
- 文章讨论的是 HarmonyOS 7 / API 26 当前资料，不拿旧版本页面替代新接口。
- 两个案例的输入、失败现象和解决目标不同，不是同一段代码换名称。
- 代码中的常量有来源；没有来源的数值明确写成示例策略，不伪装成系统规定。
- 性能、兼容性与无障碍结论都有可重复的检查方法。
- 日志不保存账号、文件内容、设备标识和其他敏感数据。
官方资料
- 提升屏幕朗读无障碍体验
- 2026 年 7 月开发者月刊
