必须加aria-live:动态替换内容时屏幕阅读器默认不播报,需用aria-live="polite"(非紧急)或aria-live="assertive"(如错误提示)显式声明变更;不可嵌套在header等landmark内,须与main等同级且每次仅保留一个。

动态替换 <main></main> 内容时必须加 aria-live
JS 用 innerHTML 或框架(如 React)更新 <main></main> 区域内容后,屏幕阅读器默认不会播报变化——它只监听 DOM 变化事件,不主动感知语义区域更新。
解决办法是给 <main></main> 加上 aria-live="polite"(非紧急内容)或 aria-live="assertive"(如表单错误提示),让辅助技术知道“这里的内容变了,需要读出来”。
-
aria-live="polite":等当前语音播报结束再读,适合列表刷新、分页加载 -
aria-live="assertive":立即中断当前播报,适合错误弹窗、验证失败 - 不要把
aria-live放在<div> 或其他非语义容器上——只有挂载在 <code><main></main>或明确的语义区域里才可靠<main></main>不能嵌套在<header></header>、<nav></nav>等 landmark 元素内很多响应式项目为图方便,把
<main></main>写进<header></header>里做“带 banner 的主内容”,这会破坏 landmark 层级。NVDA 和 VoiceOver 会忽略嵌套的<main></main>,键盘用户 Tab 时直接跳过整块内容。正确结构只能是平级并列:
立即学习“前端免费学习笔记(深入)”;
<header></header> <nav></nav> <main></main> <aside></aside> <footer></footer>
-
<main></main>必须是的直接子元素,或至少与其它 landmark 同级 - 如果页面有多个“主内容区”(比如 SPA 中路由切换),每次只保留一个
<main></main>,旧的要移除或设hidden,不能留空占位 - W3C Validator 会报错:
Element main not allowed as child of element header
动态菜单展开时,焦点流和
aria-expanded必须同步更新移动端汉堡菜单点击后只显示视觉层,但 DOM 里的
<nav></nav>仍被display: none或hidden隐藏,键盘用户 Tab 还是会卡在第一个导航链接后,无法进入菜单项。
DeepBI DHTML 页面生成器下载生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
关键动作有三步,缺一不可:
- 用
aria-expanded="true"标记触发按钮状态 - 移除
hidden或改display: block,确保菜单项在 DOM 中可访问 - 菜单展开后,用
.focus()把键盘焦点移到第一个可聚焦元素(如第一个<a></a>)
漏掉任意一步,都会导致键盘用户“看得见、点不进、Tab 不到”。
使用
data-*存储状态时,别绕过aria-属性更新有些团队习惯用
data-is-open="true"控制菜单状态,但屏幕阅读器完全不认这个——它只看aria-expanded、aria-hidden这类标准属性。也就是说,哪怕你 JS 逻辑完全正确,只要没同步设置
aria-属性,对辅助技术来说就是“没变”。-
data-仅用于 JS 内部逻辑,不能替代 ARIA 属性 - 所有影响可访问性的状态变更,必须双写:既更新
data-,也更新对应aria- - 尤其注意
aria-hidden:折叠菜单时设为true,展开时必须设回false,不能只靠 CSS 隐藏
最常被忽略的其实是 DOM 顺序和焦点管理——语义标签写得再标准,只要 JS 动态操作后没重置焦点、没补
aria-live、没清理残留aria-hidden,无障碍就形同虚设。 -


















