TechUI Docs

简中

EN

简中

EN

主题

进度池 ​

⭐明星组件
👑首创

TuiProgressPool 是一个具有高度装饰性的进度展示组件。 它模拟了“蓄水池”或“电池充能”的视觉效果，支持波浪动画 (Wave)、虚线外框 (Dash Border) 以及多种颜色渐变策略。配合 TuiProgressPoolGroup 可轻松实现队列动画效果。

基础用法 ​

基础展示 ​

最简单的用法，配置 value 和 label。 默认情况下，组件会自动计算百分比，并使用科技感的虚线边框包裹。

html
<template>
  <div style="width: 300px; height: 100px;">
    <TuiProgressPool 
      :value="60" 
      label="基础进度池" 
    />
  </div>
</template>

视觉特效 ​

波浪填充 (Wave) ​

设置 fillContent="wave" 可开启液位波浪动画。 您可以精细控制波浪的高度、段数和动画时长，模拟液面晃动的效果。

  • waveHeight: 波浪起伏高度。
  • waveSegments: 波浪的波峰数量。
html
<template>
  <TuiProgressPool 
    :value="45" 
    label="液位监测" 
    fillContent="wave"
    :waveHeight="10"
    :waveSegments="4"
    :colors="['#409eff', '#36cfc9']" 
  />
</template>

形状与方向 ​

  • shape: 支持 square (默认矩形) 和 circle (圆形)。
  • barDirection: 控制内部进度条的增长方向 (h 水平, v 垂直)。
html
<template>
  <TuiProgressPool 
    :value="75" 
    shape="circle" 
    barDirection="v"
    fillContent="wave"
    label="储罐容量" 
    unit="L"
    :width="150"
  />
</template>

数值与阈值 ​

数值展示逻辑 ​

组件提供了强大的数值显示配置：

  • maxValue: 设置最大值，用于计算百分比（默认 100）。

  • displayValue: 控制显示内容。

  • auto: 自动显示。

  • all: 同时显示百分比和实际数值。

  • allReverse: 反转百分比和实际数值的主次显示位置。

  • unit: 数值单位。

智能阈值 (Thresholds) ​

通过 thresholds 对象，可以根据数值自动切换颜色状态。支持定义 critical, danger, warning, normal, success 五种状态的断点。

html
<script setup>
const myThresholds = {
  danger: 20,   // 0-20
  warning: 50,  // 21-50
  normal: 80,   // 51-80
  success: 100  // 81+
};
</script>

<template>
  <TuiProgressPool 
    :value="85" 
    :thresholds="myThresholds"
    label="健康度" 
  />
</template>

进度池组 ​

使用 TuiProgressPoolGroup 可以渲染一组进度池，并支持 队列动画（一个接一个地播放入场动画）。

  • queueInit: 是否开启队列初始化动画（默认为 true）。
  • progressPoolConfig: 统一配置内部所有 item 的样式属性。
html
<script setup>
const items = [
  { label: "节点 A", value: 32 },
  { label: "节点 B", value: 65 },
  { label: "节点 C", value: 89 }
];

const poolConfig = {
  fillContent: 'wave',
  barDirection: 'v', // 垂直柱状图效果
  gradientAni: true  // 开启渐变流光动画
};
</script>

<template>
  <div style="height: 300px">
    <TuiProgressPoolGroup 
      :items="items" 
      :progressPoolConfig="poolConfig"
      :gap="20"
    />
  </div>
</template>

API 参考 ​

TuiProgressPool Props ​

属性名类型默认值说明
valueNumber0当前数值。
maxValueNumbernull最大值。若不填则默认按 100 计算百分比。
labelStringRequired标题/标签文本。
unitString''数值单位。
shapeString'square'形状。可选：square, circle。
fillContentString'bar'填充内容类型。可选：bar (普通), wave (波浪)。
colorsString/Arraynull颜色配置。支持单色字符串或 [startColor, endColor] 渐变数组。
barDirectionString'h'进度增长方向。可选：h, v。
labelPostionString'top'标签位置。可选：top, left, right, bottom。
displayValueString'auto'数值显示模式。可选：none, auto, all, allReverse。
statusString-强制指定状态颜色 (success, warning 等)。
thresholdsObject-阈值配置对象。
barDashArray[5, 2]内部进度条的虚线配置 [实线长, 间隙长]。
borderWidthNumber3外框边框宽度。
borderGapNumber3外框与内部进度的间距。
borderRadiusNumber5圆角大小。
gradientTypeString'linear'渐变类型。可选：linear, radial。
gradientAniBooleanfalse是否开启渐变流光动画。
waveHeightNumber20波浪高度 (px)。
waveSegmentsNumber6波浪段数。
aniDelayNumber2000初始动画延迟时间 (ms)。
durationNumber-动画持续时长 (ms)。
resizeObserverString'global'尺寸监听策略。

TuiProgressPoolGroup Props ​

属性名类型默认值说明
itemsArray[]数据源数组，项包含 { label, value }。
progressPoolConfigObject-统一透传给内部 TuiProgressPool 的 Props 配置对象。
gapNumber-组内元素间距。
directionString'h'组排列方向。可选：h, v。
queueInitBooleantrue是否开启队列延迟初始化（依次播放入场动画）。
labelWidthNumber-统一标签宽度（用于对齐）。

Emits ​

事件名说明回调参数
inited组件初始化动画完成时触发。-