Apq/semi-design: 快速搭建美观的 React 应用。由抖音前端与 UED 团队维护。 @ 72f726b75ef9bc4640e379041489375d606acd96

localeCode: zh-CN order: 68 category: 反馈类 title: Progress 进度条 icon: doc-progress width: 60%

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

代码演示

如何引入

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

标准的进度条

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

() => (
    <div style={{ width: 200 }}>
        <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>
);

展示百分比文本

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

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

垂直的进度条

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

() => (
    <div style={{ height: 100, 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 React from 'react';
import { Progress } from '@douyinfe/semi-ui';

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

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

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

小号的环形进度条

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

() => (
    <React.Fragment>
        <Progress percent={10} type="circle" size="small" style={{ margin: 5 }} aria-label="disk usage" />
        <Progress percent={25} type="circle" size="small" style={{ margin: 5 }} aria-label="disk usage" />
        <Progress percent={50} type="circle" size="small" style={{ margin: 5 }} aria-label="disk usage" />
        <Progress percent={80} type="circle" size="small" style={{ margin: 5 }} aria-label="disk usage" />
    </React.Fragment>
);

动态改变进度

import React, { useState } from 'react';
import { Progress, Button } from '@douyinfe/semi-ui';
import { IconChevronLeft, IconChevronRight } from '@douyinfe/semi-icons';

() => {
    const [percent, setPercent] = useState(40);
    return (
        <>
            <div>
                <Progress percent={percent} showInfo aria-label="disk usage" />
                <Button
                    icon={<IconChevronLeft />}
                    theme="light"
                    onClick={() => {
                        setPercent(percent - 10);
                    }}
                    disabled={percent === 0}
                />
                <Button
                    icon={<IconChevronRight />}
                    theme="light"
                    onClick={() => {
                        setPercent(percent + 10);
                    }}
                    disabled={percent >= 100}
                />
            </div>
        </>
    );
};

import React, { useState } from 'react';
import { Progress, Button } from '@douyinfe/semi-ui';
import { IconChevronLeft, IconChevronRight } from '@douyinfe/semi-icons';

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

自定义中心文字内容

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

() => (
    <React.Fragment>
        <Progress
            percent={75}
            showInfo
            type="circle"
            format={per => per + 'Days'}
            style={{ margin: 10 }}
            aria-label="disk usage"
        />
        <Progress
            percent={100}
            showInfo
            type="circle"
            format={per => 'Done'}
            style={{ margin: 10 }}
            aria-label="disk usage"
        />
        <Progress percent={50} type="circle" showInfo={false} style={{ margin: 10 }} aria-label="disk usage" />
    </React.Fragment>
);

圆角/方角边缘

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

import React from 'react';
import { Progress } from '@douyinfe/semi-ui';

() => (
    <React.Fragment>
        <Progress percent={50} strokeLinecap="round" type="circle" style={{ margin: 10 }} aria-label="disk usage" />
        <Progress percent={50} strokeLinecap="square" type="circle" style={{ margin: 10 }} aria-label="disk usage" />
    </React.Fragment>
);

自定义进度条颜色

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

import React, { useState } from 'react';
import { Progress, Button } from '@douyinfe/semi-ui';
import { IconChevronLeft, IconChevronRight } from '@douyinfe/semi-icons';

() => {
    const [percent, setPercent] = useState(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)' }
    ];
    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
                icon={<IconChevronLeft />}
                theme="light"
                onClick={() => {
                    setPercent(percent - 10);
                }}
                disabled={percent === 0}
            />
            <Button
                icon={<IconChevronRight />}
                theme="light"
                onClick={() => {
                    setPercent(percent + 10);
                }}
                disabled={percent === 100}
            />
        </>
    );
};

自动补齐颜色区间

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

import React, { useEffect, useState } from 'react';
import { Space, Progress, Button } from '@douyinfe/semi-ui';
import { IconChevronLeft, IconChevronRight } from '@douyinfe/semi-icons';

() => {
    const [percent, setPercent] = useState(65);
    const [percentInterval, setPercentInterval] = useState(0);
    useEffect(() => {
        setTimeout(
            () => {
                setPercentInterval(percentInterval > 100 ? 0 : percentInterval + 3);
            },
            percentInterval === 0 || percentInterval > 100 ? 1200 : 290 - (percentInterval % 50) * 3
        );
    }, [percentInterval]);
    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)' },
    ];
    return (
        <>
            <Space spacing={20}>
                <div>
                    <Progress
                        percent={percentInterval}
                        stroke={strokeArr}
                        strokeGradient={true}
                        showInfo
                        type="circle"
                        width={100}
                        aria-label="file download speed"
                    />
                </div>
                <div>
                    <Progress
                        percent={percentInterval}
                        stroke={strokeArrReverse}
                        strokeGradient={true}
                        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={true}
                    showInfo
                    size="large"
                    aria-label="file download speed"
                />
            </div>
            <Button
                icon={<IconChevronLeft />}
                theme="light"
                onClick={() => {
                    setPercent(percent - 5);
                }}
                disabled={percent === 0}
            />
            <Button
                icon={<IconChevronRight />}
                theme="light"
                onClick={() => {
                    setPercent(percent + 5);
                }}
                disabled={percent === 100}
            />
        </>
    );
};

API 参考

属性	说明	类型	默认值
aria-label	aria-label属性，用来给当前元素加上的标签描述, 用于提升可访问性 v2.2.0 后提供	string
aria-labelledby	aria-labelledby属性，表明某些元素的 id 是当前元素的标签。它被用来确定控件或控件组与它们标签之间的联系, 提升可访问性 v2.2.0 后提供	string
aria-valuetext	aria-valuetext属性，用于提升可访问性 v2.2.0 后提供	string
className	样式类名	string
direction	条状进度条方向 `horizontal`、`vertical`	string	'horizontal'
format	格式化函数，入参为当前百分比，return 的结果将会直接渲染在圆形进度条中心	(percent: number) => ReactNode	(percent) => percent + '%'
id	id 标识 v2.2.0 后提供	string
orbitStroke	进度条轨道填充色 v1.0.0 后提供	string	'var(--semi-color-fill-0)'
percent	进度百分比	number
showInfo	环形进度条是否显示中间文本，条状进度条后右侧是否显示文本	boolean	false
size	尺寸,可选`default`、`small`(仅 type=circle 生效)、`large`(仅 type=line 生效)	string	'default'
stroke	进度条填充色，类型为 `Array<{percent:number; color:string }>` 时，`color` 参数支持颜色类型：`'Hex'` \| `'Hsl'` \| `'Hsla'` \| `'Rgb'` \| `'Rgba'` \| `'Semi Design Tokens'`	string \| Array<{percent:number; color:string }>	'var(--semi-color-success)'
strokeGradient	是否自动生成渐变色补齐区间颜色，需要 `stroke` 设置至少一个颜色区间	boolean	false
strokeLinecap	圆角`round`/方角`square`(仅在 type='circle'模式下生效)	string	'round'
strokeWidth	type 为`line`时，该属性控制进度条高度; type 为`circle`时，该属性控制进度条宽度	number	4
style	样式	CSSProperties
type	类型，可选`line`、`circle`	string	'line'
width	环形进度条宽度	number	size='default'时为 72，'small'为 24

Accessibility

ARIA

Progress 具有 progressbar role 来表示它是一个进度条组件。
Progress 会自动将 aria-valuenow 设置为传递给组件的进度百分比（percent），以确保屏幕阅读器可以获取正确的百分比数值。另外，Progress 支持传入 aria-valuetext，当你传入时，根据 W3C 规范，aria-valuetext 将优先被屏幕阅读器使用消费，而不是 aria-valuenow

Progress 支持传入 aria-label、aria-labelledby

当 Progress 外部存在关于 Progress 作用的描述元素时，你可以通过 aria-labelledby 显式指定某些元素的 id 是 Progress 的标签

否则你应当通过 aria-label 说明 Progress 所代表的具体数值含义

// good case
<p id="progressbar-label">Disk Usage</p>
<Progress aria-labelledby="progressbar-label" percent={80} />

// good case
<Progress aria-label='Percent of disk usage' percent={80} />
<Progress aria-label='Percent of file downloaded' percent={80} />

// usage of aria-valuetext
<Progress aria-label='Percent of disk usage' percent={80} aria-valuetext="Step 2: Copying files... "/>

文案规范

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

index.md 16 KB

History Raw

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

代码演示

如何引入

标准的进度条

展示百分比文本

垂直的进度条

环形进度条

小号的环形进度条

动态改变进度

自定义中心文字内容

圆角/方角边缘

自定义进度条颜色

自动补齐颜色区间

API 参考

Accessibility

ARIA

文案规范

设计变量

index.md 16 KB History Raw

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

代码演示

如何引入

标准的进度条

展示百分比文本

垂直的进度条

环形进度条

小号的环形进度条

动态改变进度

自定义中心文字内容

圆角/方角边缘

自定义进度条颜色

自动补齐颜色区间

API 参考

Accessibility

ARIA

文案规范

设计变量

index.md 16 KB

History Raw