index.md 11 KB
localeCode: zh-CN order: 67 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>
);
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 | 进度条填充色 | string | 'var(--semi-color-success)' |
| 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 具有
progressbarrole 来表示它是一个进度条组件。 - 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... "/>
文案规范
- 如果进度条过程复杂，或者有很长的等待时间，可以使用帮助文本来做说明。这样可以让用户知道正在发生的进度进展