原生可折叠组件应使用和,仅允许一层嵌套,open属性控制默认展开,禁用display/visibility强制显示,样式定制需重置::marker并处理焦点,JS操作应直接设置open属性并监听toggle事件。

用 details 和 summary 实现原生可折叠组件
HTML 原生就支持折叠展开,不需要 JS 或 CSS 框架——details 元素就是为此设计的。summary 作为其唯一必须的子元素,会自动变成可点击的标题栏,点击后展开/收起其余内容。
常见错误是把多个 summary 放进一个 details,或试图用 div 模拟行为却忽略语义和键盘可访问性。正确写法只有一层嵌套:
<details>
<summary>点击展开说明</summary>
<p>这里是被折叠的内容,可以是任意 HTML 元素。</p>
<ul>
<li>支持列表</li>
<li>也支持表格、代码块等</li>
</ul>
</details>
默认展开要加 open 属性,别用 CSS 强制显示
details 默认收起,加 open 属性即可默认展开。这是布尔属性,写上即生效,不用赋值:open 或 open="" 都行,但 open="false" 无效。
立即学习“前端免费学习笔记(深入)”;
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
不要用 style="display: block" 或 visibility: visible 强行显示内容——这会破坏 details 的状态同步,JS 读取 open 属性仍为 false,且屏幕阅读器无法感知真实状态。
- ✅ 正确:
<details open><summary>默认展开</summary>...</details> - ❌ 错误:
<details style="display:block">...</details> - ⚠️ 注意:CSS 动画不直接支持
open状态切换,需配合details[open] > *手动控制过渡
样式定制要针对 summary 和 details 分开处理
浏览器对 summary 有默认小三角图标(::marker),且在不同系统下渲染差异大(比如 macOS 不显示箭头,Windows 显示)。想统一外观,得显式重置:
- 隐藏原生箭头:
summary::marker { content: "" } - 自定义图标(如 + / −):
summary::before { content: "▶"; },再用details[open] summary::before { content: "▼" } - 禁用默认 outline:
summary:focus { outline: none },但记得补上可访问的焦点样式 - 避免给
summary设display: block后丢失点击区域——它默认是display: list-item,改之前先测试点击热区
需要 JS 控制时,优先操作 open 属性而非 DOM 显示
如果页面逻辑需要动态展开/收起(比如按钮触发、表单验证后展开错误详情),直接设置 details.open = true/false 即可。浏览器会同步更新 UI、触发 toggle 事件,并保持语义正确。
别用 element.style.display = "none" 切换——这会让 open 属性和视觉状态脱节,影响无障碍体验,也干扰后续 JS 判断。
- ✅ 推荐:
document.querySelector("details").open = true - ✅ 监听切换:
details.addEventListener("toggle", () => console.log(details.open)) - ⚠️ 注意:
toggle事件在初始化时不会触发(即使带open属性),只响应用户点击或 JS 修改open
多组折叠组件共存时,每个 details 独立维护自己的 open 状态,无需额外管理索引或 ID——只要结构清晰,就很难出错。


















