Collapse

可以折叠 / 展开的内容区域。

基础示例

基础用法

用于将复杂的内容区域分组和隐藏，可折叠或展开。默认可以展开多个面板。

外观与状态

禁用

通过 disabled 禁用面板。

布局与排列

嵌套面板

本组配置对照

配置	作用	相关示例
default-value	非受控初始展开面板	嵌套面板、展开图标位置
destroy-on-hide	是否在隐藏时销毁内容	嵌套面板
offset	展开面板是否显示间距	展开间距
expand-icon-position	展开图标在标题区域的 left 或 right 位置，默认 left；不控制内容展开方向	展开图标位置
show-expand-icon	是否显示展开图标；未设置时由子项决定	展开图标位置

面板多层嵌套。

展开间距

通过 offset 控制展开面板之间的间距。

展开图标位置

通过 expand-icon-position 属性设置展开图标的位置。

内容与展示

手风琴模式

本组配置对照

配置	作用	相关示例
default-value	非受控初始展开面板	手风琴模式、边框与分隔线、展开图标
accordion	手风琴模式，同时最多展开一项	手风琴模式
bordered	是否显示边框	边框与分隔线
divider	是否显示面板分割线	边框与分隔线
destroy-on-hide	是否在隐藏时销毁内容	隐藏时销毁

通过 accordion 开启手风琴模式，同时只能打开一个面板。手风琴模式下 modelValue 仍为数组，最多包含一项。

边框与分隔线

比较外边框和面板间分隔线，分别展开面板观察两种装饰的边界。

配置说明与使用限制

无边框模式

通过设置 bordered="false" 隐藏边框。

分割线

通过 divider 控制面板之间的分割线。

额外节点

通过 extra 可以设置额外节点。点击 extra 区域不会触发展开。

展开图标

为展开项自定义展开图标。父级 expand-icon 插槽会下发给未自定义图标的子项。

隐藏时销毁

通过设置 destroy-on-hide 可以让面板内容在隐藏时销毁。

自定义与插槽

自定义样式

本组配置对照

配置	作用	相关示例
default-value	非受控初始展开面板	自定义样式
bordered	是否显示边框	自定义样式

自定义面板样式。

交互与控制

切换全部

通过 toggleAll 批量展开 / 收起面板。手风琴模式下不可用。

阅读方向

继承最近的 dir="ltr|rtl"，支持运行时切换与局部覆盖。标题文字与扩展内容继承阅读方向，展开状态不因切换方向改变。expand-icon-position 的 left/right 始终表示物理侧，不改为逻辑起止；自定义展开图形不额外镜像。

API

主值使用普通 v-model：modelValue 表示展开面板的 name 数组，手风琴模式也使用数组。defaultValue 仅在创建时初始化非受控状态，之后修改不会重置当前值；初始化不触发 update:modelValue。提供 modelValue 时由父级控制，以受控值为准。

Props

属性	说明	类型	默认值
model-value	当前展开面板的 name，支持 v-model	(string | number)[]	—
default-value	非受控初始展开面板	(string | number)[]	[]
accordion	手风琴模式，同时最多展开一项	boolean	false
show-expand-icon	是否显示展开图标；未设置时由子项决定	boolean	—
expand-icon-position	展开图标在标题区域的 left 或 right 位置，默认 left；不控制内容展开方向	'left' | 'right'	'left'
bordered	是否显示边框	boolean	true
divider	是否显示面板分割线	boolean	true
offset	展开面板是否显示间距	boolean	false
destroy-on-hide	是否在隐藏时销毁内容	boolean	false

Events

Event	Description	Arguments
update:model-value	请求更新展开面板	(string | number)[]
change	展开面板变化时触发	(string | number)[], Event

Slots

Slot	Description	Scope
default	面板列表	—

Methods

Method	Description
toggleAll	开启或关闭所有面板（手风琴模式下无效）

父级可通过 expand-icon 插槽下发默认展开图标，作用域为 expanded、disabled、position。该插槽由子项读取，不在根节点渲染。

CollapseToggleAllOptions

参数	描述	类型	默认值
expand	'inverse' 切换全部；boolean 控制全部展开或收起	'inverse' | boolean	—
skipDisabled	是否跳过禁用面板	boolean	false

<collapse-item> Props

参数名	描述	类型	默认值
name (必填)	面板唯一标识，对应 modelValue 中的值	string | number	—
title	面板的标题	string	—
disabled	是否禁用	boolean	false
show-expand-icon	是否显示展开图标	boolean	true
destroy-on-hide	是否在隐藏时销毁内容	boolean	false

<collapse-item> Slots

插槽名	描述	参数
title	面板的标题	—
extra	额外内容	—
expand-icon	展开图标	expanded: boolean disabled: boolean position: 'left' | 'right'
default	面板内容	—

类型定义

组件导出以下类型定义。Collapse.Item 与 CollapseItem 为同一组件。

import type { CollapseInstance, CollapseToggleAllOptions, ExpandIconPosition } from '@cedar-design/ui'

颜色变量

Collapse 的公开颜色变量使用 system 语义作为默认值，Cedar 与 Maple 保持一致：

变量	默认语义
--c-collapse-border-color	--c-sys-color-border-default
--c-collapse-title-bg	--c-sys-color-surface-default
--c-collapse-title-bg-active	--c-sys-color-surface-default
--c-collapse-title-bg-disabled	--c-sys-color-surface-default
--c-collapse-title-text-color	--c-sys-color-content-primary
--c-collapse-title-text-color-disabled	--c-sys-color-content-disabled
--c-collapse-content-text-color	--c-sys-color-content-primary
--c-collapse-content-text-color-disabled	--c-sys-color-content-disabled
--c-collapse-content-bg	--c-sys-color-surface-muted
--c-collapse-expand-icon	var(--c-sys-color-content-secondary)
--c-collapse-item-border-color	--c-sys-color-border-default

减少动态效果

内置 CSS 过渡遵循 prefers-reduced-motion: reduce。关闭过渡不改变最终显隐、选中／展开状态及事件语义；插槽内自定义动画由应用自行控制。