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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/collapse.md.

Collapse 折叠面板

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

基础用法

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

项目资料与协作说明。
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
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
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
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

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

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

CollapseItem

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

属性类型默认值说明
keystring必填唯一标识
labelReactNode必填可展开标题。
childrenReactNode必填展开后的内容。
disabledbooleanfalse禁止通过标题切换展开,不禁用 extra 中的独立操作。
extraReactNode—标题旁的内容