做 Android 开发的朋友应该都被那个默认的绿色小进度条折磨过：想换个颜色，系统属性不给力；想加个圆角，样式直接放飞自我；想显示百分比文字，默认的 ProgressBar 根本不带这个功能。所以“Android 自定义 ProgressBar 进度条”几乎是每个项目里迟早都要做一遍的事。这篇内容我会从方案选型、自定义属性设计、核心绘制原理、常见坑点排查一路讲到底，适合刚开始接触自定义控件、被系统 ProgressBar 限制住的初级 Android 开发者，也适合想系统梳理绘制方案、避免重复造轮子的中级开发者。你不需要有什么特别深厚的图形学基础，只要会用 Canvas、看过 Android 的基础 View 生命周期，跟着思路走就能写出一个能落地、不卡顿、样式可控的进度条。
1. 别急着写代码，先想清楚你要的到底是哪种“自定义”
1.1 认清系统 ProgressBar 的能力边界
很多人一上来就找自定义方案，是因为被系统 ProgressBar 的样式恶心到了。默认的水平进度条只有一条细长的灰色轨道和一个黄色的进度块（不同主题下颜色还不一样），想改成圆角、渐变色、带气泡数字，靠 XML 里的 progressDrawable 也能改一点，但改到后面你会发现维护成本高得离谱，而且很多效果（比如双色渐变、分段进度、波浪效果）根本不是 drawable 能优雅解决的场景。
另外一点经常被忽略：ProgressBar 本身是带逻辑的。系统会处理 max、progress 的边界、setProgress 的动画回调，这些逻辑我们没必要推倒重来。所以在动手之前先问一句：你是要“换皮”还是“重新造轮子”？如果只是从绿色改成蓝色、从直角改成圆角，优先考虑通过 progressTint、backgroundTint 或者自定义 LayerDrawable 来做，代码量小、不会破坏原有生命周期。只有在系统进度条的粒度不能满足你的时候——比如你想在进度条内部绘制文字、粒子、自定义动画，才需要走继承 ProgressBar 或直接写自定义 View 的路线。
我个人比较推荐的做法是：能用系统属性解决的小改动，绝对不新建类；但一旦出现以下几种情况，就直接走自定义 View，别犹豫：
- 需要的视觉效果和轨道/进度块的大小、位置、形状强耦合（比如进度条中间要挖空显示图标）；
- 要在进度变化的同时绘制其他内容，比如文字、小图标、渐变高光；
- 需要处理触摸事件或动画插值，纯 XML 难以表达；
- 项目里有多个页面要用同一种特殊进度条，你希望沉淀成一个可复用组件。
1.2 三条路线怎么选
第一类：继承 ProgressBar。这种方式的好处是天然保留 max、progress、setProgress、动画回调等能力，外部调用方完全无感知。你只需要在 onDraw 里用 Canvas 自己画轨道和进度块即可。但注意一个小坑：ProgressBar 自己有一套绘制逻辑，如果你重写了 onDraw，记得不要调用 super.onDraw()，否则系统默认样式还会被画一遍，造成视觉叠加。
第二类：直接继承 View，自己管理 progress。这种方式的控制力最强，代码也最直观，适合做环形进度条、自定义交互界面。代价是你要自己维护业务逻辑，比如进度不能超过 max、更新进度后要主动 invalidate、测量宽度高度时的比例关系等。
第三类：组合布局。把 TextView、ImageView 和系统 ProgressBar 拼成一个自定义组合控件，常用于“进度条+文字百分比+小图标”的情况。这种方案不需要重绘，代码量小，但性能和样式的统一性要看你怎么封装。适合 UI 要求不极端、进度信息以文案为主的场景。
给你一个简单的选择依据：如果进度条的长宽比接近系统默认，且只需要换颜色/圆角，用 Theme 属性或 LayerDrawable；如果界面元素单一、需要高度自定义的绘制效果，用继承 View；如果进度条旁边还有多个附属控件要联动，用组合布局更省事。下面我重点讲继承 View 和继承 ProgressBar 的混合思路，因为这是大多数人真正会遇到的主流需求。
2. 第一步：把需求写进 attrs.xml，再搭好自定义 View 的骨架
2.1 用自定义属性把参数“声明”出来
做自定义控件最容易踩的坑就是硬编码。颜色、圆角大小、轨道高度、进度条高度直接写死在代码里，表面看“跑通了”，一旦换个页面换种配色，改到你怀疑人生。所以正确的第一步是在 res/values/attrs.xml 里把进度条的所有可配置项声明出来。
我通常会定义这样一组属性：
<declare-styleable name="RoundProgressBar"> <attr name="progressColor" format="color" /> <attr name="trackColor" format="color" /> <attr name="progressHeight" format="dimension" /> <attr name="trackHeight" format="dimension" /> <attr name="radius" format="dimension" /> <attr name="showText" format="boolean" /> <attr name="textColor" format="color" /> <attr name="textSize" format="dimension" /> <attr name="maxProgress" format="integer" /> <attr name="progress" format="float" /> </declare-styleable>为什么用 float 而不是 integer 来表示 progress？因为很多场景下进度值是带小数的，比如上传文件的字节数换算成百分比。你在自定义 View 内部把它转成实际的绘制比例即可，int 反而会导致进度精度丢失。
在构造函数里通过 context.obtainStyledAttributes 读取这些属性后，一定要记得调用 recycle()。这一步很多人都漏了，结果就是下一次读取属性时拿到残留值，排查半天还找不到原因。
然后实现一个最基本的 init 方法：初始化画笔 Paint、读取属性默认值、设置抗锯齿。这里给一个我常用的默认值策略：
- 轨道高度默认 8dp，进度条高度默认 8dp；
- 圆角半径默认是轨道高度的一半，这样画出来就是胶囊形状；
- 进度颜色默认使用主题色或 Color.BLUE；
- 文字默认不显示。
有个细节要提一下：dp 和 px 的转换。Android 里 XML 传入的 dimension 在 getDimension 时已经转成了 px，所以你拿到的值可以直接用。但如果用户在代码里直接 new 你的 View，就没法走 XML 属性，这时你要自己定义 dp2px 的转换方法。我的习惯是无论哪种情况，涉及尺寸的默认值都统一用 dp2px 换算，避免在 mdpi 和 xxxhdpi 屏幕上出现肉眼可见的尺寸差异。
2.2 测量逻辑：别让 wrap_content 变成“零宽度”
继承 View 写自定义控件时，默认是不处理 onMeasure 的。这时候如果你在 XML 里写 android:layout_width="wrap_content"，控件可能直接变成 0 宽度，进度条显示不出来。这个问题的根因是 View 的默认测量规格是 AT_MOST 时取背景尺寸，没有背景就取 0。
所以必须重写 onMeasure 方法，至少保证 wrap_content 时有一个合理的默认尺寸。
@Override protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) { int desiredWidth = dp2px(160); int desiredHeight = dp2px(20); int width = resolveSize(desiredWidth, widthMeasureSpec); int height = resolveSize(desiredHeight, heightMeasureSpec); setMeasuredDimension(width, height); }这里 resolveSize 是系统提供的方法，它会根据你的期望值和父布局的 MeasureSpec 来算出最终尺寸。简单说一下它的行为：如果父布局传的是 EXACTLY，就取父布局指定的值；如果是 AT_MOST，就取期望值和父布局限制值中较小的那个；如果是 UNSPECIFIED，就取你的期望值。所以这么写之后，wrap_content 会有一个 160dp x 20dp 的默认大小，match_parent 依然能撑满，不会破坏布局行为。
还有一个我踩过的坑：进度条高度和轨道高度容易混淆。很多人把 View 的布局高度直接当成轨道高度，结果进度条的实际绘制区域变小，文字和进度块被裁剪。你需要在 onLayout 或 onDraw 里明确算出一个 contentRect，把 paddingLeft、paddingTop、paddingRight、paddingBottom 都减掉，再在这个矩形里去布局轨道和进度。
3. 核心绘制实现：做一个圆角渐变水平进度条
3.1 轨道和进度块怎么画才不生硬
先把 Canvas 坐标系这个基础理一理。Android 的 Canvas 默认原点在 View 左上角，x 正方向向右，y 正方向向下。画进度条的逻辑其实不复杂：先在 y 方向上居中画一条轨道，再根据 progress 占 max 的比例，从左往右画出进度块。
轨道的绘制我会用 round rect 而不是普通矩形，这样四个角是圆角，在深色背景上更柔和。假设你已经算出了 contentRect，轨道的高度为 trackHeight，那么轨道的矩形应该是垂直居中的：
float trackTop = contentRect.centerY() - trackHeight / 2f; float trackBottom = trackTop + trackHeight; RectF trackRect = new RectF(contentRect.left, trackTop, contentRect.right, trackBottom); paint.setColor(trackColor); canvas.drawRoundRect(trackRect, radius, radius, paint);这里有一个关键点：圆角半径。如果 radius 比 trackHeight / 2 还大，系统会强制按一半处理，所以你在 XML 里写多大都不会崩，但视觉效果不会更“圆”。为了直观，我建议直接设置 radius = trackHeight / 2，得到的就是端到端的胶囊形。
画进度块时，最省事的做法是直接 clipRect 然后画一个圆角矩形：
float fraction = maxProgress == 0 ? 0 : progress / (float) maxProgress; float progressRight = contentRect.left + contentRect.width() * fraction; canvas.save(); canvas.clipRect(contentRect.left, trackTop, progressRight, trackBottom); canvas.drawRoundRect(trackRect, radius, radius, progressPaint); canvas.restore();逻辑是：先画一个和轨道一样大小的圆角矩形，但通过裁剪限制它的右边界，这样就能得到“左侧圆角、右侧平齐或带圆角截断”的效果。为什么不用直接把宽度乘比例的方式画一个动态宽度的圆角矩形？因为右侧的圆角半径是固定的，如果进度只有 10%，右边那个小小的圆角会让进度块看起来像一条胶囊头而不是被切平，视觉上不一致。用 clip 方式能保证整条进度块始终是完整圆角矩形被切割出来的，前后效果统一。
渐变效果可以借助 LinearGradient。比如同时设置 startX、endX，让颜色从浅蓝过渡到深蓝。这里要注意 Shader 的边界范围，它默认只在绘制区域内部生效，如果你给 progressPaint 设置了 LinearGradient，并且 Shader 的坐标是基于整个 View 宽度，那么进度只走到 30% 时渐变效果会显得“被压缩”而不是“被截断”。这其实是很多自定义效果看起来不对劲的根源。我建议把 Shader 的范围始终设置为轨道的完整宽度，这样不管进度在哪个位置，颜色渐变都是均匀的，符合视觉预期。
3.2 让进度条动起来：直接 invalidate 还是开动画
进度条不是静态图片，它要平滑地从 0 走到 100。最简单粗暴的写法是用户在业务代码里循环调用 setProgress，然后你在这个方法里调 invalidate()。比如下载文件时，网络回调线程每 100ms 更新一次进度值。但如果每次收到的进度差值很大，进度条会看起来一顿一顿的，体验很差。
我的做法是提供一个带动画的接口：
public void setProgressAnimated(float targetProgress, long duration) { ValueAnimator animator = ValueAnimator.ofFloat(getProgress(), targetProgress); animator.setDuration(duration); animator.setInterpolator(new DecelerateInterpolator()); animator.addUpdateListener(animation -> { setProgress((float) animation.getAnimatedValue()); }); animator.start(); }为什么用 DecelerateInterpolator？因为绝大多数业务场景希望进度“先快后慢”，比如加载页的进度条，速度过快会有催促感，立即突然停住也显得生硬。先快后慢会让人觉得更自然。如果你想做下载进度这类需要尽量真实的场景，反而建议用 LinearInterpolator，因为不确定的网络状态会不断纠正动画目标，插值器太重只会造成视觉上的持续卡顿。
另外，invalidate 不要滥用。可以在 setProgress 内部加一个判断：只有当前值和目标值之差大于某个最小像素阈值时才重绘，否则直接赋值。这个阈值怎么算？用进度条的宽度乘以一像素对应的进度比例，大概就能避免 0.1% 的微小变化也触发全量重绘。举个例子：如果控件宽度是 1000px，max 是 10000，那么 1px 对应的进度是 10，只有变化量超过 10 才刷新。这样在 RecyclerView 滑动的场景里不会因为频繁刷新 layout 导致掉帧。
4. 进阶细节：文字百分比、环形进度条与性能避坑
4.1 在进度条中间画出文字，位置计算是关键
带文字的自定义进度条是实际项目里出现频率最高的需求。文字的位置一般分两种：进度条内部左下角/中心，或者进度条右侧。先说中心的情况，用 Paint.measureText 量出文字的宽度，然后画在控件中心：
String text = (int) (progress * 100 / maxProgress) + "%"; float textWidth = textPaint.measureText(text); float baselineX = contentRect.centerX() - textWidth / 2f; Paint.FontMetrics fm = textPaint.getFontMetrics(); float baselineY = contentRect.centerY() - (fm.descent + fm.ascent) / 2f; canvas.drawText(text, baselineX, baselineY, textPaint);这里最坑的是 baselineY 的计算。很多人直接用 contentRect.centerY() 作为 y 坐标，结果文字永远偏高或偏低。原因是 drawText 的 y 参数是文字的 baseline，而不是文字的中心，baseline 之上是 ascent，之下是 descent。正确的做法是用 FontMetrics 算出 ascent 和 descent 的平均值，让文字视觉上居中。
如果文字要显示在进度块的前端（比如进度条走到哪文字跟到哪），位置就要contentRect.left + contentRect.width() * fraction - textWidth - 间距，并且要做边界判断：进度太小时文字不能冲出左边，太大时不能超出右侧。这个逻辑虽然简单，但漏了边界判断会出现文字被裁剪的诡异效果。
4.2 环形进度条和分段进度条：换一种坐标系而已
环形进度条的本质是把进度条从直线映射到圆弧。使用 Canvas.drawArc 时，起点和扫过的角度是关键。以 12 点钟方向为起点，顺时针绘制的好处是符合用户的视觉直觉：
float startAngle = -90f; float sweepAngle = 360f * fraction; canvas.drawArc(rectF, startAngle, sweepAngle, false, progressPaint);rectF 是外接圆区域，半径大小取决于 View 的宽高较小值，ringWidth（环宽）决定弧线宽度。坚决不建议直接画一个圆环再在中间填充颜色，那样边缘锯齿会很明显。正确做法是给 paint 设置 strokeWidth，并使用圆角 strokeCap：
paint.setStyle(Paint.Style.STROKE); paint.setStrokeWidth(ringWidth); paint.setStrokeCap(Paint.Cap.ROUND);用 strokeCap = ROUND 画出来的进度条，两端是圆形的，视觉上高级很多。但要注意，这个圆头会让弧线两端超出 rectF 边界，如果环的宽度很大，显示起来可能“超出”控件范围，记得在 onDraw 里给 rectF 缩进 strokeWidth / 2。
分段进度条本质上是把 fraction 切割成若干段：先算出总段数，每一段占一个固定角度或水平宽度，段与段之间留出间隙。实现的时候不要去算每一段的起点和终点，而是先画完整轨道，再用 clip 把分段空隙的区域挖掉，或者反过来先画背景段再覆盖进度段，效率更高。
4.3 在 RecyclerView 高频刷新场景里的性能避坑
自定义进度条放列表里，最典型的坑是“滑动时进度条会闪”和“多个 item 共用进度条导致状态错乱”。前者一般是因为 itemView 复用后没有重置 progress，后者是因为你把动画的 ValueAnimator 放到了自定义 View 内部，列表快速滑动时，动画更新回调在非 UI 线程或者频繁创建导致内存抖动。
我的经验是：列表里的进度条尽量做成“哑巴控件”，也就是 View 本身只负责根据 progress 重绘，不管理动画。动画放到 Adapter 或 ViewModel 层控制，进度更新通过 data binding 或接口回调驱动。另外，如果一个列表同时出现多个进度不同的 item，不要在 onBindViewHolder 里每次都调用 setProgressAnimated，否则快速滑动时动画和复用逻辑会互相打架。正确做法是首次加载时用动画，后续刷新直接 setProgress 无动画。
还有一个内存细节：ValueAnimator 是有生命周期的。如果你在自定义 View 内部启动动画，View 被 remove 时没有 cancel 动画，会造成内存泄漏。至少在 onDetachedFromWindow 里把动画 cancel 掉：
@Override protected void onDetachedFromWindow() { super.onDetachedFromWindow(); if (animator != null) { animator.cancel(); } }虽然有些同学觉得小项目无所谓，但在实际列表复用的场景里，这个问题会导致 GC 频繁触发，页面滚动时掉帧明显。
5. 常见问题速查：进度条为什么不显示、不刷新、位置不对
5.1 进度条不显示的高频原因
我整理一下这几年看到最多的几类问题：
一是 View 的宽高为 0。前面说过 wrap_content 默认可能测量为 0，或者布局嵌套里被某个不可见的父容器挤压成 0。排查方法很简单：在 onDraw 里先打 Log 输出 getWidth() 和 getHeight()，如果为 0，优先检查布局参数。
二是进度值没有触发重绘。自定义 View 里面 setProgress 之后忘了调 invalidate()，进度条自然纹丝不动。我见过不少初学者直接在 Activity 里 new 一个自定义 View 并设置 progress，却不调用 invalidate，结果崩溃式调试一整天。记住：自定义 View 的属性变化不会自动触发 onDraw，必须显式请求重绘。
三是画笔设置问题。比如设置了 Paint.Style.FILL 画轨道，然后画进度块时忘了切换为 STROKE，或者 shader 没设置边界，导致进度块不可见。还有一个隐蔽的问题是 Paint 的 alpha：如果 toggling 了 alpha，进度刷新时旧的 alpha 没有 reset 回 255，进度条会越来越淡甚至隐形。
四是属性文件没生效。使用 declare-styleable 时，如果你在 getDrawable 或 getColor 时用了错误的资源 ID，或者直接复用了同一个 attrs 数组，会出现颜色、尺寸拿到默认值的情况。注意 context.obtainStyledAttributes(attrs, R.styleable.RoundProgressBar) 里的 attrs 必须是构造函数传进来的那个，不要自己 new 一个空 int 数组，否则读取到的都是默认值。
5.2 位置不对和状态错乱的坑
进度条整体偏移，多半是没考虑 padding。自定义 View 处理 padding 的原则和普通 View 一样：绘制内容时必须把 padding 考虑进去。如果不想考虑，建议在构造函数里 setWillNotDraw(false)，并手动把 padding 加到整个控件的尺寸计算里。另一种做法是直接把 paddingLeft 和 paddingTop 加到内容区域起点，这是最简单的处理方式。
多状态错乱的经典场景是：同一个 View 被多个线程同时 setProgress。Android 的 View 刷新是线程不安全的，不要在子线程直接调用 invalidate。很多同学会用 Handler 或者 View.post 来解决，但更规范的做法是让进度更新通过主线程回调节点统一派发。
我再补充一个可能有点反直觉的点：ProgressBar 的 max 默认是 100，但如果是做文件上传，进度值可能是字节数。强烈建议在自定义 View 内部直接透传真实值，而不是提前换算成 0-100。因为换算之后 UI 层拿到的是一个没有语义的数字，后续想显示大小、剩余时间、速度等信息都无从下手。我在项目里一般把 progress 直接设为已上传字节数，max 设为文件总字节数，然后在绘制时算 fraction。
6. 我在实际项目中的几个小经验
做自定义 ProgressBar 这几件事，每次都能帮我省不少调试时间：一是属性声明时把默认值全部收敛到一个方法里，不要在构造函数里到处 new Paint。二是画任何自定义 View 之前先画一个 Debug 背景色（比如半透明红色），这样能立刻看出来控件的实际边界和内容区域是否如你预期。等形状确认没问题了，再把这个调试背景删掉。三是画完一个效果后，一定在 minSdk 和 targetSdk 之间多个版本跑一遍，Android 的硬件加速策略在不同版本上对 Canvas 的影响略有差异，比如某些旧版本上 drawRoundRect 配合 clipRect 可能会出现圆角边缘锯齿，这时候老老实实开启抗锯齿并降低绘制区域的复杂度。
如果你正打算在项目里引入自定义进度条，不妨从一个最简单的圆角水平进度条开始，先打通属性读取、测量、绘制、刷新的完整链路，再逐步加文字、加动画、加环形变体。第一次做不会太久，但做完之后这个组件能覆盖项目里大多数“进度展示”的需求。后面如果再遇到 loading、上传、下载、引导页这类场景，你已经有了一个可以快速复用的基础，不用再到处找轮子。
