原生元素是唯一开箱即用、无需JS/CSS即可满足WCAG 2.1 AA级无障碍要求的方案;它自动提供tabindex="0"、aria-expanded/aria-hidden同步、Enter/Space响应及焦点管理,而手写方案若漏掉aria-hidden、键盘事件或焦点控制,即默认不可访问。

原生 details 元素是唯一能开箱即用、无需 JS/CSS 就满足 WCAG 2.1 AA 级折叠展开无障碍要求的方案;所有手写 div + aria-expanded 的实现,只要没同步 aria-hidden、没处理键盘事件、没管理焦点,就默认不可访问。
为什么不用 details/summary 就大概率翻车
开发者常以为“加了 aria-expanded 就算无障碍”,但屏幕阅读器(如 NVDA、VoiceOver)需要整套信号:状态变化必须可感知、内容显隐必须同步隐藏语义、键盘操作必须响应 Enter/Space。而 details 原生提供:
-
summary自动获得tabindex="0",支持 Tab 进入、Enter/Space 切换 - 浏览器自动切换
open属性,并同步aria-expanded和aria-hidden - 视觉箭头、焦点样式、禁用态(
disabled在summary上)全部内置 - 不依赖 JS,服务端渲染后即可被读屏器识别
手写方案里漏掉任意一项——比如只改 display: none 却不设 aria-hidden="true"——NVDA 仍会朗读被“视觉隐藏”的子内容。
details 元素必须遵守的结构约束
summary 必须是 details 的第一个子元素,否则语义断裂、键盘导航失效。常见错误写法:
<details><div class="wrapper">
<summary>标题</summary><p>内容</p><div class="aritcle_card flexRow artxards">
<div class="artcardd flexRow">
<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20d3191a227.jpg" alt="DeepBI DHTML 页面生成器" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a rel="nofollow" href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器" class="overflowclass">DeepBI DHTML 页面生成器</a>
<p class="overflowclass">生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力:
- 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面;
- 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”;
- 提及位于 `apps/console/src/featur</p>
</div>
<a rel="nofollow" href="/xiazai/skill12116" title="DeepBI DHTML 页面生成器" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
</a>
</div>
</div>
</div>
</details>
这会导致 summary 失去原生行为(无法空格触发、焦点丢失)。正确结构只能是:
<details><summary>标题</summary><p>内容</p> <ul><li>列表项</li></ul></details>
如果必须包裹容器(如加边框、阴影),应把样式直接加在 details 上,而非插入中间层。
需要动画时怎么不破坏无障碍
details 默认无过渡,加 CSS 动画时容易踩坑:
- 不能对
details或summary直接设transition,它们不响应 height/max-height 变化 - 动画目标必须是
details[open] > *的直接子元素(即summary后的首个兄弟节点) - 推荐用
max-height+overflow: hidden,并预估最大高度(如max-height: 500px),避免用auto - 必须保留
open属性变更的语义信号——JS 不该移除open,而应通过 class 控制动画,否则读屏器收不到状态更新
示例关键 CSS:
details > *:not(summary) {
overflow: hidden;
max-height: 0;
transition: max-height 0.3s ease, opacity 0.3s ease;
}
details[open] > *:not(summary) {
max-height: 500px;
opacity: 1;
}
复杂场景下必须手动实现时的关键补救点
当业务强制要求自定义树形控件、横向折叠组或带图标按钮等场景,无法使用 details 时,以下三点缺一不可:
- 点击目标必须是
button元素(不是div+role="button"),否则 disabled 同步、键盘响应、焦点管理全失效 - 折叠容器需设
role="region"或role="group",并在其上动态切换aria-hidden="true/false",与aria-expanded成对操作 - 展开后,焦点必须用
focus()移入首项(如第一个input或可聚焦子元素),否则键盘用户卡在按钮上无法继续操作
最容易被忽略的是最后一项:视觉上内容已展开,但焦点没跟过去,等于对键盘用户“锁死”了后续交互路径。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










