折叠 - Semi Design Next

使用场景

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

代码演示

如何引入

<script setup lang="ts">
    import { Collapsible } from '@fibrous/semi-ui-vue';
</script>

基本用法

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

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Collapsible } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
</script>

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

自定义动画时间

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

设置动画时间：

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Collapsible, InputNumber } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const duration = ref(250);
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
    const setDuration = (value: number | string) => {
        duration.value = Number(value);
    };
</script>

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

嵌套使用

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Collapsible } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const isChildOpen = ref(false);
</script>

<template>
    <div>
        <Button aria-controls="collapsible-nested" :aria-expanded="isOpen" @click="isOpen = !isOpen">Toggle</Button>
        <br />
        <Collapsible id="collapsible-nested" :isOpen="isOpen">
            <div>
                <span>Semi Design的设计原则包括：</span>
                <Button aria-controls="collapsible-nested-list" :aria-expanded="isChildOpen" @click="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>
</template>

自定义折叠高度

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

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

代码

<script setup lang="ts">
    import { computed, ref } from 'vue';
    import { Button, Collapsible } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const maskStyle = computed(() =>
        isOpen.value
            ? {}
            : {
                  WebkitMaskImage: 'linear-gradient(to bottom, black 0%, rgba(0, 0, 0, 1) 60%, rgba(0, 0, 0, 0.2) 80%, transparent 100%)',
              }
    );
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
    const linkStyle = {
        position: 'absolute',
        left: 0,
        right: 0,
        width: '100%',
        padding: 0,
        border: 'none',
        background: 'none',
        fontSize: 'inherit',
        fontFamily: 'inherit',
        lineHeight: 'inherit',
        textAlign: 'center',
        bottom: '-10px',
        fontWeight: 700,
        cursor: 'pointer',
        color: 'var(--semi-color-link)',
    } as const;
</script>

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

API 参考

Props

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

Events

事件	说明	回调参数
motionEnd	展开或收起动画结束时触发。	`[]`

Slots

插槽	说明	作用域参数
default	需要展开或收起的内容。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 传入，落在外层 wrapper 上；id 是组件声明的 prop，落在内层内容元素上，且不读全局默认值（全局设置 id 会让每个实例重复同一个 id）。使用方的 @transitionend 与组件自身的处理同时触发。

Accessibility

ARIA

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

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Collapsible } from '@fibrous/semi-ui-vue';

    const collapseId = 'myCollapsible';
    const visible = ref(false);
</script>

<template>
    <Button :aria-expanded="visible" :aria-controls="collapseId" @click="visible = !visible">
        {{ visible ? 'hide' : 'show' }}
    </Button>
    <Collapsible :isOpen="visible" :id="collapseId">
        <div>hide content</div>
    </Collapsible>
</template>

焦点

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

FAQ

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