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

    进度条

    用于展示用户操作的当前进度和状态，一般在操作耗时较长时使用。也可用来表示任务/对象的完成度

    代码演示

    如何引入

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

    标准的进度条

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






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

<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>

    不确定状态的进度条

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


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

<div style="width: 240px">
    <Progress aria-label="正在加载" indeterminate />
    <br />
    <Progress aria-label="正在加载" indeterminate size="large" />
    <div style="display: flex; align-items: center; gap: 16px; margin-top: 20px">
        <Progress aria-label="正在加载" indeterminate type="circle" />
        <Progress aria-label="正在加载" indeterminate size="small" type="circle" />
    </div>
</div>

    展示百分比文本

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

    10%

    25%

    50%

    500‰
    代码
    <script lang="ts">
    import { Progress } from '@fibrae/semi-ui-svelte';
</script>

<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>
        {#snippet format({ percent })}{percent * 10}‰{/snippet}
    </Progress>
</div>

    垂直的进度条

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

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

<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>

    环形进度条

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

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

<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>

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

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

<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>

    小号的环形进度条

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

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

<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" />

    动态改变进度

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

    40%
    代码
    <script lang="ts">
    import { IconChevronLeft, IconChevronRight } from '@fibrae/semi-icons-svelte';
    import { Button, Progress } from '@fibrae/semi-ui-svelte';

    let percent = $state(40);
</script>

<div>
    <Progress aria-label="disk usage" {percent} showInfo />
    <Button aria-label="减少" disabled={percent === 0} theme="light" onclick={() => (percent -= 10)}>
        {#snippet icon()}
            <IconChevronLeft />
        {/snippet}
    </Button>
    <Button aria-label="增加" disabled={percent >= 100} theme="light" onclick={() => (percent += 10)}>
        {#snippet icon()}
            <IconChevronRight />
        {/snippet}
    </Button>
</div>
    代码
    <script lang="ts">
    import { IconChevronLeft, IconChevronRight } from '@fibrae/semi-icons-svelte';
    import { Button, Progress } from '@fibrae/semi-ui-svelte';

    let cirPerc = $state(40);
</script>

<div>
    <div>
        <Progress aria-label="disk usage" percent={cirPerc} type="circle" />
    </div>
    <Button aria-label="减少" disabled={cirPerc === 0} theme="light" onclick={() => (cirPerc -= 10)}>
        {#snippet icon()}
            <IconChevronLeft />
        {/snippet}
    </Button>
    <Button aria-label="增加" disabled={cirPerc >= 100} theme="light" onclick={() => (cirPerc += 10)}>
        {#snippet icon()}
            <IconChevronRight />
        {/snippet}
    </Button>
</div>

    自定义中心文字内容

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

    75Days
    Done
    代码
    <script lang="ts">
    import { Progress } from '@fibrae/semi-ui-svelte';
</script>

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

    圆角/方角边缘

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

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

<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" />

    自定义进度条颜色

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

    10%
    10%
    代码
    <script lang="ts">
    import { IconChevronLeft, IconChevronRight } from '@fibrae/semi-icons-svelte';
    import { Button, Progress } from '@fibrae/semi-ui-svelte';

    let percent = $state(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>

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

    自动补齐颜色区间

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

    0%
    0%
    65%
    代码
    <script lang="ts">
    import { IconChevronLeft, IconChevronRight } from '@fibrae/semi-icons-svelte';
    import { Button, Progress, Space } from '@fibrae/semi-ui-svelte';

    let percent = $state(65);
    let percentInterval = $state(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.
    $effect(() => {
        const current = percentInterval;
        const timer = setTimeout(
            () => {
                percentInterval = current > 100 ? 0 : current + 3;
            },
            current === 0 || current > 100 ? 1200 : 290 - (current % 50) * 3
        );
        return () => clearTimeout(timer);
    });
</script>

<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} showInfo size="large" stroke={strokeArr} strokeGradient />
</div>
<Button aria-label="Decrease" disabled={percent === 0} theme="light" onclick={() => (percent -= 5)}>
    {#snippet icon()}
        <IconChevronLeft />
    {/snippet}
</Button>
<Button aria-label="Increase" disabled={percent === 100} theme="light" onclick={() => (percent += 5)}>
    {#snippet icon()}
        <IconChevronRight />
    {/snippet}
</Button>

    API 参考

    Props

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

    class、style（字符串）与原生属性（id、aria-label、aria-labelledby、aria-valuetext 等）落在根元素（role="progressbar"）上。

    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 所代表的具体数值含义
    <!-- 推荐用法 -->
<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... " />

    文案规范

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

    设计变量

    下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。
    Sass 变量值用法
    $color-progress_default-bgvar(--semi-color-fill-0)默认背景色
    $color-progress_track_inner-bgvar(--semi-color-success)默认进度色
    $color-progress_line_text-textvar(--semi-color-text-0)百分比文本文字颜色
    $color-progress_circle-textvar(--semi-color-text-0)环形进度百分比文字颜色
    $motion-progress-transition_duration0.3s进度条动画时长
    $motion-progress-transition_timing_functioncubic-bezier(0.62, 0.05, 0.36, 0.95)进度条动画曲线
    $height-progress_horizontal4px水平进度条高度
    $height-progress_horizontal_large6px大尺寸水平进度条高度
    $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-fontWeight600百分比文本字重
    $width-progress_line_text45px百分比文本最小宽度
    $width-progress_vertical4px垂直进度条宽度
    $width-progress_vertical_large6px大尺寸垂直进度条宽度
    $radius-progress_trackvar(--semi-border-radius-small)背景圆角大小
    $radius-progress_track_innervar(--semi-border-radius-small)进度条圆角大小