进度条 - Semi Design Next

代码演示

如何引入

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

标准的进度条

通过stroke属性来控制进度条的填充色
通过percent属性控制已完成的进度
通过size属性控制进度条尺寸
通过aria-label说明进度条具体代表含义
如果size预设的尺寸不满足，可以通过style传入 height 自定义进度条高度

代码

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

<template>
    <div :style="{ width: '200px' }">
        <Progress aria-label="disk usage" :percent="10" stroke="var(--semi-color-warning)" />
        <br />
        <Progress aria-label="disk usage" :percent="25" stroke="var(--semi-color-danger)" />
        <br />
        <Progress aria-label="disk usage" :percent="50" />
        <br />
        <Progress aria-label="download progress" :percent="80" />
        <br />
        <Progress aria-label="disk usage" :percent="80" size="large" />
        <br />
        <Progress aria-label="disk usage" :percent="80" :style="{ height: '8px' }" />
    </div>
</template>

不确定状态的进度条

当任务进度无法计算时，可设置 indeterminate 展示不确定状态。该属性支持条状和环形进度条；开启后 percent 不再控制进度长度，且不会展示 showInfo 文本。

代码

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

<template>
    <div :style="{ width: '240px' }">
        <Progress aria-label="正在加载" indeterminate />
        <br />
        <Progress aria-label="正在加载" indeterminate size="large" />
        <div :style="{ display: 'flex', alignItems: 'center', gap: '16px', marginTop: '20px' }">
            <Progress aria-label="正在加载" indeterminate type="circle" />
            <Progress aria-label="正在加载" indeterminate size="small" type="circle" />
        </div>
    </div>
</template>

展示百分比文本

通过showInfo控制是否展示百分比数字，可以通过#format插槽格式化展示文本

10%

25%

50%

500‰

代码

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

<template>
    <div :style="{ width: '200px' }">
        <Progress aria-label="disk usage" :percent="10" showInfo stroke="var(--semi-color-warning)" />
        <br />
        <Progress aria-label="disk usage" :percent="25" showInfo stroke="var(--semi-color-danger)" />
        <br />
        <Progress aria-label="disk usage" :percent="50" showInfo />
        <br />
        <Progress aria-label="disk usage" :percent="50" showInfo>
            <template #format="{ percent }">{{ percent * 10 }}‰</template>
        </Progress>
    </div>
</template>

垂直的进度条

设置direction='vertical'，展示垂直进度条，可以通过style传入 width 控制进度条宽度

代码

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

<template>
    <div :style="{ height: '100px', display: 'flex' }">
        <Progress aria-label="disk usage" direction="vertical" :percent="10" />
        <Progress aria-label="disk usage" direction="vertical" :percent="25" />
        <Progress aria-label="disk usage" direction="vertical" :percent="50" />
        <Progress aria-label="disk usage" direction="vertical" :percent="80" size="large" />
        <Progress aria-label="disk usage" direction="vertical" :percent="80" :style="{ width: '8px' }" />
    </div>
</template>

环形进度条

将 type 设为circle，进度条将会展示成环状。进度条默认尺寸为 72 x 72

代码

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

<template>
    <div>
        <Progress aria-label="disk usage" :percent="10" :style="{ margin: '5px' }" type="circle" />
        <Progress aria-label="disk usage" :percent="25" :style="{ margin: '5px' }" type="circle" />
        <Progress aria-label="disk usage" :percent="50" :style="{ margin: '5px' }" type="circle" />
        <Progress aria-label="disk usage" :percent="80" :style="{ margin: '5px' }" type="circle" />
    </div>
</template>

你可以通过修改width来控制环形进度条的大小

代码

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

<template>
    <div>
        <Progress aria-label="disk usage" :percent="100" :style="{ margin: '5px' }" type="circle" :width="100" />
    </div>
    <div>
        <Progress aria-label="disk usage" :percent="100" stroke="var(--semi-color-danger)" :style="{ margin: '5px' }" type="circle" :width="100" />
    </div>
</template>

小号的环形进度条

小号进度条默认尺寸为 24 x 24

代码

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

<template>
    <Progress aria-label="disk usage" :percent="10" size="small" :style="{ margin: '5px' }" type="circle" />
    <Progress aria-label="disk usage" :percent="25" size="small" :style="{ margin: '5px' }" type="circle" />
    <Progress aria-label="disk usage" :percent="50" size="small" :style="{ margin: '5px' }" type="circle" />
    <Progress aria-label="disk usage" :percent="80" size="small" :style="{ margin: '5px' }" type="circle" />
</template>

动态改变进度

文字中的数字会以动画过渡到新的 percent。动画进行中再次修改 percent，新动画从当前显示的数字起算。

40%

代码

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

    const percent = ref(40);
</script>

<template>
    <div>
        <Progress aria-label="disk usage" :percent="percent" showInfo />
        <Button aria-label="减少" :disabled="percent === 0" theme="light" @click="percent -= 10">
            <template #icon>
                <IconChevronLeft />
            </template>
        </Button>
        <Button aria-label="增加" :disabled="percent >= 100" theme="light" @click="percent += 10">
            <template #icon>
                <IconChevronRight />
            </template>
        </Button>
    </div>
</template>

代码

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

    const cirPerc = ref(40);
</script>

<template>
    <div>
        <div>
            <Progress aria-label="disk usage" :percent="cirPerc" type="circle" />
        </div>
        <Button aria-label="减少" :disabled="cirPerc === 0" theme="light" @click="cirPerc -= 10">
            <template #icon>
                <IconChevronLeft />
            </template>
        </Button>
        <Button aria-label="增加" :disabled="cirPerc >= 100" theme="light" @click="cirPerc += 10">
            <template #icon>
                <IconChevronRight />
            </template>
        </Button>
    </div>
</template>

自定义中心文字内容

你可以通过 #format="{ percent }" 插槽自定义中心文字，percent 为当前显示的百分比，只有显示文字时才会执行插槽
如果不需要中心文本内容，你可以将 showInfo 设为 false，或者让插槽渲染为空

75Days

Done

代码

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

<template>
    <Progress aria-label="disk usage" :percent="75" showInfo :style="{ margin: '10px' }" type="circle">
        <template #format="{ percent }">{{ percent }}Days</template>
    </Progress>
    <Progress aria-label="disk usage" :percent="100" showInfo :style="{ margin: '10px' }" type="circle">
        <template #format>Done</template>
    </Progress>
    <Progress aria-label="disk usage" :percent="50" :showInfo="false" :style="{ margin: '10px' }" type="circle" />
</template>

圆角/方角边缘

通过 strokeLinecap 属性，你可以控制环形进度条边缘形状

代码

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

<template>
    <Progress aria-label="disk usage" :percent="50" strokeLinecap="round" :style="{ margin: '10px' }" type="circle" />
    <Progress aria-label="disk usage" :percent="50" strokeLinecap="square" :style="{ margin: '10px' }" type="circle" />
</template>

自定义进度条颜色

可通过设置 stroke 属性，自定义具体 percent 的颜色

10%

代码

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

    const percent = ref(10);
    const strokeArr = [
        { percent: 20, color: 'red' },
        { percent: 40, color: 'orange-9' },
        { percent: 60, color: 'light-green-8' },
        { percent: 80, color: 'hsla(125, 50%, 46%, 1)' },
    ];
</script>

<template>
    <div>
        <Progress aria-label="disk usage" :percent="percent" showInfo :stroke="strokeArr" type="circle" :width="100" />
        <Progress aria-label="disk usage" :percent="percent" showInfo :stroke="strokeArr" :style="{ margin: '20px 0 10px' }" />
    </div>
    <Button aria-label="Decrease" :disabled="percent === 0" theme="light" @click="percent -= 10">
        <template #icon>
            <IconChevronLeft />
        </template>
    </Button>
    <Button aria-label="Increase" :disabled="percent === 100" theme="light" @click="percent += 10">
        <template #icon>
            <IconChevronRight />
        </template>
    </Button>
</template>

自动补齐颜色区间

可通过设置 strokeGradient 属性，属性为 true 时自动补齐颜色区间，生成渐变色

65%

代码

<script setup lang="ts">
    import { ref, watchEffect } from 'vue';
    import { IconChevronLeft, IconChevronRight } from '@fibrous/semi-icons-vue';
    import { Button, Progress, Space } from '@fibrous/semi-ui-vue';

    const percent = ref(65);
    const percentInterval = ref(0);
    const strokeArr = [
        { percent: 0, color: 'rgb(249, 57, 32)' },
        { percent: 50, color: '#46259E' },
        { percent: 100, color: 'hsla(125, 50%, 46%, 1)' },
    ];
    const strokeArrReverse = [
        { percent: 0, color: 'hsla(125, 50%, 46%, 1)' },
        { percent: 50, color: '#46259E' },
        { percent: 100, color: 'rgb(249, 57, 32)' },
    ];

    // Each value schedules the next one; restarting after 100 pauses longer.
    watchEffect((onCleanup) => {
        const current = percentInterval.value;
        const timer = setTimeout(
            () => {
                percentInterval.value = current > 100 ? 0 : current + 3;
            },
            current === 0 || current > 100 ? 1200 : 290 - (current % 50) * 3
        );
        onCleanup(() => clearTimeout(timer));
    });
</script>

<template>
    <Space :spacing="20">
        <div>
            <Progress aria-label="file download speed" :percent="percentInterval" showInfo :stroke="strokeArr" strokeGradient type="circle" :width="100" />
        </div>
        <div>
            <Progress aria-label="file download speed" :percent="percentInterval" showInfo :stroke="strokeArrReverse" strokeGradient type="circle" :width="100" />
        </div>
    </Space>
    <div :style="{ width: '100%', margin: '20px 0 10px' }">
        <Progress aria-label="file download speed" :percent="percent" showInfo size="large" :stroke="strokeArr" strokeGradient />
    </div>
    <Button aria-label="Decrease" :disabled="percent === 0" theme="light" @click="percent -= 5">
        <template #icon>
            <IconChevronLeft />
        </template>
    </Button>
    <Button aria-label="Increase" :disabled="percent === 100" theme="light" @click="percent += 5">
        <template #icon>
            <IconChevronRight />
        </template>
    </Button>
</template>

API 参考

Props

属性	说明	类型	默认值
direction	条状进度条的方向，可选 horizontal、vertical。	`ProgressDirection`	`semiDefault("Progress", "direction", "horizontal")`
indeterminate	是否为不确定状态。开启后 percent 不再控制进度长度，且不展示文字，aria-valuenow 省略。	`boolean`	`semiDefault("Progress", "indeterminate", false)`
motion	文字数字是否以动画过渡到新的 percent；关闭后直接跳到目标值。	`boolean`	`semiDefault("Progress", "motion", true)`
orbitStroke	进度条轨道的填充色。	`string`	`semiGlobalDefault("Progress", "orbitStroke")`
percent	进度百分比；传入 NaN 会抛出错误。	`number`	`semiDefault("Progress", "percent", 0)`
showInfo	是否显示文字：环形显示在中间，条状显示在右侧。	`boolean`	`semiDefault("Progress", "showInfo", false)`
size	尺寸，可选 default、small（仅 type 为 circle 时生效）、large（仅 type 为 line 时生效）。	`Size`	`semiDefault("Progress", "size", "default")`
stroke	填充色。数组形式为 `{ percent, color }` 的区间列表，color 可为任意 CSS 颜色或 Semi 色板名。	`string \| StrokeArr`	`semiGlobalDefault("Progress", "stroke")`
strokeGradient	是否自动生成渐变色补齐区间颜色，需要 stroke 至少设置一个颜色区间。	`boolean`	`semiDefault("Progress", "strokeGradient", false)`
strokeLinecap	环形进度条端点形状，可选 round、square。	`"round" \| "square"`	`semiDefault("Progress", "strokeLinecap", "round")`
strokeWidth	环形进度条的线宽。	`number`	`semiDefault("Progress", "strokeWidth", 4)`
type	类型，可选 line、circle。	`ProgressType`	`semiDefault("Progress", "type", "line")`
width	环形进度条的直径；缺省时 size 为 small 时为 24，其他为 72。	`number`	`semiGlobalDefault("Progress", "width")`

Events

事件	说明	回调参数
无

Slots

插槽	说明	作用域参数
format	自定义显示文字，参数 percent 为当前显示的数字（限制在 0 到 100）；只在显示文字时执行。	`{ percent: number; }`

Exposes

名称	说明	类型
无

class、style 与原生属性（id、aria-label、aria-labelledby、aria-valuetext 等）经 attrs 传入根元素。

Accessibility

ARIA

Progress 具有 progressbar role 来表示它是一个进度条组件。
Progress 会自动将 aria-valuenow 设置为传递给组件的进度百分比（percent），以确保屏幕阅读器可以获取正确的百分比数值。当 indeterminate=true 时，由于当前进度未知，不设置 aria-valuenow。另外，Progress 支持传入 aria-valuetext，当你传入时，根据 W3C 规范，aria-valuetext 将优先被屏幕阅读器使用消费，而不是 aria-valuenow
Progress 支持传入 aria-label、aria-labelledby
- 当 Progress 外部存在关于 Progress 作用的描述元素时，你可以通过 aria-labelledby 显式指定某些元素的 id 是 Progress 的标签
- 否则你应当通过 aria-label 说明 Progress 所代表的具体数值含义

<template>
    <!-- 推荐用法 -->
    <p id="progressbar-label">Disk Usage</p>
    <Progress aria-labelledby="progressbar-label" :percent="80" />

    <!-- 推荐用法 -->
    <Progress aria-label="Percent of disk usage" :percent="80" />
    <Progress aria-label="Percent of file downloaded" :percent="80" />

    <!-- 使用 aria-valuetext -->
    <Progress aria-label="Percent of disk usage" :percent="80" aria-valuetext="Step 2: Copying files... " />
</template>

文案规范

如果进度条过程复杂，或者有很长的等待时间，可以使用帮助文本来做说明。这样可以让用户知道正在发生的进度进展

设计变量

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

Sass 变量	值	用法
$color-progress_default-bg	var(--semi-color-fill-0)	默认背景色
$color-progress_track_inner-bg	var(--semi-color-success)	默认进度色
$color-progress_line_text-text	var(--semi-color-text-0)	百分比文本文字颜色
$color-progress_circle-text	var(--semi-color-text-0)	环形进度百分比文字颜色
$motion-progress-transition_duration	0.3s	进度条动画时长
$motion-progress-transition_timing_function	cubic-bezier(0.62, 0.05, 0.36, 0.95)	进度条动画曲线
$height-progress_horizontal	4px	水平进度条高度
$height-progress_horizontal_large	6px	大尺寸水平进度条高度
$spacing-progress_line_text-marginLeft	$spacing-base	水平进度条百分比文本左侧外边距
$spacing-progress_vertical-marginX	$spacing-extra-tight	垂直进度条水平方向外边距
$spacing-progress_horizontal-marginY	$spacing-extra-tight	水平进度条垂直方向外边距
$spacing-progress_vertical_line_text-marginTop	$spacing-tight	垂直进度条百分比文本顶部外边距
$font-progress_line_text-fontWeight	600	百分比文本字重
$width-progress_line_text	45px	百分比文本最小宽度
$width-progress_vertical	4px	垂直进度条宽度
$width-progress_vertical_large	6px	大尺寸垂直进度条宽度
$radius-progress_track	var(--semi-border-radius-small)	背景圆角大小
$radius-progress_track_inner	var(--semi-border-radius-small)	进度条圆角大小