CircularProgressBar

丈夫志四海，万里犹比邻。—— 曹 植《赠白马王彪》

https://github.com/lopspower/CircularProgressBar

Android 自定义控件推荐：CircularProgressBar 完美实现圆形进度条

在 Android 开发中，进度条是一种非常常见的 UI 元素，用于展示任务的完成进度。虽然系统自带了 ProgressBar，但其样式单一，无法满足复杂的 UI 需求。为了解决这一问题，CircularProgressBar 提供了一种简单易用的解决方案，帮助我们轻松实现高度定制化的圆形进度条。

本篇文章将为你详细介绍 CircularProgressBar 的功能、特点以及如何快速上手使用。

---

什么是 CircularProgressBar？

CircularProgressBar 是一个开源的自定义控件，用于实现 Android 中的圆形进度条。由 lopspower 开发，CircularProgressBar 提供了灵活的 API 和丰富的样式选项，可以轻松满足各种设计需求。

---

CircularProgressBar 的功能亮点

• 高度可定制化：支持设置圆环的颜色、宽度、背景颜色等属性。
• 支持动画：进度条更新时支持平滑动画效果。
• 轻量级：无额外依赖，易于集成到任何项目中。
• 简单易用：只需几行代码即可快速实现。

---

快速上手指南

1. 添加依赖

在项目的 build.gradle 文件中添加以下依赖：

dependencies {
    implementation 'com.mikhaellopez:circularprogressbar:latest_version'
}

将 latest_version 替换为 Releases 页面 中的最新版本号。

---

2. 在布局文件中使用

在 XML 布局中添加 CircularProgressBar：

<com.mikhaellopez.circularprogressbar.CircularProgressBar
    android:id="@+id/circularProgressBar"
    android:layout_width="200dp"
    android:layout_height="200dp"
    app:cpb_progress="65"
    app:cpb_progressBarWidth="10dp"
    app:cpb_backgroundProgressBarWidth="5dp"
    app:cpb_progressBarColor="@color/blue"
    app:cpb_backgroundProgressBarColor="@color/gray"
    app:cpb_roundBorder="true"
    app:cpb_startAngle="90" />

常用属性说明

• app:cpb_progress：设置当前进度（范围为 0-100）。
• app:cpb_progressBarWidth：设置圆环的宽度。
• app:cpb_backgroundProgressBarWidth：设置背景圆环的宽度。
• app:cpb_progressBarColor：设置圆环的颜色。
• app:cpb_backgroundProgressBarColor：设置背景圆环的颜色。
• app:cpb_roundBorder：是否启用圆角边框。
• app:cpb_startAngle：设置进度条的起始角度。

---

3. 在代码中动态控制

CircularProgressBar 提供了丰富的 API，可以在代码中动态控制其行为：

val circularProgressBar = findViewById<CircularProgressBar>(R.id.circularProgressBar)

// 设置当前进度
circularProgressBar.setProgressWithAnimation(75f, duration = 1000L)

// 动态更改圆环颜色
circularProgressBar.progressBarColor = ContextCompat.getColor(this, R.color.green)

// 动态更改背景圆环颜色
circularProgressBar.backgroundProgressBarColor = ContextCompat.getColor(this, R.color.light_gray)

// 设置圆环宽度
circularProgressBar.progressBarWidth = 15f

以上方法让你可以根据业务需求灵活调整进度条的样式和功能。

---

动画效果

CircularProgressBar 默认支持平滑的动画效果，当调用 setProgressWithAnimation 方法时，可以指定动画的持续时间。

示例代码：

circularProgressBar.setProgressWithAnimation(50f, duration = 2000L)

通过这种方式，可以为用户提供更好的视觉体验。

---

进阶功能

1. 设置渐变颜色

CircularProgressBar 支持为圆环设置渐变颜色，代码示例如下：

circularProgressBar.apply {
    progressBarColorStart = ContextCompat.getColor(this@MainActivity, R.color.blue)
    progressBarColorEnd = ContextCompat.getColor(this@MainActivity, R.color.green)
    progressBarColorDirection = CircularProgressBar.GradientDirection.TOP_TO_BOTTOM
}

2. 自定义起始角度

通过 cpb_startAngle 属性，可以自定义进度条的起始位置。例如，设置为 0 表示从顶部开始。

---

实际应用场景

1. 健身应用

在健身类应用中，使用圆形进度条展示每日运动目标的完成情况。

2. 下载进度

在下载管理器中，用圆形进度条展示文件的下载进度。

3. 计时器

在倒计时功能中，将圆形进度条与计时功能结合，展示剩余时间。

---

总结

CircularProgressBar 是一个功能强大且易于使用的自定义控件，不仅可以满足 Android 开发中各种进度条场景的需求，还能通过丰富的样式和动画效果提升用户体验。如果你正在寻找一款高效的圆形进度条工具，不妨尝试一下 CircularProgressBar。

项目地址：https://github.com/lopspower/CircularProgressBar