details 元素配合 summary 可原生实现语义化、无障碍友好的树状折叠目录,无需 JavaScript;嵌套 details 即可构建多级结构,支持 open 属性默认展开,CSS 可自定义箭头;IE 不支持,需降级为 JS 方案并用 aria-expanded 和 max-height 实现动画与状态同步。

用 details 和 summary 最快实现可折叠目录
不用写一行 JavaScript,原生 HTML 就能做树状折叠目录——details 元素就是为此设计的。它天然支持点击展开/收起,语义正确,屏幕阅读器友好,且默认有浏览器级过渡(部分浏览器需加简单 CSS 触发动画)。
常见错误是硬套 div + 手动 toggle class,结果既要写 JS 控制状态,又要补 ARIA 属性,还容易忽略键盘操作(如回车、空格触发)。
实操建议:
-
details必须直接包裹一个summary作为标题,其余内容为折叠体;嵌套多个details即可形成树状 - 若想默认展开,加
open属性:<details open></details> - Chrome/Firefox/Safari 均支持,IE 完全不支持——如需兼容 IE,必须降级为 JS 方案(见下节)
- 去除
summary默认箭头:用summary::marker { content: "" },再自定义图标更稳妥
需要兼容 IE 或自定义动画时,用 aria-expanded + classList.toggle()
当项目必须跑在 IE11 上,或要求展开有高度渐变动画(details 不支持 CSS height 过渡),就得手动控制。核心是用 aria-expanded 同步状态,并靠 JS 切换 max-height 或 height。
立即学习“前端免费学习笔记(深入)”;
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
容易踩的坑:
- 直接设
height: 0→height: auto无法过渡,得用max-height配合足够大的固定值(如max-height: 500px),并确保子元素无溢出隐藏干扰 - 忘记同步
aria-expanded="true/false",导致读屏软件无法感知状态变化 - 用
click监听但没处理键盘事件,应同时监听keydown并响应Enter和Space - 嵌套时未阻止事件冒泡,点子级
summary会触发父级折叠——加event.stopPropagation()
ul + li 结构里怎么加折叠按钮而不破坏语义
很多 CMS 或文档系统输出的是纯 ul/li 目录结构,没法直接塞 details。这时要在 li 内插入按钮,但不能让按钮脱离列表项语义。
正确做法:
- 按钮放在
li开头,role="button"+aria-expanded+aria-controls="target-id",指向下一个ul - 被控的子
ul加id和role="group",便于辅助技术识别 - 用
display: none切换显示时,别用visibility: hidden——它仍占空间且对读屏软件不可见 - 避免给
li自身加onclick,否则整个列表项都变成可点击区域,影响操作精度
为什么不要用 display: none 控制初始状态
如果目录数据来自后端或静态生成,有人会直接给子 ul 加 style="display: none" 实现“默认收起”。这看似省事,但埋了三个隐患:
- SEO 友好性下降:搜索引擎可能认为隐藏内容权重低,尤其多层嵌套时
- 首屏渲染时发生重排:JS 运行前 DOM 已按
display: none渲染,后续 JS 显示时触发 layout,影响性能 - 无障碍失效:没有
aria-expanded和状态同步,视障用户无法得知该节点是否可展开 - 正确做法是初始不设隐藏,用 JS 检测后统一收起,并立即补全所有 ARIA 属性
树状目录真正的复杂点不在折叠逻辑本身,而在于状态同步粒度——每个节点是否独立控制?展开时要不要自动收起兄弟节点?这些业务规则一旦叠加,就很容易把简单的 DOM 操作搞成状态管理泥潭。


















