details 和 summary 是 HTML 原生支持卡片折叠展开的唯一语义化方案,现代浏览器全支持,无需 JS 或 CSS 动画;手动用 JS 控制 display 或 max-height 会破坏可访问性且状态易不同步,而 details 本就内置状态管理、焦点控制和默认箭头。

details 和 summary 是 HTML 原生支持卡片折叠展开的唯一语义化方案,现代浏览器(Chrome 12+、Firefox 49+、Safari 12.1+、Edge 79+)全支持,无需 JS、不依赖 CSS 动画即可工作。
为什么不用 JS 控制 display 或 max-height?
手动监听 click + 切换 display 或 max-height 会破坏可访问性:键盘无法用空格/回车触发、屏幕阅读器识别不到状态、Safari 15.4+ 下容易状态不同步。更关键的是,details 本就是为此设计的语义元素——它自带状态管理、焦点控制和默认箭头,绕开它等于自己重造轮子还造得不稳。
- 不要给
details设height: 0或overflow: hidden,这会干扰 Safari 的展开逻辑 - 不要把
summary包在div里,或让它不是details的第一个子元素,否则点击完全无效 - 避免在
summary里放button或a,Safari 旧版本对嵌套交互支持不稳定
基础写法与常见结构错误
正确结构必须满足两个硬性条件:summary 是 details 的**首个子元素**,且必须是**成对标签**(不能自闭合)。以下写法才生效:
<details> <summary>标题</summary> <p>内容可以是任意 HTML</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/cb6835dc7db1" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">前端免费学习笔记(深入)</a>”;</p> <img src="..." alt="示例"> </details>
这些写法都会失效:
-
<summary></summary>(自闭合)→ 浏览器不识别为可交互元素 -
<details><p>标题</p> <summary>内容</summary></details>→p占了第一个子位置,summary被忽略 -
<details open="true"></details>→open是布尔属性,只存在即生效,写open="true"反而可能被某些解析器误判
如何加旋转箭头但不破坏语义?
原生 summary::marker 在 Safari 15.4 之前支持差,图标常消失且无 fallback。稳妥做法是禁用默认 marker,用 summary::before 自定义:
summary {
list-style: none; /* 清掉原生箭头 */
}
summary::before {
content: "▶";
margin-right: 8px;
transition: transform 0.2s;
}
details[open] summary::before {
transform: rotate(90deg);
}切记不能写 summary { display: block; }——这会让它退化为普通文本,失去按钮语义和键盘可访问性。
需要滑动动画时怎么安全过渡?
details 原生只做显隐切换,不支持高度动画。真要“向下展开”的丝滑感,就得放弃原生切换逻辑,改用 max-height + transition 手动控制:
- 初始状态:
max-height: 0; overflow: hidden; - 展开状态:
max-height: 500px;(不能是auto或none,CSS 无法对它们做过渡) - 必须配
transition: max-height 0.3s ease-out; - JS 只需操作
open属性或 class,不要直接改style.display
预估的 max-height 值宁大勿小;如果卡片内容差异极大(比如含代码块+高清图),设 800px 比 300px 更安全,否则动画中途会被截断。



















