进度条

TuiProgress 用于展示操作的当前进度、统计数据的百分比或仪表盘指标。 支持 线性 (Bar)、环形 (Circle) 和 仪表盘 (Guage) 三种展示形态，并内置了丰富的状态色彩和动画效果。

基础用法

线性进度条 (Bar)

默认形态。通过 value 设置进度值（默认 0-100）。

• label: 设置左侧标签文本。
• status: 设置状态颜色 (success, warning, danger 等)。

<template>
  <div class="demo-gap">
    <TuiProgress :value="30" label="基础进度" />
    <TuiProgress :value="50" label="完成" status="success" />
    <TuiProgress :value="70" label="警告" status="warning" />
    <TuiProgress :value="90" label="错误" status="danger" />
  </div>
</template>

形态变体

通过 type 属性切换显示形态。

环形进度条 (Circle)

设置 type="circle"。

• icon: 可在圆环中心显示图标。

<template>
  <TuiProgress type="circle" :value="30" label="Normal" />
  
  <TuiProgress 
    type="circle" 
    :value="75" 
    status="success" 
    icon="tui-icon ti-check" 
  />
</template>

仪表盘 (Guage)

设置 type="guage"。通常用于 Dashboard 展示。

<TuiProgress 
  type="guage" 
  :value="80" 
  :strokeWidth="12" 
  label="CPU使用率" 
/>

数值与阈值

智能阈值 (Thresholds)

通过 thresholds 属性，可以根据进度值自动改变颜色和状态。 对象 Key 为状态名 (success, warning 等)，Value 为触发该状态的数值节点。

<script setup>
// 定义阈值：0-59为danger，60-119为warning，120+为success
const myThresholds = {
  danger: 59,
  warning: 119,
  success: 260
};
</script>

<template>
  <TuiProgress 
    :value="currentValue" 
    :maxValue="300" 
    :thresholds="myThresholds" 
    unit="吨"
  />
</template>

格式化内容 (Format)

通过 format 函数或插槽自定义右侧/中间的文字内容。

<script setup>
const formatText = (props) => {
  if (props.value === 100) return '满';
  return `${props.value}%`;
};
</script>

<template>
  <TuiProgress :value="100" :format="formatText" />

  <TuiProgress :value="60">
    <template #default="{ value }">
      <span style="color: blue">{{ value }} / 100 分</span>
    </template>
  </TuiProgress>
</template>

布局与外观

标签布局

• labelNewline: 标签是否独占一行显示在进度条上方。
• labelWidth: 固定标签宽度，用于多行对齐。

<TuiProgress :value="40" label="长标题自动换行" labelNewline />

内部显示 (Value Inside)

对于线性进度条，设置 valuePosition="inside" 可将百分比数值显示在进度条内部。

<TuiProgress :value="70" :strokeWidth="18" valuePosition="inside" />

动画与特效

• striped: 开启条纹效果。
• stripedFlow: 开启条纹流动动画（常用于加载中）。
• indeterminate: 开启不确定进度的加载动画。

<TuiProgress :value="50" status="warning" striped stripedFlow />
<TuiProgress :value="30" indeterminate />

API 参考

Props

属性名	类型	默认值	说明
value	Number	0	必填。当前进度值。
type	String	'bar'	类型。可选：bar, circle, guage。
status	String	-	状态。可选：normal, success, danger, warning, emphasis, critical。
maxValue	Number	0	最大值（用于计算比例）。默认为 100 (若未设置)。
thresholds	Object	-	阈值配置对象 { status: number }。
color	String	-	自定义进度条颜色（覆盖 status）。
strokeWidth	Number	-	进度条宽度 (px)。
width	Number	-	画布宽度 (用于 Circle/Guage)。
indeterminate	Boolean	false	是否为不确定进度动画。
striped	Boolean	false	是否显示条纹。
stripedFlow	Boolean	false	条纹是否流动。
strokeLinecap	String	'round'	端点形状。可选：butt, round, square。
label	String	-	左侧/上方标签文本。
labelNewline	Boolean	false	标签是否换行显示。
labelWidth	Number	-	标签区域固定宽度。
showValue	Boolean	true	是否显示数值。
valuePosition	String	'default'	数值位置。可选：default, newline, inside。
format	Function	-	内容格式化函数 (props) => string。
unit	String	-	数值单位后缀。
icon	String	-	图标类名。
showStatusIcon	Boolean	true	是否显示状态对应的图标（如对勾、感叹号）。

Slots

插槽名	说明	参数
default	自定义进度数值区域的内容。	{ value }
label	自定义标签区域的内容。	-
icon	自定义图标区域的内容。	-