折叠面板 - Semi Design Next

代码演示

如何引入

import { Collapse } from '@fibrous/semi-ui-react';

基本用法

可以同时展开多个面板，可以通过 defaultActiveKey 设置默认展开的面板。

代码

import { Collapse } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

手风琴效果

可以通过设置 accordion 使每次只允许展开一个面板。

代码

import { Collapse } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

禁用面板

可以通过设置 disabled 禁用面板。

代码

import { Collapse } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1" disabled>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

隐藏面板展开/收起图标

可以通过设置 showArrow 隐藏面板展开/收起图标。

代码

import { Collapse } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1" showArrow={false}>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

自定义展开图标

可以通过 expandIcon 设置展开图标，collapseIcon 设置折叠图标。传入 null 表示不显示图标。

展开图标在面板收起时显示（表示可以展开），折叠图标在面板展开时显示。

代码

import { IconPlus, IconMinus } from '@fibrous/semi-icons-react';
import { Collapse } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse expandIcon={<IconPlus />} collapseIcon={<IconMinus />}>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

自定义右上角辅助区域内容

通过 extra 设置右上角辅助区域内容。

header 渲染在面板的切换按钮内，只能放文字、图标等非交互内容；extra 位于同一行、按钮之外，可以放按钮、输入框等控件，header 为 string 或 ReactNode 时都生效。

1234

Recommended

代码

import { IconCopy } from '@fibrous/semi-icons-react';
import { Collapse, Tag } from '@fibrous/semi-ui-react';

export default function CollapseDemo() {
    return (
        <Collapse>
            <Collapse.Panel header="This is panel header 1" itemKey="1" extra="1234">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2" extra={<IconCopy />}>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel
                header="This is panel header 3"
                itemKey="3"
                extra={
                    <Tag color="violet" style={{ margin: 0 }}>
                        Recommended
                    </Tag>
                }
            >
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

API 参考

Collapse

Props

属性	说明	类型	默认值
accordion	手风琴模式，每次只展开一个面板。	`boolean`	-
activeKey	受控属性，当前展开面板的 key；`null` 与空字符串表示全部收起。	`string \| string[] \| null`	-
children	`Collapse.Panel` 面板。	`React.ReactNode`	-
className	根元素的类名。	`string`	-
clickHeaderToExpand	点击面板头整行展开收起；为 `false` 时只响应切换按钮和箭头。	`boolean`	`true`
collapseIcon	面板展开时显示的图标，传入 ReactNode；未传时为 `IconChevronUp`，传入 `null` 不显示图标。	`React.ReactNode`	-
defaultActiveKey	初始展开面板的 key。	`string \| string[]`	`""`
expandIcon	面板收起时显示的图标，传入 ReactNode；未传时为 `IconChevronDown`，传入 `null` 不显示图标。	`React.ReactNode`	-
expandIconPosition	展开图标位置，可选 `left`、`right`。	`'left' \| 'right'`	`"right"`
keepDOM	是否保留隐藏面板的 DOM 树，默认销毁；未传时依次读 Collapse、Collapsible 的全局默认值。	`boolean`	-
lazyRender	配合 `keepDOM` 使用，为 `true` 时面板展开前不渲染内容。	`boolean`	`false`
motion	是否开启动画，默认开启；未传时依次读 Collapse、Collapsible 的全局默认值。	`boolean`	-
onChange	切换面板时调用，参数为展开面板的 key 数组与原生 MouseEvent（键盘操作经原生按钮同样是 click）。	`Type`	-
ref	根元素（`div`）的引用。	`Type`	-
style	根元素的样式。	`React.CSSProperties`	-

其他原生属性（如 id、aria-*）落在根元素（.semi-collapse）上。

Collapse.Panel

Props

属性	说明	类型	默认值
children	面板内容。	`React.ReactNode`	-
className	根元素的类名。	`string`	-
disabled	面板是否被禁用。	`boolean`	`false`
extra	面板头右侧的辅助内容，位于切换按钮之外，可以放按钮、输入框等控件。	`React.ReactNode`	-
header	面板头内容，渲染在切换按钮内，不能包含交互元素。	`React.ReactNode`	-
itemKey	必填且唯一，用于匹配 `activeKey` 与 `defaultActiveKey`。	`string`	-
onMotionEnd	展开或收起动画结束时调用。	`Type`	-
ref	根元素（`.semi-collapse-item`）的引用。	`Type`	-
showArrow	是否展示箭头。	`boolean`	`true`
style	根元素（`.semi-collapse-item`）的样式。	`React.CSSProperties`	-

其他原生属性（如 id、aria-*）落在根元素（.semi-collapse-item）上。

Accessibility

ARIA

面板头遵循 WAI-ARIA Accordion 模式：原生 button 外包 role="heading"、aria-level="3" 的元素，按钮的可访问名称是 header 内容。
按钮带 aria-expanded；面板内容仍在 DOM 中时一律带指向它的 aria-controls：展开时总在；收起时内容在 DOM 中的情况包括 keepDOM 生效（含只在 Collapsible 的全局默认值里设置 keepDOM）且内容已经渲染过，例如 keepDOM 加 lazyRender 下展开过一次再收起；lazyRender 尚未渲染的收起面板没有内容，不带 aria-controls。
面板内容是 role="region"，通过 aria-labelledby 以按钮为名称；keepDOM 保留的收起内容设置 inert。
展开图标是装饰，设置 aria-hidden="true"；extra 位于按钮之外。
disabled 面板使用按钮的原生 disabled 属性。

键盘和焦点

每个面板头按钮是一个 Tab 停靠点，禁用面板被跳过。
焦点在按钮上时按 Enter 或 Space 展开或收起面板，clickHeaderToExpand 为 false 时同样有效。
extra 中的控件是各自的 Tab 停靠点。

文案规范

折叠面板本质是卡片容器增加了收起和展开的功能，所以折叠面板的文案规范需要和卡片文案规范保持一致

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$color-collapse_item-border-default	var(--semi-color-border)	分割线颜色
$color-collapse_header-text-default	var(--semi-color-text-0)	标题文字颜色
$color-collapse_header-text-disabled	var(--semi-color-disabled-text)	标题文字颜色禁用
$color-collapse_header-icon-default	var(--semi-color-text-2)	展开箭头图标颜色
$color-collapse_header-bg-hover	var(--semi-color-fill-0)	菜单项背景颜色 - 悬浮
$color-collapse_header-bg-active	var(--semi-color-fill-1)	菜单项背景颜色 - 按下
$color-collapse_content-text-default	var(--semi-color-text-1)	内容文字颜色
$font-collapse_header-fontWeight	$font-weight-bold	标题字重
$spacing-collapse_header-marginX	$spacing-tight	标题水平外边距
$spacing-collapse_header-marginY	$spacing-extra-tight	标题垂直外边距
$spacing-collapse_header-padding	$spacing-tight	标题内边距
$spacing-collapse_right-paddingRight	$spacing-tight	图标右侧内边距
$spacing-collapse_header_iconLeft-marginRight	8px
$spacing-collapse_content-paddingTop	$spacing-extra-tight	内容顶部内边距
$spacing-collapse_content-paddingRight	$spacing-base	内容右侧内边距
$spacing-collapse_content-paddingBottom	$spacing-tight	内容底部内边距
$spacing-collapse_content-paddingLeft	$spacing-base	内容左侧内边距
$radius-collapse_header	var(--semi-border-radius-small)	内容圆角大小
$width-collapse_item-border	1px	分割线宽度
$size-collapse_icon-default	$width-icon-medium	图标尺寸

FAQ

Collapse 内嵌表单收起后表单数据会清空 ?

Collapse 收起之后，默认会销毁相应的 DOM 。所以相应的 field 被卸载了，数据也被清空。可以将 Collapse 的 keepDOM 设为 true，保留对应的 DOM 节点。
面板头整行是折叠、展开的点击热区，在这一行放置控件（例如 Input）后，点击它会导致 Collapse 收起/展开。如何避免？

控件放在 extra 而不是 header 中：header 位于切换按钮内，不能包含控件。设置 clickHeaderToExpand 为 false 时只有切换按钮和箭头响应点击；否则在控件的点击回调中阻止事件冒泡至面板头即可，若控件未提供 event 对象，在外层包裹元素的点击回调中阻止冒泡亦可，见下方示例。

import React from 'react';
import { Collapse, Input } from '@fibrous/semi-ui-react';

() => (
    <Collapse>
        <Collapse.Panel
            header="Panel header"
            extra={
                <span onClick={(e) => e.stopPropagation()}>
                    <Input aria-label="面板备注" />
                </span>
            }
            itemKey="1"
        >
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
        </Collapse.Panel>
    </Collapse>
);