aria-modal="true" 仅声明模态语义，不自动隐藏背景内容，必须配合 aria-hidden="true" 动态屏蔽非模态区域；role="dialog"、aria-labelledby 和 aria-modal="true" 三者缺一不可，且需同步管理焦点与 aria-hidden 状态。

aria-modal="true" 本身不限制辅助工具读取遮罩背景，它只声明“这是一个模态框”，但**不会自动隐藏背景内容**。真正起作用的是配合 aria-hidden="true" 手动屏蔽背景区域。

为什么aria-modal="true"不能单独屏蔽背景

aria-modal="true" 是语义声明，不是行为控制。它告诉屏幕阅读器：“当前焦点上下文是这个对话框”，但浏览器和辅助技术（尤其是 Safari 和旧版 Firefox）可能忽略它，或仅部分支持——背景仍会被朗读、被聚焦、甚至被误认为可操作区域。

常见错误现象：aria-modal="true" 加了，但 VoiceOver 还在读导航栏；NVDA 按 Tab 跳出弹窗后继续朗读页脚。

• aria-modal="true" 必须加在 role="dialog" 元素上，加在遮罩层（overlay）或 body 上无效
• 它对 div、section 等无 role 的元素不起作用
• 设为 "false" 或省略，等同于未启用模态语义

遮罩背景必须用aria-hidden="true"动态控制

遮罩层（灰色半透明 overlay）本身没有语义，不该被辅助工具读取，但**背景主内容（main、header、侧边栏等）才是重点屏蔽对象**。

DeepBI DHTML 页面生成器

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

下载

正确做法：模态框打开时，给所有非模态区域的容器（推荐用

包裹整个主内容）设 aria-hidden="true"；关闭时立即移除或设为 "false"。

• 不要直接对 body 设 aria-hidden="true"——某些屏幕阅读器会跳过整页，用户彻底失联
• 遮罩层可以设 aria-hidden="true" 或 role="presentation"，但更推荐不加任何 ARIA（纯视觉装饰）
• 模态框自身绝不能设 aria-hidden="true"，否则整个弹窗对辅助工具“消失”

role="dialog" 和 aria-labelledby 是前提条件

没有 role="dialog"，aria-modal="true" 就是废属性。辅助技术根本不识别这是对话框，也不会尝试隔离上下文。

aria-labelledby 必须指向一个真实存在的、可见的标题元素（如

确认删除？

），不能只靠 aria-label 替代——否则视觉用户看到标题，屏幕阅读器却读不到上下文。

• role="dialog" 必须搭配 aria-modal="true" 和 aria-labelledby，三者缺一不可
• 标题元素需是原生 heading（h1–h6），不能是 span + CSS 样式模拟
• 如果标题是图标+文字组合，确保 aria-labelledby 同时引用图标 ID 和文字 ID，或用 aria-label 补充语义

真正容易被忽略的点在于：焦点管理（focus()、Tab 循环）和 aria-hidden 切换必须同步发生。哪怕 aria-modal 和 role 都写对了，只要背景没及时 aria-hidden="true"，或者模态框关闭后没清掉它，屏幕阅读器就会立刻“迷路”。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！