进度条 - Semi Design Next

代码演示

如何引入

import { Progress } from '@fibrous/semi-ui-solid';

标准的进度条

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

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

不确定状态的进度条

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <div style={{ width: '240px' }}>
            <Progress indeterminate aria-label="正在加载" />
            <br />
            <Progress indeterminate size="large" aria-label="正在加载" />
            <div style={{ display: 'flex', 'align-items': 'center', gap: '16px', 'margin-top': '20px' }}>
                <Progress indeterminate type="circle" aria-label="正在加载" />
                <Progress indeterminate type="circle" size="small" aria-label="正在加载" />
            </div>
        </div>
    );
}

展示百分比文本

通过showInfo控制是否展示百分比数字，可以通过format属性传入函数格式化展示文本，函数返回的 JSX 替换默认文字

10%

25%

50%

500‰

代码

import { Progress } from '@fibrous/semi-ui-solid';

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

垂直的进度条

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <div style={{ height: '100px', display: 'flex' }}>
            <Progress percent={10} direction="vertical" aria-label="disk usage" />
            <Progress percent={25} direction="vertical" aria-label="disk usage" />
            <Progress percent={50} direction="vertical" aria-label="disk usage" />
            <Progress percent={80} direction="vertical" size="large" aria-label="disk usage" />
            <Progress percent={80} direction="vertical" style={{ width: '8px' }} aria-label="disk usage" />
        </div>
    );
}

环形进度条

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <div>
            <Progress percent={10} type="circle" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={25} type="circle" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={50} type="circle" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={80} type="circle" style={{ margin: '5px' }} aria-label="disk usage" />
        </div>
    );
}

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

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

小号的环形进度条

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <>
            <Progress percent={10} type="circle" size="small" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={25} type="circle" size="small" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={50} type="circle" size="small" style={{ margin: '5px' }} aria-label="disk usage" />
            <Progress percent={80} type="circle" size="small" style={{ margin: '5px' }} aria-label="disk usage" />
        </>
    );
}

动态改变进度

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

40%

代码

import { createSignal } from 'solid-js';
import { IconChevronLeft, IconChevronRight } from '@fibrous/semi-icons-solid';
import { Progress, Button } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    const [percent, setPercent] = createSignal(40);
    return (
        <div>
            <Progress percent={percent()} showInfo aria-label="disk usage" />
            <Button aria-label="减少" icon={<IconChevronLeft />} theme="light" onClick={() => setPercent(percent() - 10)} disabled={percent() === 0} />
            <Button aria-label="增加" icon={<IconChevronRight />} theme="light" onClick={() => setPercent(percent() + 10)} disabled={percent() >= 100} />
        </div>
    );
}

代码

import { createSignal } from 'solid-js';
import { IconChevronLeft, IconChevronRight } from '@fibrous/semi-icons-solid';
import { Progress, Button } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    const [cirPerc, setCirPerc] = createSignal(40);
    return (
        <div>
            <div>
                <Progress percent={cirPerc()} type="circle" aria-label="disk usage" />
            </div>
            <Button aria-label="减少" icon={<IconChevronLeft />} theme="light" onClick={() => setCirPerc(cirPerc() - 10)} disabled={cirPerc() === 0} />
            <Button aria-label="增加" icon={<IconChevronRight />} theme="light" onClick={() => setCirPerc(cirPerc() + 10)} disabled={cirPerc() >= 100} />
        </div>
    );
}

自定义中心文字内容

你可以通过传入 format 函数自定义中心文字，format 的入参为当前百分比，返回值可以是任意 JSX
如果不需要中心文本内容，你可以将 showInfo 设为 false，或者在 format 中直接返回空字符串

75Days

Done

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <>
            <Progress percent={75} showInfo type="circle" format={(per) => per + 'Days'} style={{ margin: '10px' }} aria-label="disk usage" />
            <Progress percent={100} showInfo type="circle" format={() => 'Done'} style={{ margin: '10px' }} aria-label="disk usage" />
            <Progress percent={50} type="circle" showInfo={false} style={{ margin: '10px' }} aria-label="disk usage" />
        </>
    );
}

圆角/方角边缘

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

代码

import { Progress } from '@fibrous/semi-ui-solid';

export default function ProgressDemo() {
    return (
        <>
            <Progress percent={50} strokeLinecap="round" type="circle" style={{ margin: '10px' }} aria-label="disk usage" />
            <Progress percent={50} strokeLinecap="square" type="circle" style={{ margin: '10px' }} aria-label="disk usage" />
        </>
    );
}

自定义进度条颜色

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

10%

代码

import { createSignal } from 'solid-js';
import { IconChevronLeft, IconChevronRight } from '@fibrous/semi-icons-solid';
import { Progress, Button } from '@fibrous/semi-ui-solid';

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)' },
];

export default function ProgressDemo() {
    const [percent, setPercent] = createSignal(10);
    return (
        <>
            <div>
                <Progress percent={percent()} stroke={strokeArr} showInfo type="circle" width={100} aria-label="disk usage" />
                <Progress percent={percent()} stroke={strokeArr} showInfo style={{ margin: '20px 0 10px' }} aria-label="disk usage" />
            </div>
            <Button aria-label="Decrease" icon={<IconChevronLeft />} theme="light" onClick={() => setPercent(percent() - 10)} disabled={percent() === 0} />
            <Button aria-label="Increase" icon={<IconChevronRight />} theme="light" onClick={() => setPercent(percent() + 10)} disabled={percent() === 100} />
        </>
    );
}

自动补齐颜色区间

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

65%

代码

import { createEffect, createSignal, on, onCleanup } from 'solid-js';
import { IconChevronLeft, IconChevronRight } from '@fibrous/semi-icons-solid';
import { Space, Progress, Button } from '@fibrous/semi-ui-solid';

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)' },
];

export default function ProgressDemo() {
    const [percent, setPercent] = createSignal(65);
    const [percentInterval, setPercentInterval] = createSignal(0);

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

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

API 参考

Props

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

class、style 与原生属性（id、aria-label、aria-labelledby、aria-valuetext 等）经 props 展开到根元素（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-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)	进度条圆角大小