> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/collapse.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Collapse 折叠面板

按需展开或收起一组内容。


## 基础用法

通过 `items` 提供标题与内容，`defaultActiveKey` 设置初始展开项。默认允许同时展开多个面板；`disabled` 禁止切换对应标题。


项目介绍

项目资料与协作说明。

更新记录

已归档

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/collapse/basic.tsx"
import { Collapse } from '@ifhover/leaf-ui';

export function CollapseBasic() {
  return (
    <Collapse
      defaultActiveKey="about"
      items={[
        { key: 'about', label: '项目介绍', children: '项目资料与协作说明。' },
        { key: 'updates', label: '更新记录', children: '查看最近的功能与内容更新。' },
        { key: 'archived', label: '已归档', children: null, disabled: true },
      ]}
    />
  );
}
```

展开代码


## 示例

### 手风琴

设置 `accordion` 后最多展开一个面板，也可以全部收起。受控使用 `activeKey` 与 `onChange`；回调始终返回 `string[]`，包括手风琴模式。


项目介绍

项目资料与协作说明。

更新记录

已归档

accordion.tsx

复制代码

```tsx lineNumbers file="../../src/examples/collapse/accordion.tsx"
import { Collapse } from '@ifhover/leaf-ui';

export function CollapseAccordion() {
  return (
    <Collapse
      accordion
      defaultActiveKey="about"
      items={[
        { key: 'about', label: '项目介绍', children: '项目资料与协作说明。' },
        { key: 'updates', label: '更新记录', children: '查看最近的功能与内容更新。' },
        { key: 'archived', label: '已归档', children: null, disabled: true },
      ]}
    />
  );
}
```

展开代码

### 内容保留与销毁

未打开过的内容按需挂载，访问过的内容默认在收起后保留。输入草稿后收起再展开，可继续编辑；开启 `destroyInactive` 后，收起动画结束会卸载内容，重新打开时内部非受控值恢复初始状态。组件外部的受控状态仍由应用管理。


收起后销毁内容

草稿

项目名称

preserve-content.tsx

复制代码

```tsx lineNumbers file="../../src/examples/collapse/preserve-content.tsx"
import { Collapse, Flex, Form, FormField, Input, Switch } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CollapsePreserveContent() {
  const [destroy, setDestroy] = useState(false);
  return (
    <Flex direction="column" gap="md">
      <Flex>
        <Switch checked={destroy} onChange={(event) => setDestroy(event.target.checked)}>
          收起后销毁内容
        </Switch>
      </Flex>
      <Collapse
        defaultActiveKey="draft"
        destroyInactive={destroy}
        items={[
          {
            key: 'draft',
            label: '草稿',
            children: (
              <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
                <FormField label="项目名称">
                  <Input name="project" placeholder="Leaf Garden" />
                </FormField>
              </Form>
            ),
          },
        ]}
      />
    </Flex>
  );
}
```

展开代码

### 标题操作

使用 `extra` 在标题旁放置独立操作。附加按钮不会切换面板；此例只更新阅读状态。


通知

标记已读

未读

extra.tsx

复制代码

```tsx lineNumbers file="../../src/examples/collapse/extra.tsx"
import { Button, Collapse, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function CollapseExtra() {
  const [read, setRead] = useState(false);
  return (
    <Flex direction="column" gap="md">
      <Collapse
        items={[
          {
            key: 'notice',
            label: '通知',
            children: '文档已更新。',
            extra: (
              <Button size="sm" disabled={read} onClick={() => setRead(true)}>
                标记已读
              </Button>
            ),
          },
        ]}
      />
      <Text role="status" tone="muted">
        {read ? '已读' : '未读'}
      </Text>
    </Flex>
  );
}
```

展开代码


## API

### Collapse API

面板数据、展开状态与手风琴模式的配置。

| 属性                 | 类型                                             | 默认值     | 说明                                |
| ------------------ | ---------------------------------------------- | ------- | --------------------------------- |
| `items`            | `readonly `[`CollapseItem`](#collapseitem)`[]` | 必填      | 面板列表                              |
| `activeKey`        | `string \| readonly string[]`                  | —       | 受控展开项；可传字符串或数组，手风琴模式只取第一项。        |
| `defaultActiveKey` | `string \| readonly string[]`                  | `[]`    | 非受控模式的初始展开项。                      |
| `onChange`         | `(keys: string[]) => void`                     | —       | 展开项变化时始终返回字符串数组；全部关闭返回空数组。        |
| `accordion`        | `boolean`                                      | `false` | 同时只展开一个面板                         |
| `size`             | `'sm' \| 'md' \| 'lg'`                         | `'md'`  | 标题尺寸                              |
| `bordered`         | `boolean`                                      | `true`  | 显示边框                              |
| `destroyInactive`  | `boolean`                                      | `false` | 退出动画后卸载关闭的内容；默认保留访问过的内容，未访问项延迟挂载。 |

### CollapseItem

折叠面板条目的标题、内容和状态。

| 属性         | 类型          | 默认值     | 说明                           |
| ---------- | ----------- | ------- | ---------------------------- |
| `key`      | `string`    | 必填      | 唯一标识                         |
| `label`    | `ReactNode` | 必填      | 可展开标题。                       |
| `children` | `ReactNode` | 必填      | 展开后的内容。                      |
| `disabled` | `boolean`   | `false` | 禁止通过标题切换展开，不禁用 extra 中的独立操作。 |
| `extra`    | `ReactNode` | —       | 标题旁的内容                       |
