Accordion

折叠和展开分组内容。中文惯用名：折叠面板。设计文档原名：Collapse。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.accordion`
名称	Accordion
二级分类	数据展示（`data-display`）
用途	折叠和展开分组内容
描述	中文惯用名：折叠面板。设计文档原名：Collapse。

预览

静态结构：Accordion 为 data-slot="accordion" 折叠组，每项 data-slot="accordion-item" = 触发行 data-slot="accordion-trigger"（标题 + 行尾 chevron 图标，展开时旋转）+ 内容区 data-slot="accordion-content"；内容区为 items[].children DSL 子树，经 Renderer children 机制渲染。items[].key 作为项 value：multiple 时使用 Base UI multiple 模式（可多项同开），否则 single 模式（点击已展开项即可收起，天然允许全部收起）。

DSL 结构

DslNode

{
  "type": "Accordion",
  "props": {
    "items": [
      {
        "key": "intro",
        "title": "产品简介",
        "children": [
          {
            "type": "Text",
            "props": {
              "text": "Pactor 是一套 DSL 驱动的动态页面框架。"
            }
          }
        ]
      },
      {
        "key": "usage",
        "title": "使用方式",
        "children": [
          {
            "type": "Text",
            "props": {
              "text": "以 YAML/JSON 描述页面结构，经运行时渲染为真实组件。"
            }
          }
        ]
      },
      {
        "key": "faq",
        "title": "常见问题",
        "children": [
          {
            "type": "Text",
            "props": {
              "text": "表达式、数据源与动作均可组合使用，详见使用文档。"
            }
          }
        ]
      }
    ]
  }
}

何时用

何时使用

内容分组收纳：把平级的长内容折叠成若干面板，默认收起以节省纵向空间。
用户按需展开阅读的辅助信息：帮助说明、常见问题、配置分组。
面板之间是并列关系（无父子层级），需要单开或多开。

何时不用

层级数据（父子节点、逐级展开）：使用 Tree——层级数据用 Tree，内容分组收纳用 Accordion。
同区域视图切换、每次只看一个视图：使用 Tabs（Accordion 强调收纳，Tabs 强调切换）。
表单内需要展示大量可折叠字段组且需校验：当前实现不承载表单语义，改用业务侧折叠表单结构。

变体

变体	视觉形态	适用场景
single 单开（缺省）	同时最多展开一个面板	内容较长、希望用户聚焦当前面板
multiple 多开	多个面板可同时展开	面板内容短、需对照阅读（如多项说明）
DSL 子树面板	面板内容由 DSL 节点渲染（可含任意组件）	面板内需要放表格、表单等复杂内容
全部收起	single 模式下可点开项收起至零展开	初始不展开任何面板的节省空间形态

API 属性

属性	类型	默认值	说明
`items`	`AccordionItemData[]`	[]	面板列表（可含表达式解析后的数组）；项结构 { key, title, children?: DslNode[] }
`collapsible`	`boolean`	—	允许收起全部面板（契约兼容字段；Base UI single 模式天然允许收起）
`multiple`	`boolean`	false	允许多个面板同时展开
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

面板 key 必须唯一且稳定，作为展开状态的标识；重复 key 会导致面板联动错乱。
title 用简短名词短语概括面板内容；面板内容本身不要再重复标题信息。
需对照阅读的短内容用 multiple 多开；长内容用缺省单开，减少来回滚动。
面板数量控制在 3-8 个；更多时先分组或改用其他导航结构，避免长列表折叠堆叠。
内容需在折叠状态下也可被检索到时（如 FAQ 搜索），考虑把关键信息摘要提到 title 中。

正例

✓ 帮助中心：items 分「产品简介 / 使用方式 / 常见问题」，缺省单开节省空间。
✓ 配置说明分组：multiple 多开，用户可一边看说明一边对照另一组配置。
✓ 面板内复杂内容：children 传 DSL 子树（Table、Form 等），与页面其他部分同一渲染路径。

反例

✕ 用 Accordion 表达层级父子数据（应使用 Tree）。
✕ 用 Accordion 做同区域视图切换并期待路由 / 深链语义（应使用 Tabs）。
✕ items 使用重复 key，展开一个面板却联动影响其他面板。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。