折叠 Collapsible - Svelte - Semi Design Next

使用场景

Collapsible 是一个行为组件，默认开启动画效果。它被用于 Semi 的各种组件中，如：Navigation， Collapse, Tree， TreeSelect，以及 Typography 中。
当上述组件不能满足需求或者需要自定义一些折叠行为时，可以使用 Collapsible 来包裹需要展开或者折叠的内容。

代码演示

如何引入

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

基本用法

通过 isOpen 来控制内容的展开或者折叠。

代码

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

    let isOpen = $state(false);
</script>

<div>
    <Button aria-controls="collapsible-basic" aria-expanded={isOpen} onclick={() => (isOpen = !isOpen)}>Toggle</Button>
    <Collapsible id="collapsible-basic" {isOpen}>
        <ul>
            <li>
                <p>Semi Design 以内容优先进行设计。</p>
            </li>
            <li>
                <p>更容易地自定义主题。</p>
            </li>
            <li>
                <p>适用国际化场景。</p>
            </li>
            <li>
                <p>效率场景加入人性化关怀。</p>
            </li>
        </ul>
    </Collapsible>
</div>

自定义动画时间

通过 duration 设置动画展开或者折叠的时间，也可以通过 motion 来关闭动画。

设置动画时间：

代码

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

    let isOpen = $state(false);
    let duration = $state(250);
</script>

<div>
    <span id="collapsible-duration-label">设置动画时间：</span>
    <InputNumber aria-labelledby="collapsible-duration-label" min={0} onChange={(value) => (duration = Number(value))} step={10} style="width: 120px" value={250} />
    <br />
    <Button aria-controls="collapsible-duration" aria-expanded={isOpen} onclick={() => (isOpen = !isOpen)}>Toggle</Button>
    <Collapsible {duration} id="collapsible-duration" {isOpen}>
        <ul>
            <li>
                <p>Semi Design 以内容优先进行设计。</p>
            </li>
            <li>
                <p>更容易地自定义主题。</p>
            </li>
            <li>
                <p>适用国际化场景。</p>
            </li>
            <li>
                <p>效率场景加入人性化关怀。</p>
            </li>
        </ul>
    </Collapsible>
</div>

嵌套使用

代码

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

    let isOpen = $state(false);
    let isChildOpen = $state(false);
</script>

<div>
    <Button aria-controls="collapsible-nested" aria-expanded={isOpen} onclick={() => (isOpen = !isOpen)}>Toggle</Button>
    <br />
    <Collapsible id="collapsible-nested" {isOpen}>
        <div>
            <span>Semi Design的设计原则包括：</span>
            <Button aria-controls="collapsible-nested-list" aria-expanded={isChildOpen} onclick={() => (isChildOpen = !isChildOpen)}>Toggle List</Button>
        </div>
        <Collapsible id="collapsible-nested-list" isOpen={isChildOpen}>
            <ul>
                <li>
                    <p>Semi Design 以内容优先进行设计。</p>
                </li>
                <li>
                    <p>更容易地自定义主题。</p>
                </li>
                <li>
                    <p>适用国际化场景。</p>
                </li>
                <li>
                    <p>效率场景加入人性化关怀。</p>
                </li>
            </ul>
        </Collapsible>
    </Collapsible>
</div>

自定义折叠高度

可以使用 collapseHeight 自定义收起的高度

Semi Design 以内容优先进行设计。
更容易地自定义主题。
适用国际化场景。
效率场景加入人性化关怀。

代码

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

    let isOpen = $state(false);

    const maskStyle = $derived(isOpen ? undefined : '-webkit-mask-image: linear-gradient(to bottom, black 0%, rgba(0, 0, 0, 1) 60%, rgba(0, 0, 0, 0.2) 80%, transparent 100%)');
    const linkStyle = 'position: absolute; left: 0; right: 0; width: 100%; padding: 0; border: none; background: none; font-size: inherit; font-family: inherit; line-height: inherit; text-align: center; bottom: -10px; font-weight: 700; cursor: pointer; color: var(--semi-color-link)';
</script>

<Button aria-controls="collapsible-height" aria-expanded={isOpen} onclick={() => (isOpen = !isOpen)}>Toggle</Button>
<div style="position: relative">
    <Collapsible collapseHeight={60} id="collapsible-height" {isOpen} style={maskStyle}>
        <ul>
            <li>
                <p>Semi Design 以内容优先进行设计。</p>
            </li>
            <li>
                <p>更容易地自定义主题。</p>
            </li>
            <li>
                <p>适用国际化场景。</p>
            </li>
            <li>
                <p>效率场景加入人性化关怀。</p>
            </li>
        </ul>
    </Collapsible>
    {#if !isOpen}
        <button aria-controls="collapsible-height" aria-expanded={isOpen} style={linkStyle} type="button" onclick={() => (isOpen = !isOpen)}>+ Show More</button>
    {/if}
</div>

API 参考

Props

属性	说明	类型	默认值
children	需要展开或收起的内容的 snippet。	`Snippet`	-
collapseHeight	收起时的高度，单位为像素。	`number`	`0`
collapseHeightAdaptive	内容高度小于 collapseHeight 时，收起高度是否取内容高度。	`boolean`	`false`
duration	动画执行的时间，单位为毫秒。	`number`	`250`
fade	是否开启淡入淡出。	`boolean`	`false`
id	内层内容元素的 id，可配合触发器的 aria-controls 使用；不读全局默认值。	`string`	-
isOpen	是否展开内容区域。	`boolean`	`false`
keepDOM	是否保留隐藏的内容 DOM 树，默认销毁。	`boolean`	`false`
lazyRender	配合 keepDOM 使用，为 true 时挂载时不渲染内容，首次展开后才渲染。	`boolean`	`false`
motion	是否开启动画。	`boolean`	`true`
onMotionEnd	展开或收起动画结束时调用。	`Type`	-

class、style 与其他原生属性和事件落在外层 wrapper 上；id 是组件声明的 prop，落在内层内容元素上，且不读全局默认值。使用方的 ontransitionend 与组件自身的处理同时触发。

Accessibility

ARIA

Collapsible 具有 id props，传入的值会被设置为内层内容元素的 id（不是外层 wrapper），触发按钮用 aria-controls 指向它，并用 aria-expanded 表示当前是否展开，见下方使用示例。

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

    const collapseId = 'myCollapsible';
    let visible = $state(false);
</script>

<Button aria-controls={collapseId} aria-expanded={visible} onclick={() => (visible = !visible)}>
    {visible ? 'hide' : 'show'}
</Button>
<Collapsible id={collapseId} isOpen={visible}>
    <div>hide content</div>
</Collapsible>

焦点

collapseHeight 为 0 时，收起的内容设为 inert，读屏读不到，Tab 也到不了。
collapseHeight 大于 0 时，收起后露出的预览区与被裁掉的部分是同一个元素，不能只隐藏被裁掉的部分，所以整段内容保持可读、可聚焦，读屏用户能读到全文。被裁掉的部分里不要放链接、按钮等可聚焦元素，否则键盘焦点会落在看不见的位置。

FAQ

为什么使用 Collapsible 没有正常展开?
Collapsible 的展开高度由 CSS 计算，不依赖测量节点高度，父级为 display: none 时切换 isOpen 也能得到正确的展开高度。请先检查 isOpen 是否随状态更新；collapseHeight 大于 0 时，收起状态本来就会露出一部分内容。