Progress 进度条

一条横向轨道，按 value / max 的比例填充，表示一项任务完成了多少。

基础用法

value 取 0 到 max（默认 100），超出范围时夹紧。没有可见文字说明时写 aria-label。

<pt-progress value="0" aria-label="未开始"></pt-progress>
<pt-progress value="33" aria-label="上传进度"></pt-progress>
<pt-progress value="100" aria-label="已完成"></pt-progress>

自定义最大值

按步骤计数时把 max 设成总步数，宽度与 aria-valuenow / aria-valuemax 按比例换算。

<pt-progress value="3" max="5" aria-label="第 3 步，共 5 步"></pt-progress>

取值

• value：0 到 max。缺省、null、NaN 都按 0 处理（不是「不确定进度」）；超出范围时夹紧到 0 或 max。
• max：默认 100。缺省、非数或 <= 0 时按 100 处理。

aria-valuenow / aria-valuemax 用的是兜底、夹紧之后的值，读屏念的和画出来的一致。

尺寸

宿主默认占满容器宽度、8px 高。改粗细用 --pt-progress-height（可设在容器上统一生效）， 也可以直接给元素写 height —— 轨道撑满宿主：

<pt-progress value="60" style="--pt-progress-height: 4px"></pt-progress>
<pt-progress value="60" style="height: 12px"></pt-progress>

RTL 下指示条从右往左长，不需要额外设置。系统开启「减少动态效果」时，值变化不带过渡。

无障碍

宿主是 role="progressbar"，aria-valuemin="0"。页面上没有可见文字说明它是什么进度时， 写 aria-label（React / Vue / Angular 包装层里属性名是 ariaLabelText）：

<pt-progress value="33" aria-label="上传进度"></pt-progress>

定制

通过 ::part() 调整：base（轨道）、indicator（指示条）。

API

属性

属性	Attribute	类型	默认值	说明
ariaLabelText	aria-label	string | undefined	—	无障碍名称：原生 HTML 里写 aria-label，React / Vue / Angular 包装层里属性名是 ariaLabelText。 不直接叫 ariaLabel：它是 Element 的原生属性，同名 prop 会互相覆盖。
max	max	number	100	最大值。缺省、非数或 <= 0 时按 100 处理
value	value	number | undefined	—	当前进度，0 到 max。缺省 / null / NaN 视为 0，超出范围时夹紧

可定制的内部元素（::part()）

part	说明
base	轨道
indicator	指示条