组件
    切换框架
    ReactVueSolidSvelte
    切换语言
    简体中文English
    GitHub
    展示类

    折叠面板

    可以展开或折叠展示内容区域。

    代码演示

    如何引入

    <script lang="ts">
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

    Svelte 的面板写成 Collapse.Panel 或具名导出 CollapsePanel，两者是同一组件。Panel 的 header、extra 是 snippet。Panel 只能在 Collapse 内使用，否则抛出说明性错误。

    基本用法

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

    Svelte 没有 defaultActiveKey：只传 activeKey 时作为初始展开的面板；需要读写展开状态时用 bind:activeKey。

    代码
    <script lang="ts">
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

<Collapse>
    <CollapsePanel itemKey="1">
        {#snippet header()}This is panel header 1{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="2">
        {#snippet header()}This is panel header 2{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="3">
        {#snippet header()}This is panel header 3{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
</Collapse>

    手风琴效果

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

    代码
    <script lang="ts">
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

<Collapse accordion>
    <CollapsePanel itemKey="1">
        {#snippet header()}This is panel header 1{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="2">
        {#snippet header()}This is panel header 2{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="3">
        {#snippet header()}This is panel header 3{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
</Collapse>

    禁用面板

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

    代码
    <script lang="ts">
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

<Collapse accordion>
    <CollapsePanel disabled itemKey="1">
        {#snippet header()}This is panel header 1{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="2">
        {#snippet header()}This is panel header 2{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="3">
        {#snippet header()}This is panel header 3{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
</Collapse>

    隐藏面板展开/收起图标

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

    代码
    <script lang="ts">
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

<Collapse accordion>
    <CollapsePanel itemKey="1" showArrow={false}>
        {#snippet header()}This is panel header 1{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="2">
        {#snippet header()}This is panel header 2{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="3">
        {#snippet header()}This is panel header 3{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
</Collapse>

    自定义展开图标

    可以通过 Collapse 的 expandIcon snippet 设置展开图标，collapseIcon snippet 设置折叠图标，用 {#snippet expandIcon()}...{/snippet} 写在 Collapse 标签内。

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

    代码
    <script lang="ts">
    import { IconMinus, IconPlus } from '@fibrae/semi-icons-svelte';
    import { Collapse, CollapsePanel } from '@fibrae/semi-ui-svelte';
</script>

<Collapse>
    {#snippet expandIcon()}
        <IconPlus />
    {/snippet}
    {#snippet collapseIcon()}
        <IconMinus />
    {/snippet}
    <CollapsePanel itemKey="1">
        {#snippet header()}This is panel header 1{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="2">
        {#snippet header()}This is panel header 2{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
    <CollapsePanel itemKey="3">
        {#snippet header()}This is panel header 3{/snippet}
        <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
    </CollapsePanel>
</Collapse>

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

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

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

    1234
    Recommended
    代码
    <script lang="ts">
    import { IconCopy } from '@fibrae/semi-icons-svelte';
    import { Collapse, CollapsePanel, Tag } from '@fibrae/semi-ui-svelte';
</script>

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

    API 参考

    Collapse

    Props

    属性说明类型默认值
    accordion手风琴模式。booleanfalse
    activeKey当前展开面板的 key，可用 bind:activeKey 双向绑定；null 与空字符串表示全部收起。函数绑定 bind:activeKey={get, set} 时完全受控；只传 activeKey 时作为初值，点击在组件内覆盖。string | string[] | null-
    childrenCollapsePanel 面板的 snippet。Snippet-
    clickHeaderToExpand点击面板头整行展开收起；为 false 时只响应切换按钮和箭头。booleantrue
    collapseIcon面板展开时显示的图标的 snippet，默认 IconChevronUp。Snippet-
    expandIcon面板收起时显示的图标的 snippet，默认 IconChevronDown。Snippet-
    expandIconPosition展开图标位置，可选 left、right。'left' | 'right'"right"
    keepDOM是否保留隐藏面板的 DOM 树，默认销毁；未传时依次读 Collapse、Collapsible 的全局默认值。boolean-
    lazyRender配合 keepDOM 使用，为 true 时面板展开前不渲染内容。booleanfalse
    motion是否开启动画，默认开启；未传时依次读 Collapse、Collapsible 的全局默认值。boolean-
    onChange切换面板时调用，参数为展开面板的 key 数组与原生 MouseEvent（键盘操作经原生按钮同样是 click）。Type(activeKey: string[], event: MouseEvent) => void-

    class、style 与原生属性和事件（如 id、aria-*）落在 Collapse 根元素（.semi-collapse）上。onChange 的第一个参数总是 string[]，即使 activeKey 传入的是字符串。

    Collapse.Panel

    Props

    属性说明类型默认值
    children面板内容的 snippet；传入 children 才算有内容。Snippet-
    disabled面板是否被禁用。booleanfalse
    extra面板头右侧辅助内容的 snippet，位于切换按钮之外，可以放控件。Snippet-
    header面板头内容的 snippet，渲染在切换按钮内，不能包含交互元素。Snippet-
    itemKey必填且唯一，用于匹配 activeKey。string-
    onMotionEnd展开或收起动画结束时调用。Type() => void-
    showArrow是否展示箭头。booleantrue

    class、style 与原生属性和事件落在 Panel 根元素（.semi-collapse-item）上。Panel 不读全局默认值，按是否传入 children 判断有无内容。

    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-defaultvar(--semi-color-border)分割线颜色
    $color-collapse_header-text-defaultvar(--semi-color-text-0)标题文字颜色
    $color-collapse_header-text-disabledvar(--semi-color-disabled-text)标题文字颜色 禁用
    $color-collapse_header-icon-defaultvar(--semi-color-text-2)展开箭头图标颜色
    $color-collapse_header-bg-hovervar(--semi-color-fill-0)菜单项背景颜色 - 悬浮
    $color-collapse_header-bg-activevar(--semi-color-fill-1)菜单项背景颜色 - 按下
    $color-collapse_content-text-defaultvar(--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-marginRight8px
    $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_headervar(--semi-border-radius-small)内容圆角大小
    $width-collapse_item-border1px分割线宽度
    $size-collapse_icon-default$width-icon-medium图标尺寸

    FAQ

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

      Collapse 收起之后，默认会销毁相应的 DOM 。所以相应的 field 被卸载了，数据也被清空。可以将 Collapse 的 keepDOM 设为 true，保留对应的 DOM 节点。

    • 面板头整行是折叠、展开的点击热区，在这一行放置控件（例如 Input）后，点击它会导致 Collapse 收起/展开。如何避免？

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

    <script lang="ts">
    import { Collapse, CollapsePanel, Input } from '@fibrae/semi-ui-svelte';
</script>

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