Progress 进度条

显示任务完成进度的指示器——条形、分段条、圆环或仪表盘。

基础用法

@Local progress: number = 13;

aboutToAppear() {
  setTimeout(() => this.progress = 66, 500);
}

SProgress({ value: this.progress })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

尺寸

sizing：'sm' | 'default' | 'lg'，或任意粗细；showValue 显示百分比。

SProgress({ value: 40, sizing: 'sm' })
SProgress({ value: 55 })
SProgress({ value: 70, sizing: 'lg', showValue: true })
SProgress({ value: 30, thickness: 2 })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

色调

default | success | warning | info | destructive；valueText 替换百分比文字。

SProgress({ value: 80, tone: 'success', showValue: true })
SProgress({ value: 55, tone: 'warning', showValue: true })
SProgress({ value: 35, tone: 'info', showValue: true })
SProgress({ value: 92, tone: 'destructive', valueText: '92 GB' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

缓冲、条纹、分段与不确定

不确定进度条在独立节点上持续滑动；切换它即可看到停止。

SProgress({ value: 35, buffer: 70, sizing: 'sm' })      // buffered media
SProgress({ value: 60, sizing: 'lg', striped: true })
SProgress({ value: 45, sizing: 'lg', striped: true, animated: true, tone: 'info' })
SProgress({ value: 3, max: 5, segments: 5, valueText: 'Step 3 of 5' })
SProgress({ indeterminate: true, label: 'Loading' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

圆环

shape: 'circle'——尺寸、粗细、数值 / 说明 / 自定义中心内容、不确定旋转。

SProgress({ shape: 'circle', value: 72, sizing: 'sm' })
SProgress({ shape: 'circle', value: 72, showValue: true })
SProgress({ shape: 'circle', value: 72, sizing: 'lg', showValue: true, caption: 'Storage', tone: 'success' })
SProgress({ shape: 'circle', value: 4, max: 10, diameter: 80, thickness: 10 }) {
  Text('4/10')
}
SProgress({ shape: 'circle', indeterminate: true, sizing: 'sm' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

仪表盘

shape: 'gauge'——240° 的仪表，适合水平与配额。

SProgress({ shape: 'gauge', value: 48, showValue: true, caption: 'CPU', sizing: 'lg' })
SProgress({ shape: 'gauge', value: 82, valueText: '82°', caption: 'Temp', sizing: 'lg', tone: 'destructive' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SProgress

shadcn-vue 的 Progress，并扩展了设计系统通常需要的各种形式。

• linear（默认）：h-2 w-full rounded-full bg-primary/20 轨道，bg-primary 指示条的宽度会以动画过渡到 value / max。其他选项：sizing / thickness、buffer（颜色更浅的第二段进度条，例如视频缓冲）、striped（配合 animated）、segments（分为 N 段的分段进度条）以及 indeterminate（滑动的进度条）。
• circle：圆环（diameter、thickness），中央显示数值（showValue / valueText）、caption 或任意插槽内容；indeterminate 会旋转四分之一圆弧。
• gauge：240° 的仪表盘，中央内容相同。

tone 决定指示条的颜色：default（主色）| success | warning | info | destructive。

无限循环动效（indeterminate、移动的条纹）位于其独立的子节点中，该节点被移除时动效停止；关闭动效（--motion-progress-enabled: false）时则显示静态状态。

属性	类型	默认值	说明
value	number	0	0…max
max	number	100
label	string | undefined	undefined	无障碍名称。
shape	ProgressShape ProgressShape = 'linear' | 'circle' | 'gauge'	'linear'
sizing	ProgressSize ProgressSize = 'sm' | 'default' | 'lg'	'default'
thickness	number | undefined	undefined	进度条高度 / 圆环描边宽度，单位 vp；覆盖 sizing 预设
diameter	number | undefined	undefined	圆环 / 仪表盘直径，单位 vp；覆盖 sizing 预设
tone	SparkTone SparkTone = 'default' | 'success' | 'warning' | 'info' | 'destructive'	'default'
indeterminate	boolean	false	持续时间未知：滑动条（linear）或旋转圆弧（circle）
buffer	number | undefined	undefined	linear：次要（缓冲）数值，0…max，绘制在指示条后方，颜色更浅。
striped	boolean	false	linear：指示条上的斜向条纹。
animated	boolean	false	linear + striped：条纹会移动。
segments	number	0	linear：将轨道等分为 N 段（步进）。0 表示连续。
showValue	boolean	false	显示数值：位于进度条右侧，或位于圆环 / 仪表盘的中央。
valueText	ResourceStr | undefined	undefined	自定义数值文字（默认 "66%"）。隐含 showValue。
caption	ResourceStr | undefined	undefined	圆环 / 仪表盘：数值下方的小号弱化文字。
tokens	ProgressTokens	{}	实例级令牌覆盖，参见 {@link ProgressTokens}。

插槽: 子组件（尾随闭包）