uni-app 多类型进度条组件 cxl-progress 详解

前言

在文件上传、数据加载、任务进度等场景中，「进度条」是最常见的交互元素之一。一个美观、易用的进度条组件能极大提升用户体验。

今天介绍一个功能全面的进度条组件 —— cxl-progress，它支持线型、环形、仪表盘三种类型，四种状态显示，支持渐变色、分段进度、动态控制等特性，完美适配 uni-app 多端（H5、微信小程序、App）。

组件特性

三种类型
：线型（line）、环形（circle）、仪表盘（dashboard），覆盖各种进度展示场景
四种状态
：正常（normal）、成功（success）、异常（exception）、活动（active），直观反映当前进度状态
分段进度
：successPercent 属性支持在一个进度条中展示总进度和已完成进度
渐变色支持
：线型进度条支持 CSS 渐变色（linear-gradient）
自定义样式
：线条粗细、端点形状、颜色、尺寸均可灵活配置
缺口控制
：环形和仪表盘支持缺口角度和位置自定义
跨端适配
：H5 使用原生 SVG 渲染，小程序端使用 SVG 转 base64 方案，保证多端一致效果
easycom 自动注册
：放在 components 目录下即可直接使用，无需手动引入

属性速查表

属性	类型	默认值	说明
`type`	String	`'line'`	进度类型：`line`（线型）、`circle`（环形）、`dashboard`（仪表盘）
`percent`	Number	`0`	进度百分比值，范围 0-100
`success-percent`	Number	`0`	已完成分段百分比（仅支持线型）
`status`	String	`'normal'`	进度状态：`normal`、`success`、`exception`、`active`（active 仅支持线型）
`show-info`	Boolean	`true`	是否显示进度数值或状态图标
`stroke-width`	Number	`6`	进度线条的宽度，建议范围 1-50
`stroke-color`	String	`''`	进度线条颜色，渐变色仅支持线型
`stroke-shape`	String	`'round'`	线条两端形状：`round`（圆角）、`square`（直角）
`width`	Number	`80`	圆形/仪表盘画布宽度（px）
`gap-degree`	Number	`0`	圆形缺口角度，取值 0-360
`gap-position`	String	`'top'`	缺口位置：`top`、`bottom`、`left`、`right`

快速开始

安装使用

将 cxl-progress 组件放入项目的 components/cxl-progress/ 目录下，uni-app 的 easycom 机制会自动注册，无需手动 import。

直接在模板中使用：

<cxl-progress:percent=”50”></cxl-progress>

就这么简单！一行代码即可展示一个 50% 的线型进度条。

实战示例

示例1：线性进度条

线型进度条是最基础也是最常用的类型，适用于大多数进度展示场景。

基本用法：

<!-- 不同百分比 --><cxl-progress:percent=”30” /><cxl-progress:percent=”50” /><cxl-progress:percent=”75” />

隐藏进度信息：

<!-- 不显示右侧百分比文字 --><cxl-progress:percent=”40”:showInfo=”false” />

分段进度：

当需要同时展示「总进度」和「已完成进度」时，使用 successPercent：

<!-- 总进度 60%，其中已完成 30%（绿色部分） --><cxl-progress:percent=”60”:successPercent=”30”:showInfo=”false” /><!-- 总进度 80%，其中已完成 50% --><cxl-progress:percent=”80”:successPercent=”50”:showInfo=”false” />

动态控制进度：

通过数据绑定实现动态进度控制：

<template> <view> <cxl-progress:percent=”dynamicPercent”strokeColor=”#1890ff” /> <buttonsize=”mini” @click=”changePercent(-10)”>-10</button> <buttonsize=”mini” @click=”changePercent(10)”>+10</button> <buttonsize=”mini” @click=”dynamicPercent = 0”>重置</button> </view></template><script>export default { data() { return { dynamicPercent: 40 } }, methods: { changePercent(val) { let newVal = this.dynamicPercent + val if (newVal < 0) newVal = 0 if (newVal > 100) newVal = 100 this.dynamicPercent = newVal } }}</script>

示例2：环形进度条

环形进度条适合用在需要更紧凑展示的场景，比如卡片内、统计面板中。

基本用法：

<!-- 设置 type=”circle” 和宽度 --><cxl-progresstype=”circle”:percent=”25”:width=”80” /><cxl-progresstype=”circle”:percent=”50”:width=”80” /><cxl-progresstype=”circle”:percent=”75”:width=”80” />

自定义尺寸：

通过 width 属性调整圆形大小，配合 strokeWidth 调整线条粗细：

<cxl-progresstype=”circle”:percent=”60”:width=”50”:strokeWidth=”4” /> <!-- 小号 --><cxl-progresstype=”circle”:percent=”60”:width=”80”:strokeWidth=”6” /> <!-- 中号 --><cxl-progresstype=”circle”:percent=”60”:width=”120”:strokeWidth=”8” /> <!-- 大号 -->

自定义颜色：

<cxl-progresstype=”circle”:percent=”70”:width=”80”strokeColor=”#f5222d” /> <!-- 红色 --><cxl-progresstype=”circle”:percent=”70”:width=”80”strokeColor=”#52c41a” /> <!-- 绿色 --><cxl-progresstype=”circle”:percent=”70”:width=”80”strokeColor=”#faad14” /> <!-- 橙色 -->

缺口位置：

<!-- gapPosition 控制缺口方向，gapDegree 控制缺口角度大小 --><cxl-progresstype=”circle”:percent=”65”:width=”80”gapPosition=”top”:gapDegree=”60” /><cxl-progresstype=”circle”:percent=”65”:width=”80”gapPosition=”bottom”:gapDegree=”60” /><cxl-progresstype=”circle”:percent=”65”:width=”80”gapPosition=”right”:gapDegree=”60” />

示例3：仪表盘

仪表盘类型默认底部有缺口，非常适合用在评分、健康度等可视化场景。

基本用法：

<cxl-progresstype=”dashboard”:percent=”30”:width=”100” /><cxl-progresstype=”dashboard”:percent=”60”:width=”100” /><cxl-progresstype=”dashboard”:percent=”90”:width=”100” />

自定义尺寸和颜色：

<!-- 警告色 + 小号 --><cxl-progresstype=”dashboard”:percent=”45”:width=”80”strokeColor=”#faad14”:strokeWidth=”8” /><!-- 正常色 + 中号 --><cxl-progresstype=”dashboard”:percent=”75”:width=”100”strokeColor=”#1890ff”:strokeWidth=”10” /><!-- 优秀色 + 大号 --><cxl-progresstype=”dashboard”:percent=”95”:width=”120”strokeColor=”#52c41a”:strokeWidth=”12” />

动态仪表盘（结合 slider 控制）：

<template> <view> <cxl-progress type=”dashboard” :percent=”dashPercent” :width=”140” :strokeWidth=”10” :strokeColor=”dashColor” /> <slider:value=”dashPercent” @change=”onSliderChange”min=”0”max=”100” /> </view></template><script>export default { data() { return { dashPercent: 60 } }, computed: { // 根据进度值动态改变颜色 dashColor() { if (this.dashPercent < 30) return '#f5222d' // 红色-危险 if (this.dashPercent < 70) return '#faad14' // 黄色-警告 return '#52c41a' // 绿色-安全 } }, methods: { onSliderChange(e) { this.dashPercent = e.detail.value } }}</script>

这个示例展示了仪表盘根据进度值自动变色：低于 30% 显示红色（危险），30%-70% 显示黄色（警告），高于 70% 显示绿色（安全）。

示例4：进度状态

cxl-progress 支持四种状态，每种状态都有独特的颜色和图标，帮助用户快速理解当前进度状况。

线型四种状态：

<!-- 正常 - 蓝色 --><cxl-progress:percent=”50”status=”normal” /><!-- 成功 - 绿色 --><cxl-progress:percent=”70”status=”success” /><!-- 异常 - 红色 --><cxl-progress:percent=”40”status=”exception” /><!-- 活动 - 蓝色 + 流动动画 --><cxl-progress:percent=”60”status=”active” />

normal
：默认蓝色，正常进行中
success
：绿色 + 对勾图标，表示完成
exception
：红色 + 叉号图标，表示失败或异常
active
：蓝色 + 白色流动动画，表示正在活跃执行（仅线型支持）

环形状态：

<cxl-progresstype=”circle”:percent=”70”:width=”80”status=”normal” /><cxl-progresstype=”circle”:percent=”100”:width=”80”status=”success” /><cxl-progresstype=”circle”:percent=”40”:width=”80”status=”exception” />

自动完成状态：

当 percent 达到 100 时，组件会自动切换为成功状态，无需手动设置：

<cxl-progress:percent=”100” /> <!-- 线型自动成功 --><cxl-progresstype=”circle”:percent=”100”:width=”80” /> <!-- 环形自动成功 --><cxl-progresstype=”dashboard”:percent=”100”:width=”80” /> <!-- 仪表盘自动成功 -->

动态状态切换：

<template> <view> <cxl-progress:percent=”statusPercent”:status=”currentStatus” /> <button @click=”currentStatus = 'normal'; statusPercent = 50”>正常</button> <button @click=”currentStatus = 'active'; statusPercent = 60”>活动</button> <button @click=”currentStatus = 'success'; statusPercent = 100”>成功</button> <button @click=”currentStatus = 'exception'; statusPercent = 40”>异常</button> </view></template><script>export default { data() { return { currentStatus: 'normal', statusPercent: 50 } }}</script>

示例5：自定义样式

cxl-progress 提供了丰富的自定义属性，让你可以打造出各种风格的进度条。

颜色自定义（含渐变色）：

<!-- 纯色 --><cxl-progress:percent=”50”strokeColor=”#1890ff” /><cxl-progress:percent=”65”strokeColor=”#722ed1” /><!-- 渐变色（仅线型支持） --><cxl-progress:percent=”70”strokeColor=”linear-gradient(90deg, #1890ff, #13c2c2)” /><cxl-progress:percent=”80”strokeColor=”linear-gradient(90deg, #f5222d, #faad14)” />

线条粗细对比：

<cxl-progress:percent=”60”:strokeWidth=”3”:showInfo=”false” /> <!-- 细线 --><cxl-progress:percent=”60”:strokeWidth=”6”:showInfo=”false” /> <!-- 默认 --><cxl-progress:percent=”60”:strokeWidth=”12”:showInfo=”false” /> <!-- 粗线 --><cxl-progress:percent=”60”:strokeWidth=”20”:showInfo=”false” /> <!-- 超粗 -->

端点形状：

<!-- 圆角（默认） --><cxl-progress:percent=”60”:strokeWidth=”10”strokeShape=”round” /><!-- 直角 --><cxl-progress:percent=”60”:strokeWidth=”10”strokeShape=”square” />

组合效果：

多种属性组合使用，打造独特的进度条：

<!-- 渐变 + 粗线 + 圆角 --><cxl-progress :percent=”85” :strokeWidth=”14” strokeColor=”linear-gradient(90deg, #722ed1, #eb2f96)” strokeShape=”round”/><!-- 紫色环形 --><cxl-progress type=”circle” :percent=”88” :width=”100” :strokeWidth=”10” strokeColor=”#722ed1”/><!-- 青色仪表盘 --><cxl-progress type=”dashboard” :percent=”72” :width=”100” :strokeWidth=”10” strokeColor=”#13c2c2”/>

跨端说明

cxl-progress 在跨端适配上做了专门的处理：

H5 端
：直接使用原生 <svg> 标签渲染环形进度条，效果最佳
小程序/App 端
：由于小程序不支持内联 SVG，组件自动将 SVG 转换为 data:image/svg+xml 的 base64 URL 形式，通过 background-image 方式显示

这些处理对使用者是完全透明的，你只需正常使用组件，无需关心底层渲染差异。

常见使用场景

场景	推荐类型	示例
文件上传进度	line	`<cxl-progress :percent="uploadPercent" />`
表单完成度	line + successPercent	`<cxl-progress :percent="80" :successPercent="50" />`
任务处理中	line + active	`<cxl-progress :percent="60" status="active" />`
存储空间使用	circle	`<cxl-progress type="circle" :percent="used" :width="100" />`
考试评分	dashboard	`<cxl-progress type="dashboard" :percent="score" />`
健康指数	dashboard + 动态颜色	根据数值范围自动变色

注意事项

percent
值范围为 0-100，超出范围会被自动修正
active
状态（流动动画）仅支持线型（line）
渐变色 linear-gradient 仅支持线型（line）
successPercent
分段进度仅支持线型（line）
width
属性仅对 circle 和 dashboard 类型生效
环形进度条的 strokeWidth 建议根据 width 大小适当调整，避免线条过粗或过细

总结

cxl-progress 是一个功能丰富、开箱即用的 uni-app 进度条组件。三种类型覆盖了从简单到复杂的所有进度展示需求，四种状态让进度反馈更加直观，丰富的自定义属性让你可以轻松适配各种 UI 风格。

如果你的项目中需要进度条组件，不妨试试 cxl-progress，一行代码即可使用！

Gitee 地址

本文示例代码已开源：

👉 https://gitee.com/hszcxl/TestUniapp/tree/cxl-progress

如果觉得本文对你有帮助，欢迎点赞、评论、转发支持！