• 前端
• UI组件
• 小程序
• 设计系统
• 移动开发

【免费下载链接】tdesign-miniprogram

Wechat MiniProgram and Uniapp UI components lib for TDesign

项目地址： https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram

点击查看 免费下载

TDesign Uniapp 组件库（位于 packages/uniapp-components）中的 Progress 进度条组件，用于直观展示任务当前的完成进度，是加载上传、批量任务、表单校验等场景的基础反馈组件。本文以 Progress 官方文档 为主线，结合组件源码（progress.vue、computed.js、progress.less）与官方示例，系统讲解它的引入方式、line / plump / circle 三种形态、success / error / warning / active 四种状态，以及 Props、Slots、External Classes、CSS Variables 四层 API，帮助你快速上手并实现深度的样式与行为定制。

一、组件引入：easycom 与手动 import 两种方式

Progress 组件支持两种引入方式，推荐使用 easycom 模式：按 easycom 规则自动扫描组件目录后，无需手动 import 即可在模板中直接书写 <t-progress />。具体配置方法参考 快速开始文档（即项目根级快速开始说明）。

如需手动引入，可在组件的 <script> 中显式导入并注册：

import TProgress from '@tdesign/uniapp/progress/progress.vue';

export default {
  components: {
    TProgress,
  },
};

官方示例目录 _example/ 中的 base/index.vue、line/index.vue 等均采用这种手动注册方式，引入路径统一为 @tdesign/uniapp/progress/progress.vue。

二、组件类型：line、plump 与 circle 三套形态

Progress 通过 theme 属性切换三种视觉形态，三者的差别在于进度标签（label）的呈现位置：

| theme 取值 | 形态 | label 显示位置 | | -- | -- | -- | | line（默认） | 线性进度条 | 进度条右侧 | | plump | 条形（百分比内显）进度条 | 进度条内部 | | circle | 环形进度条 | 环形正中间 |

从源码看，progress.vue 的模板正是按 theme 三路分支渲染，且 props.ts 对 theme 做了取值校验（仅允许 line / plump / circle，非法值不生效）：

theme: {
  type: String,
  default: 'line' as TdProgressProps['theme'],
  validator(val) {
    if (!val) return true;
    return ['line', 'plump', 'circle'].includes(val);
  },
},

2.1 线性进度条（line）

最常用的形态，基础用法只需传入百分比：

<t-progress :percentage="80" />

2.2 百分比内显进度条（plump）

标签文字直接嵌入进度色块内部，视觉更紧凑：

<t-progress theme="plump" :percentage="80" />

实现上，plump 形态在进度值大于 10% 与小于等于 10% 时有不同的内部排版：progress.vue 会根据 computedProgress > 10 切换 --over-ten / --under-ten 样式类。不足 10% 时，为避免文字挤在很短的色块里，进度文字会放到色块外部显示；超过 10% 时文字才渲染在色块内部。

2.3 环形进度条（circle）

<t-progress theme="circle" :percentage="30" />

环形形态使用 CSS conic-gradient 实现圆环描边（见 progress.vue），并通过 size 控制整体尺寸：default（直径 112px，即样式中的 224rpx）与 micro（直径 24px，即 48rpx）两种预设。若不传入 size，环形进度条中间默认显示百分比文字；微型场景通常配合 :label="false" 隐藏文字：

<t-progress theme="circle" size="micro" :percentage="30" :label="false" />

尺寸的解析逻辑位于 computed.js 的 getCircleStyle：当 size 既不是 default 也不是 micro 时，会直接把传入值（自动补充单位）写进 --td-progress-circle-width CSS 变量，因此 size 也支持传入任意数值或字符串实现自定义直径。

三、组件状态：success / error / warning / active

Progress 支持四种状态，通过 status 属性显式指定，或由源码自动推断：

<t-progress :percentage="80" />
<t-progress :percentage="88" status="warning" />
<t-progress :percentage="88" status="error" />
<t-progress :percentage="88" status="success" />
<t-progress :percentage="88" status="active" />

• success / error / warning：三种完成态，会改变进度条填充色，并在线性 / 环形形态下分别显示对应的状态图标（见 computed.js：线性使用 check-circle-filled、error-circle-filled，环形使用 check、close、error）；
• active：加载中的流动动画状态，样式层由 progress.less 中的 progress-active-animation 关键帧实现——一个持续 2s、cubic-bezier(0.23, 0.99, 0.86, 0.2) 缓动、无限循环的扫光效果，常用于上传 / 下载等持续进度场景。

两个值得注意的源码行为：

1. 状态自动推断：progress.vue 中 percentage 的 watch 处理器会把数值强制收敛到 [0, 100] 区间（Math.max(0, Math.min(percentage, 100))），并且当 percentage === 100 时自动将 computedStatus 置为 success。也就是说，不传 status 时，进度走到 100% 会自动呈现为成功态；
2. 状态优先于推断：模板中同时使用了 status || computedStatus，显式传入的 status 优先级更高，可覆盖自动推断结果。

四、Props 全参数详解

下表继承自 Progress 官方 API 文档，并结合 props.ts 补充了默认值与校验规则：

| 名称 | 类型 | 默认值 | 说明 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义根节点样式 | N | | color | String / Object / Array | '' | 进度条颜色（详见下文四种写法） | N | | label | String / Boolean | true | 进度百分比文字，可自定义内容或关闭 | N | | percentage | Number | 0 | 进度条百分比，源码会自动收敛到 0～100 | N | | size | String / Number | 'default' | 环形进度条尺寸，可选 default / micro，也支持自定义值 | N | | status | String | - | 状态，可选 success / error / warning / active，TS 类型 ProgressStatus | N | | stroke-width | String / Number | - | 进度条线宽，默认单位 px | N | | theme | String | line | 进度条风格，可选 line / plump / circle，TS 类型 ProgressTheme | N | | track-color | String | '' | 进度条未完成部分的颜色（轨道色） | N |

4.1 color 的四种写法与底层渐变处理

color 属性是 Progress 中最灵活的配置项，支持字符串、数组、对象三种形态。TS 类型定义为 string | Array<string> | Record<string, string>。官方文档给出的示例：

'#ED7B2F'   // 单个颜色
'orange'    // 颜色名
['#f00', '#0ff', '#f0f']   // 多色数组，形成线性渐变
{ '0%': '#f00', '100%': '#0ff' }  // 按百分比映射颜色
{ from: '#000', to: '#000' }      // 起止色

其底层实现位于 utils.js 的 getBackgroundColor，处理规则如下：

• 字符串：直接作为背景色返回；
• 数组：若首元素以 # 开头，自动在数组头部插入 90deg 作为渐变方向，再拼接为 linear-gradient(...)；
• 对象：解构出 from、to 与 direction（默认 'to right'）；若对象中还包含其它键，则按百分比数值排序后生成 linear-gradient(direction, colorA 0%, colorB 100%) 形式的多段渐变。

需要特别说明：环形进度条不支持渐变。progress.vue 中对 color 的 watch 处理是 this.colorCircle = typeof color === 'object' ? '' : color，即环形场景下对象形式的渐变色会被忽略、回退到主题色，只有字符串颜色对环形生效。

4.2 stroke-width 与默认线宽

stroke-width 用于控制进度条粗细（默认单位 px）。源码中通过 common/utils.js 的 unitConvert 把数字自动补上 px 单位后写入内联样式高度。不传时各形态使用样式表预设的默认线宽，见下表（来源 progress.less）：

| 形态 | 默认线宽 | | -- | -- | | line | 12rpx（--td-progress-line-stroke-width） | | plump | 40rpx（--td-progress-stroke-plump-width） | | circle | 12rpx（--td-progress-stroke-circle-width） |

五、Slots 与 External Classes

5.1 Slots

| 名称 | 说明 | | -- | -- | | label | 自定义进度百分比内容 |

当内置的文字无法满足需求时，可用插槽完全接管百分比区域的渲染：

<t-progress :percentage="80">
  <template #label>
    <text>已完成 80/100</text>
  </template>
</t-progress>

5.2 External Classes（外部样式类）

| 类名 | 说明 | | -- | -- | | t-class | 根节点样式类 | | t-class-bar | 进度条主体（进度色块）样式类 | | t-class-label | 标签样式类 |

外部样式类在 progress.vue 中通过 externalClasses 声明（对应 t-class、t-class-bar、t-class-label）。官方示例 custom/index.vue 展示了组合用法——配合 track-color、color 与外部类实现完全自定义外观：

<t-progress :percentage="88" track-color="#EAC9FF" color="#CD04FF" t-class-label="external-class-label" />
<t-progress :percentage="88" t-class-bar="external-class-bar" />

.external-class-label {
  color: #d504d9;
}

:deep(.external-class-bar) {
  border-radius: 10px !important;
}

六、CSS Variables：主题级样式定制

组件将核心样式参数全部抽象为 CSS 变量（见 progress.less），你可以在页面或全局样式中覆写，而无需改动组件源码。完整变量清单如下（默认值列中 @brand-color、@success-color 等为 TDesign 设计令牌，实际对应主题色值）：

| CSS 变量 | 默认值 | 说明 | | -- | -- | -- | | --td-progress-info-dark-color | @text-color-primary | 深色 label 文字颜色（进度条外 / 未完成灰块内显示） | | --td-progress-info-light-color | @text-color-anti | 浅色 label 文字颜色（进度条色块内显示） | | --td-progress-inner-bg-color-active | @bg-color-container | active 流动光效颜色 | | --td-progress-inner-bg-color-error | @error-color | error 状态进度色 | | --td-progress-inner-bg-color-success | @success-color | success 状态进度色 | | --td-progress-inner-bg-color-warning | @warning-color | warning 状态进度色 | | --td-progress-circle-icon-size | 96rpx | 环形状态图标尺寸 | | --td-progress-circle-inner-bg-color | @bg-color-container | 环形内圆背景色 | | --td-progress-circle-label-font | @font-title-extraLarge | 环形中央 label 字体 | | --td-progress-circle-width | 224rpx | 环形直径 | | --td-progress-inner-bg-color | @brand-color | 默认（无状态）进度色 | | --td-progress-line-stroke-width | 12rpx | line 形态线宽 | | --td-progress-stroke-circle-width | 12rpx | circle 形态描边宽度 | | --td-progress-stroke-plump-width | 40rpx | plump 形态线宽 | | --td-progress-track-bg-color | @bg-color-component | 轨道（未完成部分）背景色 |

实际应用中，color 属性与 --td-progress-inner-bg-color 是两种互补的配色手段：前者通过组件属性按实例覆盖，后者可在全局主题层批量统一。例如将主题进度色改成品牌绿：

page {
  --td-progress-inner-bg-color: #00a870;
  --td-progress-track-bg-color: #e3e6eb;
}

七、源码级补充：无障碍与动态进度

Progress 在可访问性上做了细致处理，值得在集成时参考：

• ARIA 语义：三种形态均声明了 aria-role="progressbar"、aria-valuemin="0"、aria-valuemax="100"、aria-valuenow 与 aria-live="polite"，屏幕阅读器可实时感知进度变化（见 progress.vue）；
• iOS / Android 读屏差异：computed.js 中 getIOSAriaLabel 与 getAndroidAriaLabel 针对两端做了文案差异处理——iOS 能识别 % 符号，而 Android 不识别，因此在安卓端单独拼接了 %，并对 error / warning 状态补充了「进度失败」「进度异常」的语音提示；
• 自定义读屏文案：示例 transition/index.vue 展示了动态更新进度的典型写法——通过按钮将 percentage 在 0～100 间增减，并配合 :aria-label="percentage + '%'" 覆盖默认读屏文案。

小结

TDesign Uniapp 的 Progress 组件用一套 Props 覆盖了线性、内显、环形三种主流进度展示形态与四种状态，并通过 color 的三种数据类型支持单色与多种渐变写法（环形除外）。日常使用建议遵循：基础进度用 <t-progress :percentage="x" />，需要状态反馈时追加 status，精细定制时优先使用 External Classes 与 CSS Variables，而不要直接修改组件源码。更多可运行示例可查阅 progress/_example 目录，其英文版 API 说明见 README.en-US.md。

• 前端
• UI组件
• 小程序
• 设计系统
• 移动开发

【免费下载链接】tdesign-miniprogram

Wechat MiniProgram and Uniapp UI components lib for TDesign

项目地址： https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram

点击查看 免费下载