ARIA role仅在原生标签无法满足语义需求时精准使用，如自定义控件、旧项目补足界标、动态内容区域；必须配合aria-label/labelledby命名界标，正确配置aria-live触发时机，dialog需同时满足role、aria-modal、aria-labelledby及焦点管理。

role属性不是万能补丁，而是语义缺口的精准填充

原生HTML标签（如 、

、

）自带完整无障碍语义，浏览器和读屏器对它们有强共识。强行给 加 role="link" 或给 手动设 aria-checked，反而会导致状态不同步、读屏器误判。

ARIA role 只在以下情况必须介入：

• 用
  或 实现自定义控件（如模拟开关、下拉菜单容器）
• 旧项目无法重构语义结构，需临时补足界标或结构性语义（如 role="article" 包裹旧版
  ）
• 动态内容区域缺乏上下文（如单页应用中 JS 插入的弹窗、通知条）

界标角色（Landmark Roles）要配合 aria-label 或 aria-labelledby 才算生效

仅写 role="navigation" 或 role="search"，读屏器只能识别“这是导航区”，但无法区分“主导航”和“侧边导航”。用户靠键盘快捷键（如 NVDA 的 D 键跳界标）切换时，会卡在一堆没名没姓的 navigation 里。

正确做法是显式命名：


DeepBI DHTML 页面生成器
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
下载
• 相关链接

• 避免重复命名：同一页面不能有两个 aria-label="主导航"，否则读屏器无法定位唯一目标

aria-live="polite" 和 aria-live="assertive" 的触发时机差异极大

aria-live 不是“只要 DOM 改了就朗读”，它依赖更新方式和读屏器当前模式。常见失效场景：

• 用 innerHTML = ... 替换整个
  内容 → 节点被销毁重建，读屏器丢失监听上下文
• 只改子元素文本但没触发 DOM 变更事件（如纯 JS 修改 textContent 后未触发 aria-live 检测）
• 用户正处在 VoiceOver 的“浏览模式”（非焦点模式），aria-live="polite" 可能被静默丢弃；aria-live="assertive" 才强制打断
• 错误地把 aria-live 加在 上——它只对容器内动态插入的内容有效，按钮自身状态变化应靠 aria-pressed 或 aria-expanded

role="dialog" 必须配齐三个要素，缺一不可

仅加 role="dialog"，读屏器只会读“对话框”，不会锁定焦点、不会屏蔽背景、也不会自动聚焦标题。真实模态框需同时满足：

• role="dialog" + aria-modal="true"（明确告知辅助技术这是模态层）
• aria-labelledby="dialog-title"（指向可见标题，提供可访问名称）
• JS 层面实现焦点锁定：打开时 focus() 到第一个可聚焦元素（如确认按钮），Tab/Shift+Tab 在内部循环，关闭后恢复到触发按钮
• 禁用 aria-hidden="true" 在 上——现代方案优先用 inert 属性，或手动 tabindex="-1" + focus() 控制

最易被忽略的是焦点管理逻辑：没有它，键盘用户会直接 Tab 出模态框，操作背景内容，而读屏器根本意识不到“对话框已打开”。