仅用 CSS 的 display 切换无过渡效果且破坏层叠优先级，必须用 max-height + overflow: hidden 配合 transition 实现动画； 需满足：summary 为首个子元素、不可嵌套、默认展开用 open 属性。

直接用

+

就能实现基础折叠，无需 JS；但要加动画、改图标、支持多级或响应式联动，就必须用 JS 控制 max-height 和类名切换。

为什么不能只靠 display: none/block 切换？

它没有过渡效果，视觉突兀；更关键的是会破坏 CSS 层叠优先级——element.style.display 的权重高于样式表里的 display 声明，后续维护时容易覆盖失效。

• 想加淡入/滑动动画？必须用 max-height + overflow: hidden 模拟，再配 transition
• height: auto 无法参与 CSS 过渡，所以不能写 transition: height 0.3s
• 安全的 max-height 值建议预估：比如最多 8 行文本 × 行高 24px ≈ 200px，设 max-height: 200px；收起时设 max-height: 0

必须满足的三个硬性条件

浏览器只认这三条，缺一不可，否则点击无反应。

• 必须是
  的第一个子元素（不能套
  或

  

  DeepBI DHTML 页面生成器

  生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur

  下载

  包裹）
• 不能嵌套另一个
  （Safari 和部分旧版 Chrome 会直接忽略内层）
• 要默认展开，只能加 open 属性：
  ；用 JS 设置 element.open = true 也行，但属性写法更可靠

JS 方案里最容易漏掉的 event.stopPropagation()

当折叠项里有链接、按钮或可点击子元素时，不加这句就会触发冒泡，导致点子项也把整个面板收起来了。

• 监听 click 时，在 handler 开头加 event.stopPropagation()
• 别用 element.style.display = "none" 控制显隐——改用 classList.toggle("is-open")，然后在 CSS 里写 .is-open { max-height: 300px; }
• 如果侧边栏有多个可折叠项，用事件委托比给每个按钮单独绑函数更轻量：监听父容器，再用 event.target.matches(".toggle-btn") 判断来源

真正麻烦的从来不是“怎么展开”，而是“展开后内容高度不确定时怎么让动画不卡顿、不截断”——max-height 值设小了内容被切，设大了动画拖沓，动态读取 scrollHeight 又可能触发重排。生产环境里，多数人最终还是选个保守值硬编码，而不是追求完美自适应。