---
title: Collapse 折叠面板
description: 可展开与收起内容的面板组
category: Layout
status: beta
since: 0.3.4
tags: [collapse, disclosure, layout]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="CollapseBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const active = ref(['first'])
  </script>

  <template>
    <TxCollapse v-model="active">
      <TxCollapseItem title="快速开始" name="first">
        这里是基础说明。
      </TxCollapseItem>
      <TxCollapseItem title="高级选项" name="second">
        这里是高级配置说明。
      </TxCollapseItem>
    </TxCollapse>
  </template>
---
::::

### 手风琴
`accordion` 一次只展开一个面板；再次点击当前面板会将其收起。
::::TuffDemoWrapper{demo="CollapseAccordionDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const active = ref('first')
  </script>

  <template>
    <TxCollapse v-model="active" accordion>
      <TxCollapseItem title="快速开始" name="first">基础内容。</TxCollapseItem>
      <TxCollapseItem title="高级选项" name="second">高级内容。</TxCollapseItem>
    </TxCollapse>
  </template>
---
::::

### 自定义标题
`title` 插槽替换标题文字，箭头仍在其后。

```vue
<template>
  <TxCollapseItem name="security">
    <template #title>
      <TxIcon name="i-carbon-security" />
      安全设置
    </template>
    特权操作需要通行密钥。
  </TxCollapseItem>
</template>
```

### 最佳实践

- 显式提供稳定的 `name`；回退到 `title` 时，本地化或改文案会丢失展开状态。
- 标题只放简短文字，操作与复杂控件放进正文：整个标题都是切换按钮。
- 禁用用于不可用的区块，不要禁用当前展开的面板。
- 长内容在正文内分层，不要层层嵌套折叠面板。
- 内容常驻 DOM，不要在未展开的面板里运行昂贵的常驻任务。

## API 参考

### TxCollapse

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `modelValue` | `string \| string[]` | `undefined` | 展开的面板名称；普通模式为数组，手风琴模式为字符串。 |
| `accordion` | `boolean` | `false` | 一次只展开一个面板。 |

#### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `string \| string[]` | 面板切换后触发。 |
| `change` | `string \| string[]` | 与 `update:modelValue` 同时触发，值相同。 |

#### 插槽

| 插槽名 | Props | 说明 |
|------|-------|------|
| `default` | 无 | `TxCollapseItem` 列表。 |

### TxCollapseItem

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `title` | `string` | `undefined` | 标题文本；缺少 `name` 时也作为身份。 |
| `name` | `string` | `undefined` | 面板的唯一身份。 |
| `disabled` | `boolean` | `false` | 禁止切换。 |
| `arrowIcon` | `string` | `'chevron-down'` | 标题后的箭头图标名，展开时旋转。 |

#### 插槽

| 插槽名 | Props | 说明 |
|------|-------|------|
| `title` | 无 | 箭头之前的自定义标题。 |
| `default` | 无 | 面板正文。 |

## 概述

- 普通模式派发展开名称数组；手风琴模式派发单个名称，收起当前面板时派发 `''`。
- 面板身份依次取 `name`、`title`、`''`。
- 标题是原生 `<button type="button">`，带 `aria-expanded` 与 `aria-controls`；禁用时设置原生 `disabled`。
- 内容通过 `v-show` 隐藏，始终挂载。
- `TxCollapse` 之外的面板项照常渲染，但点击无效。

## 技术实现

- `TxCollapse` 通过 provide / inject 向面板项提供展开状态与切换函数；`<Transition>` 的 JS 钩子把高度从 0 过渡到内容高度，结束后释放为 `auto`。
- 源码：`packages/tuffex/packages/components/src/collapse/`。

<TuffDocSourceLink />