Uni-app实战：从零构建高定制化微信小程序圆环进度条组件

最近在几个Uni-app项目中，我都遇到了需要展示进度数据的场景。无论是健身App的运动目标完成度，还是学习平台的任务进度，传统的条形进度条总觉得少了点视觉冲击力。圆环进度条那种直观的“填充感”，确实更能激发用户的完成欲望。但市面上的组件库要么太重，要么定制性不够，特别是要在微信小程序里跑得流畅，还得兼顾多端表现一致，这事儿就得自己动手了。

如果你也受够了东拼西凑的解决方案，想拥有一个完全可控、性能优异且能无缝融入微信小程序环境的圆环进度条，那这篇文章就是为你写的。我不会只扔给你一段代码，而是带你走一遍我实际开发中的思考路径：从最基础的CSS绘制原理，到如何在Uni-app的编译环境下规避小程序的样式陷阱，再到如何封装成一个高度可配置、带平滑动画的健壮组件。过程中遇到的坑和优化技巧，我都会毫无保留地分享出来。

1. 解构圆环：为何不直接用Canvas？

一提到绘制图形，很多开发者的第一反应是Canvas。没错，Canvas功能强大，几乎能画任何东西。但在微信小程序里，特别是在Uni-app这种多端框架下，过度使用Canvas来实现一个简单的进度环，可能有点“杀鸡用牛刀”了。

Canvas方案的主要顾虑：

  • 性能开销：频繁重绘（比如实现动画）对性能有影响，尤其在低端机型上。
  • 渲染层级：Canvas是原生组件，在微信小程序中层级最高，会覆盖在普通视图组件之上，布局时容易产生遮挡问题。
  • 开发复杂度：需要自己处理绘制逻辑、动画帧管理，代码量相对较大。

而纯CSS方案则轻量得多。它利用border、border-radius、transform和overflow: hidden这些属性，通过多个view的层叠与旋转来模拟出圆环效果。其优势非常明显：

  • 性能优异：利用浏览器（或小程序视图层）的GPU加速进行变换和合成，动画流畅。
  • 布局自然：作为普通视图组件，可以轻松使用Flexbox或Grid布局，与页面其他元素无缝融合。
  • 维护简单：结构清晰，样式调整方便。

当然，CSS方案的挑战在于理解其“欺骗视觉”的层叠模型。别担心，接下来我们就一步步拆解。

1.1 核心绘制原理：左半圆与右半圆的舞蹈

整个圆环进度条的核心思想，是将一个完整的圆环在视觉上拆分成左右两半，分别进行控制。每一半的实现，都遵循一个五层的嵌套结构。理解了这个，你就掌握了钥匙。

提示：你可以把每一层view想象成一张透明的圆形胶片，我们通过旋转和遮盖，让特定部分显示出颜色。

我们以左半圆（0%到50%进度）为例，拆解这五层：

  1. 第一层：限定区域。一个宽为直径一半、高为直径的矩形容器。它决定了左半圆活动的“舞台”边界，并通过overflow: hidden确保任何超出右边界的内容都被裁剪掉。
  2. 第二层：决定显示哪半边。一个和完整圆环同样大小的正方形，定位在容器内。这一层是整个魔术的关键。我们通过transform: rotate()来旋转它。当进度为0%时，它旋转-180度（即逆时针半圈），将画有颜色的部分转到舞台可见区域之外；随着进度增加，它逐渐向0度旋转，颜色部分慢慢进入视野。
  3. 第三层：绘制底色圆环。在第二层内部，我们首先放置一个view，为其设置很粗的border和border-radius: 50%，形成一个圆环，颜色使用进度激活色（比如橙色）。
  4. 第四层：制造“半圆”效果。在第三层同级，我们放置另一个view，将其宽度设为容器宽度的一半（即直径的一半），并定位到右侧。在这个view内部，我们再画一个圆环，但颜色使用圆环的底色（比如灰色）。这个灰色圆环会遮盖住第三层橙色圆环的右半边。
  5. 第五层：旋转第二层。通过动态计算进度值，改变第二层的rotate角度，从而控制左半圆显示的比例。

右半圆的逻辑完全对称，只是它的“舞台”（第一层）是另一个宽为直径一半的矩形，定位在右侧，并且裁剪方向相反。当进度超过50%时，左半圆完全显示（旋转到0度），右半圆开始从0度向180度旋转，完成剩余部分的填充。

为了让这个原理更直观，我们用一个表格对比左右半圆的关键差异：

特性左半圆容器 (第一层)右半圆容器 (第一层)第二层旋转起点 (0%进度)第二层旋转终点 (50%进度)
作用控制圆环左半部分控制圆环右半部分-180度0度
宽度直径 / 2直径 / 20度180度
定位left: 0right: 0 (或 left: 直径/2)
溢出隐藏裁剪右侧裁剪左侧

2. 在Uni-app中落地：组件设计与实现

理解了原理，我们就可以动手编码了。在Uni-app中，我们将创建一个单文件组件（SFC），确保其具有良好的可复用性和可配置性。

2.1 组件属性定义：开放哪些控制权？

一个好的组件应该像乐高积木，调用者可以通过参数灵活调整其外观和行为。我们的圆环进度条需要以下属性：

// components/progress-circle/progress-circle.vue - <script> 部分
export default {
  name: 'ProgressCircle',
  props: {
    // 环形直径，单位px
    diameter: {
      type: Number,
      default: 200
    },
    // 环形线条的粗细，单位px
    strokeWidth: {
      type: Number,
      default: 10
    },
    // 进度值，范围 0 ~ 1
    percent: {
      type: Number,
      default: 0,
      validator(val) {
        return val >= 0 && val <= 1;
      }
    },
    // 环形主色（进度部分）
    activeColor: {
      type: String,
      default: '#07c160' // 微信绿
    },
    // 环形背景色
    backgroundColor: {
      type: String,
      default: '#ebedf0'
    },
    // 组件背景色（通常设为透明或页面底色）
    bgColor: {
      type: String,
      default: 'transparent'
    },
    // 是否开启动画
    animate: {
      type: Boolean,
      default: false
    },
    // 动画时长（毫秒），仅在 animate 为 true 时生效
    duration: {
      type: Number,
      default: 800
    }
  },
  // ... data, computed, methods 等后续展开
}

这里我特意增加了duration属性，让动画速度可调，比固定间隔的setInterval体验更好。validator确保了传入的进度值合法。

2.2 计算属性：动态样式的核心

大部分动态样式我们都通过计算属性来生成，这样既清晰又高效。计算属性会根据percent、diameter等props的值自动更新。

computed: {
  // 第一层容器样式：左半圆和右半圆的“舞台”
  halfContainerStyle() {
    return {
      width: `${this.diameter / 2}px`,
      height: `${this.diameter}px`,
      position: 'relative',
      overflow: 'hidden' // 关键！用于裁剪
    };
  },
  // 第二层：可旋转的层
  rotatableLayerStyle() {
    // 基础样式：一个和圆环一样大的方块
    return {
      position: 'absolute',
      top: 0,
      width: `${this.diameter}px`,
      height: `${this.diameter}px`,
      // 注意：左半圆和右半圆的left/right定位在模板中单独处理
    };
  },
  // 第三层：绘制圆环本身的样式（激活色）
  circleStyle() {
    const radius = this.diameter / 2;
    return {
      width: `${this.diameter}px`,
      height: `${this.diameter}px`,
      borderRadius: `${radius}px`,
      borderWidth: `${this.strokeWidth}px`,
      borderStyle: 'solid',
      borderColor: this.activeColor,
      boxSizing: 'border-box'
    };
  },
  // 左半圆第二层的旋转角度
  leftRotation() {
    let angle = -180; // 初始状态，完全隐藏
    if (this.displayPercent < 0.5) {
      // 进度在0%~50%，左半圆从-180度旋转到0度
      angle += (180 * (this.displayPercent / 0.5));
    } else {
      // 进度超过50%，左半圆完全显示
      angle = 0;
    }
    return `transform: rotate(${angle}deg);`;
  },
  // 右半圆第二层的旋转角度
  rightRotation() {
    let angle = 0; // 初始状态，完全隐藏
    if (this.displayPercent > 0.5) {
      // 进度在50%~100%，右半圆从0度旋转到180度
      angle = 180 * ((this.displayPercent - 0.5) / 0.5);
    }
    return `transform: rotate(${angle}deg);`;
  },
  // 进度端点（圆环头部的小圆点）样式
  endPointStyle() {
    const centerRadius = 2; // 中心小圆点的半径
    const ringRadius = this.diameter / 2; // 圆环半径
    const pointLeft = ringRadius - this.strokeWidth / 2; // 圆点中心位置
    return {
      position: 'absolute',
      top: 0,
      left: `${pointLeft}px`,
      width: `${this.strokeWidth}px`,
      height: `${this.strokeWidth}px`,
      borderRadius: `${this.strokeWidth / 2}px`,
      borderWidth: `${(this.strokeWidth / 2) - centerRadius}px`,
      borderStyle: 'solid',
      borderColor: this.activeColor,
      backgroundColor: this.displayPercent >= 0.5 ? this.activeColor : this.backgroundColor,
      boxSizing: 'border-box',
      zIndex: 10 // 确保在最上层
    };
  }
}

注意，我使用了this.displayPercent而不是直接的this.percent。这是因为我们需要一个内部变量来驱动动画，这个变量会在data中定义，并通过动画函数从0渐变到目标值this.percent。

2.3 平滑动画实现：告别生硬的跳变

直接让进度条从0%跳到80%会很突兀。我们实现一个平滑的过渡动画。这里我选择使用requestAnimationFrame，它比setInterval更适合做动画，能确保与屏幕刷新率同步，更流畅也更省电。

data() {
  return {
    displayPercent: 0, // 用于动画显示的当前进度
    animationFrameId: null, // 存储动画帧ID，便于取消
    startTime: null,
    startValue: 0,
    targetValue: 0
  };
},
methods: {
  // 启动或更新动画
  updateAnimation(newPercent) {
    // 取消可能正在进行的动画
    if (this.animationFrameId) {
      cancelAnimationFrame(this.animationFrameId);
    }
    this.targetValue = newPercent;
    this.startValue = this.displayPercent;
    this.startTime = null;
    const animate = (currentTime) => {
      if (!this.startTime) this.startTime = currentTime;
      const elapsed = currentTime - this.startTime;
      // 计算当前进度（使用缓动函数easeOutCubic，效果更自然）
      const progress = Math.min(elapsed / this.duration, 1);
      const easeProgress = 1 - Math.pow(1 - progress, 3);
      this.displayPercent = this.startValue + (this.targetValue - this.startValue) * easeProgress;
      if (progress < 1) {
        this.animationFrameId = requestAnimationFrame(animate);
      } else {
        this.displayPercent = this.targetValue; // 确保最终值精确
        this.animationFrameId = null;
      }
    };
    this.animationFrameId = requestAnimationFrame(animate);
  }
},
watch: {
  percent: {
    immediate: true, // 组件创建时立即执行一次
    handler(newVal) {
      if (this.animate) {
        this.updateAnimation(newVal);
      } else {
        // 不开启动画，直接赋值
        this.displayPercent = newVal;
      }
    }
  }
},
beforeDestroy() {
  // 组件销毁前，务必清理动画帧
  if (this.animationFrameId) {
    cancelAnimationFrame(this.animationFrameId);
  }
}

这段代码实现了一个带缓动效果的线性动画。easeOutCubic函数让动画在结尾时减速，显得更自然。你也可以尝试其他缓动函数，比如easeOutQuad或easeOutExpo，来获得不同的动态效果。

3. 微信小程序特定优化与避坑指南

Uni-app虽然号称“一套代码，多端运行”，但编译到不同平台时，细节差异依然存在。针对微信小程序，有几个地方需要特别注意。

3.1 样式兼容性：-webkit- 前缀与盒子模型

小程序的内核渲染样式与WebView略有不同。最典型的是transform属性。虽然现代浏览器已经不需要前缀，但在某些小程序版本中，为了确保rotate生效，可能需要同时加上-webkit-前缀。

在Uni-app中，我们可以利用条件编译来优雅地处理这个问题：

<!-- 在模板中，动态生成样式字符串 -->
<view :style="rotatableLayerStyle + (isMPWeixin ? '-webkit-transform: ' + leftRotation + ';' : '') + leftRotation">

对应的，我们需要一个计算属性来判断环境：

computed: {
  isMPWeixin() {
    // #ifdef MP-WEIXIN
    return true;
    // #endif
    // #ifndef MP-WEIXIN
    return false;
    // #endif
  }
}

但实际上，Uni-app的编译器在打包到微信小程序时，已经帮我们处理了大部分样式兼容。更常见的问题是盒子模型。务必在所有容器view上设置box-sizing: border-box;，这样才能确保border的宽度被计算在元素的总宽高内，避免布局错乱。我们在组件最外层的样式里已经统一设置了。

3.2 性能考量：避免不必要的渲染

小程序视图层的更新通信是有成本的。我们的组件在percent变化时，会触发一系列计算属性的重新计算和视图渲染。为了优化：

  1. 使用v-if替代v-show：对于进度端点（小圆点），当进度为0或1时，它不应该存在。使用v-if可以避免渲染不必要的节点。
    <view v-if="displayPercent > 0 && displayPercent < 1" :style="endPointStyle"></view>
  2. 样式对象缓存：对于静态或变化不频繁的样式（如circleStyle），计算属性是高效的。Vue会对其依赖进行缓存。确保你的计算属性只依赖于必要的props。
  3. 动画节流：我们使用的requestAnimationFrame本身就是在最佳时机触发回调，已经是最优解。避免在动画过程中进行复杂的DOM查询或其他同步操作。

3.3 真机调试常见问题

  • 圆环边缘锯齿：在部分安卓机型上，旋转的圆环边缘可能出现锯齿。可以尝试为旋转的元素添加transform: translateZ(0);或will-change: transform;来触发GPU硬件加速，让边缘更平滑。
  • 进度端点错位：计算端点位置时，务必考虑strokeWidth。端点的中心应该位于圆环轨迹的中心线上，即 left: (直径 - 线条粗细) / 2。
  • 背景色穿透：如果组件背景色bgColor设为transparent，在复杂的页面背景下，圆环的遮盖层可能失效，导致显示异常。如果遇到此问题，可以将bgColor设置为与父容器背景一致的颜色。

4. 进阶应用与扩展思路

一个基础的圆环进度条已经完成了。但我们可以让它变得更强大、更贴合业务。

4.1 添加文本标签与自定义插槽

很多时候，我们需要在圆环中心显示百分比数字或其他信息。我们可以通过插槽（slot） 来实现，赋予组件最大的灵活性。

<!-- 在组件模板的合适位置，通常是在所有半圆层之下、最外层容器之内 -->
<view class="center-slot" :style="slotContainerStyle">
  <slot>
    <!-- 默认内容：显示百分比 -->
    <text class="default-text">{{ Math.round(displayPercent * 100) }}%</text>
  </slot>
</view>

computed: {
  slotContainerStyle() {
    // 让插槽容器居中，并防止其被圆环遮挡
    const offset = this.strokeWidth + 4; // 留一点边距
    return {
      position: 'absolute',
      top: `${offset}px`,
      left: `${offset}px`,
      width: `${this.diameter - offset * 2}px`,
      height: `${this.diameter - offset * 2}px`,
      borderRadius: '50%',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      zIndex: 5
    };
  }
}

这样，使用者既可以采用默认的百分比显示，也可以完全自定义中心区域的内容，比如放入图标、多行文字等。

4.2 实现渐变色彩与分段进度

如果产品经理想要一个从蓝色渐变到紫色的炫酷圆环，或者需要将进度分成不同颜色的几段，我们该如何扩展？

对于渐变色彩，纯CSS实现环形渐变在微信小程序视图层中比较困难。一个实用的降级方案是：使用多个重叠的、颜色不同的圆环，通过控制它们的显示范围来模拟渐变。但这会显著增加复杂度。对于追求极致效果的场景，可能不得不回归Canvas方案。

对于分段进度，则可以在现有架构上修改。思路是：将多个我们现有的“基础圆环”叠在一起，每个设置不同的activeColor和percent，但后一个的percent要大于前一个。例如，第一段0-30%用红色，第二段30-80%用黄色，第三段80-100%用绿色。我们需要调整组件，让背景色不是完整的圆环，而是根据上一段的结束位置开始绘制。这需要修改圆环绘制逻辑，计算起始角度和结束角度。

4.3 封装为Uni-app插件或npm包

当你觉得这个组件足够稳定和通用后，可以考虑将其封装起来，方便在所有项目中复用。

  1. 创建插件目录结构：
    uni-progress-circle/
├── components/
│   └── progress-circle/
│       ├── progress-circle.vue
│       └── index.js (用于easycom自动引入)
├── package.json
└── README.md
  2. 配置package.json和index.js：
    // package.json
{
  "name": "uni-progress-circle",
  "version": "1.0.0",
  "description": "A customizable circular progress bar for Uni-app",
  "main": "components/progress-circle/index.js",
  // ...
}

    // components/progress-circle/index.js
import ProgressCircle from './progress-circle.vue'
export default ProgressCircle
  3. 发布到npm：使用npm publish命令发布。之后，在其他Uni-app项目中，只需npm install uni-progress-circle，并在pages.json中配置easycom规则（如果组件符合其目录规范，Uni-app默认支持），即可在任何页面直接使用<progress-circle>标签。

经过以上四个部分的拆解、实现、优化和扩展，你已经不仅仅得到了一个圆环进度条组件，更掌握了一套在Uni-app环境下开发复杂UI组件的完整方法论。从原理分析到平台适配，从性能优化到生态封装，每一步都来源于真实的项目实践。下次再遇到特殊的UI需求，相信你也能从容地设计出属于自己的解决方案了。

# 微信小程序
Logo
乐奇 Rokid 开放社区

更多推荐

AI 智能眼镜的柔性神经，开启轻量化人机交互新世代

AI 智能眼镜的核心诉求，是在接近传统眼镜的轻薄体积内，塞进 AI 主控芯片、摄像头、麦克风阵列、骨传导 / 扬声器、光波导显示模组、触控传感器、电池、蓝牙 / Wi-Fi 射频模块等大量器件。随着 AI 眼镜出货量快速上行，鹏鼎、弘信、则成等国内 FPC 厂商纷纷布局 AI 眼镜软板、软硬结合板量产方案，单机 FPC 价值量显著高于 TWS 耳机，带动国内柔性线路板供应链升级，倒逼国内厂商突破超

avatar 乐奇 Rokid 开放社区

听书阁：让你在 AR 眼镜上也可以读小说

戴上眼镜之后我才发现，"翻页"是个需要用手完成的动作。手机上有触屏，滑动、点按、长按选词，一整套肌肉记忆。到了 AR 眼镜上这些全没了：视野只有一小块，手上可能还拎着东西，能稳定输入的只剩嘴和眼镜腿上的几颗按键。把手机阅读器原样搬过来没有意义，得重新想一遍"读一本书"在眼镜上该拆成哪几个动作。听书阁就是这次重想的产物。它跑在 Rokid Craft 上，用 AIUI 的 Ink 写页面，四个页面加

avatar 乐奇 Rokid 开放社区
cover

Python 技术报告：从 2026 长沙 AI 构建者大会到 Rokid 生态的开发者实践

avatar 乐奇 Rokid 开放社区