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

代码演示

如何引入

标准的进度条

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

展示百分比文本

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

垂直的进度条

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

环形进度条

将 type 设为circle,进度条将会展示成环状。进度条默认尺寸为 72 x 72
你可以通过修改width来控制环形进度条的大小

小号的环形进度条

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

动态改变进度

自定义中心文字内容

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

圆角/方角边缘

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

自定义进度条颜色

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

自动补齐颜色区间

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

API 参考

属性说明类型默认值
aria-labelaria-label属性,用来给当前元素加上的标签描述, 用于提升可访问性
v2.2.0 后提供
string
aria-labelledbyaria-labelledby属性,表明某些元素的 id 是当前元素的标签。它被用来确定控件或控件组与它们标签之间的联系, 提升可访问性
v2.2.0 后提供
string
aria-valuetextaria-valuetext属性,用于提升可访问性
v2.2.0 后提供
string
className样式类名string
direction条状进度条方向 horizontalverticalstring'horizontal'
format格式化函数,入参为当前百分比,return 的结果将会直接渲染在圆形进度条中心(percent: number) => ReactNode(percent) => percent + '%'
idid 标识
v2.2.0 后提供
string
orbitStroke进度条轨道填充色
v1.0.0 后提供
string'var(--semi-color-fill-0)'
percent进度百分比number
showInfo环形进度条是否显示中间文本,条状进度条后右侧是否显示文本booleanfalse
size尺寸,可选defaultsmall(仅 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 设置至少一个颜色区间booleanfalse
strokeLinecap圆角round/方角square(仅在 type='circle'模式下生效)string'round'
strokeWidthtype 为circle时,该属性控制进度条宽度number4
style样式CSSProperties
type类型,可选linecirclestring'line'
width环形进度条宽度numbersize='default'时为 72,'small'为 24

Accessibility

ARIA

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

文案规范

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

设计变量