17370845950

原生 和 可实现无 JS/CSS 框架的

折叠面板， 必为 首子元素且需闭合标签；open 属性设默认展开；支持键盘与屏幕阅读器，但动画需 :has() 或 JS 控制类名配合 max-height/opacity 实现。

用

和

实现原生折叠面板

HTML5 原生支持折叠面板，不需要 JS 或 CSS 框架。核心是

（容器）和

（标题行），浏览器自动处理展开/收起状态与切换逻辑。

常见错误是把

写成自闭合标签（如

），它必须有结束标签；另外

必须是

的第一个子元素，否则部分浏览器不识别。

• open 属性可设默认展开：
• 点击区域仅限
  内容，文字外的 padding 不触发切换（需 CSS 扩展点击热区）
• 不支持嵌套
  的动画过渡（transition 对 height 无效，因内容高度是动态计算的）

让折叠内容淡入淡出：CSS + :has() 的兼容性取舍

原生

不支持 CSS 动画，但可通过 :has(> summary:not([open])) 或 JS 监听 toggle 事件来控制类名，再配合 opacity 和 max-height 模拟过渡效果。

注意：:has() 在 Safari 15.4+、Chrome 105+ 支持，旧版 Edge/IE 完全不支持；若需兼容，必须降级为 JS 控制类名（例如监听 details 的 toggle 事件并添加 is-open 类）。

• 避免用 height: auto 做 transition —— 浏览器无法对 auto 做动画，得用 max-height 配合足够大的固定值（如 max-height: 500px）
• 过渡时间建议 ≤ 300ms，过长会削弱响应感
• overflow: hidden 必须加在
  上，否则内容溢出时动画错乱

键盘与屏幕阅读器支持要点

原生

默认支持空格键/回车键切换，且

自动获得 role="button" 和 aria-expanded，语义正确。

容易被忽略的是：若自定义了图标（如 ▶ / ▼），需用 aria-hidden="true" 隐藏，否则屏幕阅读器会重复读图标字符；同时确保焦点能自然落到

，不要用 tabindex="-1" 错误移除。

• 禁用 JavaScript 后仍应可用（原生行为不依赖 JS）
• 避免用 display: none 隐藏内容 —— 应使用 visibility: hidden 或 opacity: 0 配合 pointer-events: none，否则影响可访问性树
• 展开后，焦点不会自动跳转到内容区 —— 如需此行为，得手动 focus()，但要谨慎，可能打断用户操作流

服务端渲染或静态站点中的注意事项

如果页面由 SSR（如 Next.js、Nuxt）或静态生成（如 Jekyll、Hugo）输出，

会直接渲染展开态，无闪烁；但若后续 JS 又去操作 open 属性，可能造成状态不一致。

更隐蔽的问题是：某些 CMS 或 Markdown 解析器会把

当作非法 HTML 过滤掉（尤其老版本）。检查输出源码是否保留了标签，而不是被转义成文本。

• Webpack/Vite 构建中，若用 HTML 插件压缩（如 html-minifier-terser），确认配置未删掉 open 属性（默认通常保留）
• 在 Vue/React 中直接写
  是安全的，但 React 需注意：JSX 中属性名是 open，不是 isOpen，且不能用布尔值变量直接赋值（要用 {isOpen ? 'open' : null} 或 open={isOpen}）

原生折叠最省事，但动画和兼容性要自己兜底；别为了“看起来高级”强行 JS 重写，先确认真实需求里有没有 IE、旧 Safari 或复杂交互动效。