警告框必须用 role="alertdialog" 并显式声明 aria-modal="true",配合 aria-labelledby/aria-describedby 指向可见DOM元素,打开时同步管理焦点、背景 inert 状态及键盘隔离,关闭后恢复所有状态并回归原始触发点焦点。

警告对话框必须用 role="alertdialog",不是 role="dialog"
用 role="dialog" 处理警告会丢失关键语义:屏幕阅读器不会主动打断当前播报,用户可能完全错过“删除不可撤销”这类关键信息。只有 role="alertdialog" 才能触发强制中断式播报,且隐含 aria-modal="true" 的行为预期(尽管仍需显式声明)。
常见错误:
- 把
role="alert"直接加在按钮或文本上——它只适用于非模态、纯文本类提示,不能承载交互控件 - 用
role="dialog"+aria-live="assertive"曲线救国——aria-live不作用于模态层本身,无法保证焦点进入和背景屏蔽 - 漏掉
aria-modal="true"——即使写了role="alertdialog",旧版 JAWS 或某些 VoiceOver 配置下仍可能朗读背景内容
aria-labelledby 和 aria-describedby 必须指向真实、可见、已挂载的元素
警告框里标题和描述文案不能是 JS 动态生成后还没插入 DOM 的字符串,也不能是 display: none 或 visibility: hidden 的节点。读屏器只认“存在且可访问”的 DOM 节点。
正确做法:
立即学习“前端免费学习笔记(深入)”;
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
- 标题用
<h2 id="warn-title">确认删除?</h2>,然后aria-labelledby="warn-title" - 描述用
<p id="warn-desc">此操作不可撤销</p>,再通过aria-describedby="warn-desc"关联 - 两个 ID 必须在警告框
<div role="alertdialog"> 内部或同级已渲染完成——不能靠 <code>innerHTML =后再设属性打开时必须同步处理焦点、
aria-hidden和键盘隔离仅设
aria-modal="true"不足以阻止键盘用户误触背景。用户 Tab 到背景链接、Enter 触发跳转,就彻底绕过警告逻辑。必须三步一起做:
- 用
focus()把焦点移到警告框内第一个可聚焦元素(通常是「取消」按钮) - 给背景容器(比如
<main></main>或自定义 wrapper)加inert属性;若需兼容旧浏览器,改用tabindex="-1"+ 手动拦截 Tab 键并preventDefault - 绝对不要对
加aria-hidden="true"——整页从可访问树中消失,键盘用户直接失焦卡死
关闭后必须清除状态,否则警告框“假死”
用户点「确定」或「取消」后,如果只隐藏 DOM 却没清理 ARIA 状态,下次再打开时读屏器可能仍报“已关闭的警告框”,或焦点管理失效。
收尾动作缺一不可:
- 移除
aria-modal="true"(设为"false"或直接removeAttribute) - 恢复背景容器的
inert状态(或移除tabindex="-1") - 将焦点切回触发警告的原始按钮(用
originalButton.focus()),否则键盘用户停留在空白处 - 如果用了
aria-busy控制加载态,此时也必须设回"false",避免后续通知被静音
最易被忽略的是焦点回归路径——很多实现关掉警告后让焦点落在
或丢失,这对盲人用户等于“操作成功但找不到下一步”。 - 用


















