反馈 · 12 / 21
Progress st-progress
线形与环形两种形态，确定值与不定进度两种模式。value 是普通属性，配合 attr:value 即可随数据实时变化；缺省 value 会自动进入不定状态。
确定进度：线形与环形
value 取值 0–100，超出范围会被夹到边界。线形默认占满可用宽度，环形固定 40px 直径；两者都能放在网格或卡片里单独使用。
LIVE
value + circular
线形 · 36%
环形 · 36%
线形 · 100%
环形 · 100%
示例代码
<st-progress value="36"></st-progress>
<!-- 环形：40px 直径，stroke 随 font-size 缩放 -->
<st-progress circular value="36"></st-progress>运行时更新 value
value 是标签属性，页面里用 attr:value 绑定 data 数字。值变化时确定态有 0.3s 平滑过渡，线形和环形会同步变化。
LIVE
attr:value示例代码（attr:value 绑定）
<st-progress attr:value="progress"></st-progress>
<st-progress circular attr:value="progress"></st-progress>
<st-button on:click="step(10)">+10</st-button>
<script>
export default async () => ({
data: { progress: 36 },
proto: {
step(delta) {
this.progress = Math.max(0, Math.min(100, this.progress + delta));
},
},
});
</script>不定进度
设置 indeterminate 后忽略 value，线形显示循环滑块，环形显示旋转弧线。不写 value 也会自动视为不定，适合还不知道总进度的场景。
LIVE
indeterminate示例代码
<st-progress indeterminate></st-progress>
<st-progress></st-progress> <!-- 没有 value 同样视为不定 -->
<st-progress circular indeterminate color="success"></st-progress>
<!-- 系统开启“减少动态效果”时，动画时长会自动趋零 -->尺寸与高度
线形轨道高 0.286em，环形直径 2.857em；改 font-size 就能整体等比缩放，线形宽度仍由 width 或父容器决定。
LIVE
font-size / width
线形 · 10 像素
线形 · 20 像素
窄容器 160 像素
环形 · 10 像素
环形 · 14 像素
环形 · 24 像素
示例代码
<st-progress value="55" style="font-size: 20px; width: 100%;"></st-progress>
<st-progress circular value="55" style="font-size: 24px;"></st-progress>
<!-- 线形宽度用原生 width 控制 -->
<st-progress value="55" style="width: 160px;"></st-progress>color 语义换色
color 接受 M3 角色名（primary / secondary / tertiary / error / success）或 color 工具里的自定义变量名。默认使用 primary，切换种子色时整站进度条一起变化。
LIVE
color
primary（默认）
success
error
tertiary
环形 · error
环形 · success
示例代码
<st-progress value="70" color="success"></st-progress>
<st-progress value="70" color="error"></st-progress>
<st-progress circular value="70" color="tertiary"></st-progress>场景：同步队列
多个进度条共享一组 data，每个任务用 attr:value 绑定自己的数值，颜色表达任务状态。按钮推进后可以观察平滑过渡。
LIVE
任务列表
照片同步
{{photo}}%
云盘备份
{{backup}}%
病毒扫描
{{scan}}%
示例代码（多任务）
<st-progress attr:value="photo"></st-progress>
<st-progress attr:value="backup" color="success"></st-progress>
<script>
export default async () => ({
data: { photo: 45, backup: 80 },
proto: {
advance() {
this.photo = Math.min(this.photo + 12, 100);
this.backup = Math.min(this.backup + 8, 100);
},
},
});
</script>属性
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
value | number（0–100） | 无 | 确定进度；缺省或非数字视为不定 |
indeterminate | boolean | 无 | 不定动画；设置后忽略 value |
circular | boolean | 无 | 环形，默认线形 |
color | M3 角色名 / 自定义变量名 | primary | 进度色 |
插槽 / 事件 / 注意
- 无插槽、无事件，纯展示组件。
- 线形宽度由
width或父容器控制；线形高度 =0.286em。 - 环形直径
2.857em、stroke0.286em，随 font-size 缩放。 - 确定态数值变化有 0.3s 平滑过渡；不定态循环播放。
prefers-reduced-motion下动画时长会趋零。