Android自定义TextView歌词渐变：LinearGradient与Shader实战

简介：这是一份面向 Android 开发者的自定义控件源码，聚焦歌词风格的文字渐变效果，适合想学习自定义 View 与 Shader 绘制的中级开发者参考。资源通过 Gradient 渐变让 TextView 的文字颜色由一种颜色平滑过渡到另一种，可用于音乐播放器歌词、标题高亮等场景。压缩包共 39 个文件，约 101KB，包含 6 个 java 源码文件、13 个 xml 布局与配置、5 张 png 效果图，以及 4 个 gradle 构建脚本和 properties、jar 等辅助文件，结构上分为 app 示例模块与 mylibrary 库模块，便于直接运行查看效果或抽取控件集成到自己的工程。目前已有 495 人学习下载。读者可从中掌握自定义 View 的测量、绘制流程，理解 LinearGradient 在文字着色中的用法，并参考其模块划分与依赖配置方式，快速将渐变文字效果落地到实际项目中。

1. 歌词渐变 TextView：一个把文字玩出光影层次的自定义控件

做音乐播放器时，歌词逐字染色的效果几乎是标配。但很多人第一次尝试时，会掉进一个坑：用TextView配合ForegroundColorSpan逐字改色，结果发现颜色是硬切的，字与字之间没有过渡，看起来像被刀切过一样生硬。这个项目做的事情很纯粹——用LinearGradient配合Shader给TextView的文字做渐变着色，让歌词从暗到亮、从灰到白有一个平滑的过渡带，而不是一个字一个字地跳变。它适合两类人：一类是正在做音乐播放器、KTV 歌词页、朗读类 App 的 Android 开发者，需要快速拿到一个可用的渐变文字控件；另一类是想搞明白Paint.setShader()和LinearGradient在文字渲染上到底怎么配合的自定义 View 学习者。整个项目不依赖任何第三方库，核心就是一个继承自AppCompatTextView的自定义类，代码量不大，但把文字渐变的关键路径走通了。

2. 核心机制拆解：LinearGradient 怎么作用在文字上

2.1 从 TextView 到渐变文字：渲染链路的关键节点

Android 的TextView在onDraw里最终会调用Layout.draw()把文字画到 Canvas 上，而文字的颜色由Paint的Shader或Color决定。默认情况下Paint用的是纯色，所以文字是单色的。要让文字呈现渐变，核心操作就一步：给TextView的Paint设置一个LinearGradient类型的Shader。但这里有个容易翻车的地方——TextView内部的Paint并不是直接暴露给你的，你需要通过getPaint()拿到它，然后在合适的时机设置Shader。如果设置得太早，TextView在后续的测量或布局过程中可能会重置Paint的属性；如果设置得太晚，第一帧可能还是纯色。常见做法是在自定义 View 的onSizeChanged或onDraw里设置，确保宽高已经确定，渐变的方向和范围才能算准。

public class GradientTextView extends AppCompatTextView { private LinearGradient mLinearGradient; private int[] mColors = {0xFF888888, 0xFFFFFFFF, 0xFF888888}; private float[] mPositions = {0f, 0.5f, 1f}; public GradientTextView(Context context, AttributeSet attrs) { super(context, attrs); } @Override protected void onSizeChanged(int w, int h, int oldw, int oldh) { super.onSizeChanged(w, h, oldw, oldh); // 宽度确定后创建水平方向的线性渐变 mLinearGradient = new LinearGradient( 0, 0, w, 0, mColors, mPositions, Shader.TileMode.CLAMP ); getPaint().setShader(mLinearGradient); } }

这段代码里，LinearGradient的构造函数参数决定了渐变的方向和颜色分布。前四个参数(0, 0, w, 0)表示从控件左边缘到右边缘的水平渐变，y坐标不变。mColors数组定义了颜色断点，mPositions定义了每个颜色在渐变线上的位置比例，0f是最左，1f是最右。Shader.TileMode.CLAMP表示超出渐变范围的部分用边缘颜色填充。把Shader设置到getPaint()之后，TextView绘制文字时就会用这个渐变来着色，而不是纯色。

2.2 颜色断点与位置参数：让渐变带落在你想要的地方

很多人第一次调渐变文字，会发现渐变带太宽或者太窄，亮部没有落在当前播放的那句歌词上。问题出在mPositions和mColors的配合上。mPositions数组的长度必须和mColors一致，而且值必须从 0 到 1 递增。如果你想要一个“中间亮、两边暗”的效果，就用三个颜色断点：暗色、亮色、暗色，位置分别是 0、0.5、1。如果你想要一个更窄的亮带，可以把中间亮色的位置范围压缩，比如用五个断点：{0f, 0.4f, 0.5f, 0.6f, 1f}，颜色是{暗, 暗, 亮, 暗, 暗}，这样亮带只占中间 20% 的宽度。

// 窄亮带配置：亮部只占中间 20% private int[] mColors = {0xFF666666, 0xFF666666, 0xFFFFFFFF, 0xFF666666, 0xFF666666}; private float[] mPositions = {0f, 0.4f, 0.5f, 0.6f, 1f}; // 在 onSizeChanged 中重新创建 mLinearGradient = new LinearGradient(0, 0, w, 0, mColors, mPositions, Shader.TileMode.CLAMP); getPaint().setShader(mLinearGradient);

参数说明：mColors里每个值都是 ARGB 格式的 int，0xFF666666表示不透明的深灰色，0xFFFFFFFF是白色。mPositions里的浮点数必须是递增的，否则LinearGradient会抛IllegalArgumentException。实际做歌词效果时，这个亮带的位置需要根据当前播放进度动态移动，而不是固定在中间。移动的方式是改变LinearGradient的起始和结束 x 坐标，或者用Matrix对Shader做平移。常见做法是给自定义 View 加一个setProgress(float progress)方法，在内部根据进度重新计算渐变起点，然后调用invalidate()触发重绘。

2.3 动态移动渐变带：让高亮跟着播放进度走

静态的渐变文字只能算半成品，歌词效果的核心是亮带要跟着时间轴移动。实现思路不复杂：把LinearGradient的起点和终点从(0, 0, w, 0)改成(offset, 0, offset + w, 0)，其中offset是一个负值，随着进度从-w变到0，亮带就从左扫到右。但这里有个性能注意点：每次进度变化都重新new LinearGradient会产生大量临时对象，在快速刷新时容易触发 GC 抖动。更好的做法是用一个Matrix对象对已有的Shader做平移，避免重复创建。

private Matrix mMatrix = new Matrix(); private float mProgress = 0f; // 0 到 1 public void setProgress(float progress) { mProgress = progress; // 平移量：从 -width 到 0 float translate = -getWidth() * (1 - progress); mMatrix.setTranslate(translate, 0); if (mLinearGradient != null) { mLinearGradient.setLocalMatrix(mMatrix); invalidate(); } }

逻辑说明：setLocalMatrix会把变换矩阵应用到Shader的坐标系上，translate为负值时渐变整体左移，视觉上就是亮带从左向右扫过。invalidate()触发onDraw重绘，TextView会用更新后的Shader重新绘制文字。参数progress的范围是 0 到 1，对应播放进度从 0% 到 100%。实际接入播放器时，可以在onProgressChanged回调里调用setProgress(currentTime / duration)，刷新频率建议控制在 30 到 60 毫秒一次，太频繁没有视觉收益，反而增加主线程负担。

3. 工程结构与运行步骤：从源码到可运行 Demo

3.1 目录结构与关键文件说明

这个项目的结构是典型的 Android 单模块工程，没有复杂的多模块拆分。核心代码集中在一个自定义 View 类里，Demo 页面负责展示效果和模拟进度变化。下面是一个常见的目录组织方式，如果你拿到的源码结构略有不同，按这个思路对照即可。

app/src/main/java/com/example/gradienttextview/ ├── GradientTextView.java // 自定义渐变文字控件 ├── MainActivity.java // Demo 入口，模拟歌词播放 └── LyricAdapter.java // 可选：列表适配器，用于多行歌词 app/src/main/res/layout/ ├── activity_main.xml // 主布局，放置 GradientTextView └── item_lyric.xml // 可选：单行歌词布局 app/src/main/res/values/ ├── colors.xml // 颜色资源 ├── strings.xml // 字符串资源 └── attrs.xml // 自定义属性（可选）

GradientTextView.java是整个项目的核心，所有渐变逻辑都在这里。MainActivity.java负责把控件跑起来，通常会用一个Handler或ValueAnimator模拟播放进度，每隔几十毫秒调用一次setProgress。attrs.xml不是必须的，但如果你想让渐变颜色和位置可以在 XML 布局里配置，就需要定义自定义属性，然后在构造函数里读取TypedArray。

3.2 在布局中使用并接入模拟进度

把自定义 View 放进布局文件时，需要用完整的类名路径。如果你在attrs.xml里定义了自定义属性，可以在这里直接配置颜色和位置；如果没有定义，就用默认值，在代码里动态设置。

<com.example.gradienttextview.GradientTextView android:id="@+id/tv_lyric" android:layout_width="match_parent" android:layout_height="wrap_content" android:text="这是一句模拟歌词，渐变高亮会从左向右扫过" android:textSize="18sp" android:gravity="center" android:padding="16dp" />

在MainActivity里，用一个ValueAnimator模拟播放进度从 0 到 1 循环变化，每次更新时调用setProgress。这样不需要真实播放器就能看到渐变扫过的效果。

public class MainActivity extends AppCompatActivity { private GradientTextView mTvLyric; private ValueAnimator mAnimator; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); mTvLyric = findViewById(R.id.tv_lyric); // 模拟 3 秒内进度从 0 到 1 mAnimator = ValueAnimator.ofFloat(0f, 1f); mAnimator.setDuration(3000); mAnimator.setRepeatCount(ValueAnimator.INFINITE); mAnimator.setRepeatMode(ValueAnimator.RESTART); mAnimator.addUpdateListener(animation -> { float progress = (float) animation.getAnimatedValue(); mTvLyric.setProgress(progress); }); mAnimator.start(); } @Override protected void onDestroy() { super.onDestroy(); if (mAnimator != null) { mAnimator.cancel(); } } }

逻辑说明：ValueAnimator.ofFloat(0f, 1f)创建一个从 0 到 1 的浮点动画，setDuration(3000)表示 3 秒走完一轮，INFINITE加RESTART让它循环播放。addUpdateListener里拿到当前动画值，传给setProgress。onDestroy里取消动画，避免 Activity 销毁后动画还在跑导致内存泄漏。这套代码可以直接复制到你的项目里做验证，确认渐变效果符合预期后再接入真实播放器的进度回调。

3.3 编译与运行环境要求

这个项目对 Android 版本的要求不高，minSdkVersion设到 21 就能覆盖绝大多数设备，LinearGradient和Shader.setLocalMatrix在 API 21 上都有。compileSdkVersion和targetSdkVersion用你本地 Android Studio 默认的即可，不需要特殊配置。Gradle 版本也没有硬性要求，用项目自带的 wrapper 就行。如果你拿到的源码里build.gradle的插件版本比较老，Android Studio 可能会提示升级，按提示操作即可，不影响核心逻辑。运行前确认一下GradientTextView的包名和布局文件里的类名路径一致，这是新手最容易犯的错误——包名对不上，布局 inflation 直接崩，报ClassNotFoundException。

4. 避坑与常见问题：渐变文字不生效的排查清单

4.1 文字还是纯色，渐变完全没出现

现象：运行后TextView显示的文字是单一颜色，没有任何渐变过渡。原因通常是Shader没有设置成功，或者设置之后被TextView内部逻辑覆盖了。排查步骤：先在onSizeChanged里加一行日志，确认mLinearGradient不为 null；再确认getPaint().setShader()确实被调用了。如果都正常，检查一下mColors数组是不是所有颜色值都一样——颜色相同的话，渐变看起来就是纯色。另外，如果你在 XML 里设置了android:textColor，某些情况下TextView会在setTextColor时重置Paint的Shader，解决办法是在setTextColor之后重新设置Shader，或者干脆不在 XML 里设textColor。

4.2 渐变方向不对，亮带是竖着的

现象：期望亮带水平扫过，实际看到的是上下方向的渐变。原因：LinearGradient的起始和结束坐标写反了。水平渐变应该是(0, 0, w, 0)，y坐标相同；垂直渐变是(0, 0, 0, h)，x坐标相同。如果你写成了(0, 0, w, h)，渐变就是斜的。解决：确认onSizeChanged里的坐标参数，水平渐变固定y1 = y2 = 0，x1 = 0，x2 = w。

4.3 进度更新时画面闪烁或卡顿

现象：调用setProgress后文字闪烁，或者滑动列表时掉帧。原因：每次setProgress都重新创建LinearGradient对象，短时间内产生大量临时对象，触发 GC。解决：用Matrix.setTranslate配合Shader.setLocalMatrix做平移，复用同一个LinearGradient实例。另外，invalidate()的调用频率也要控制，如果播放器回调每 10 毫秒来一次，可以做个节流，每 30 到 50 毫秒才真正刷新一次。

4.4 多行文字渐变错乱

现象：TextView里有多行文字时，渐变带只出现在第一行，或者每行的渐变起点不一致。原因：LinearGradient的坐标系是整个View的坐标系，不是每行文字的坐标系。多行文字共享同一个渐变，所以第二行看起来颜色和第一行对不上。解决：如果要做逐行独立的渐变，需要放弃单个TextView多行方案，改用RecyclerView或LinearLayout放多个单行GradientTextView，每行独立控制进度。这也是歌词页的常见做法——每句歌词一个 View，只有当前句才应用渐变。

4.5 在 RecyclerView 中复用时渐变状态错乱

现象：歌词列表滑动时，某些行的渐变高亮没有清除，或者高亮出现在错误的行上。原因：RecyclerView复用 ViewHolder 时，没有在onBindViewHolder里重置GradientTextView的状态。解决：在onBindViewHolder里根据当前播放位置判断，如果是当前行就setProgress，否则调用setProgress(0)或清除Shader。更稳妥的做法是给GradientTextView加一个reset()方法，把Shader设为 null 并invalidate()，确保复用时状态干净。

5. 二次开发改造：从单行渐变到完整歌词组件

5.1 把渐变控件封装成可配置的歌词 View

拿到这个项目后，最直接的改造方向是把它从一个单纯的渐变TextView升级成完整的歌词组件。我一般会做三件事：第一，把颜色断点和位置参数抽成自定义属性，在attrs.xml里定义startColor、endColor、highlightColor、highlightPosition，这样在布局里就能配置，不用改 Java 代码。第二，加一个setLyricText(String text)方法，内部先setText再重置Shader，避免文字变化后渐变范围没更新。第三，加一个setHighlightWidth(float ratio)方法，控制亮带占整个宽度的比例，默认 0.2，调用方可以根据字号和歌词长度调整。

<!-- attrs.xml --> <declare-styleable name="GradientTextView"> <attr name="startColor" format="color" /> <attr name="endColor" format="color" /> <attr name="highlightColor" format="color" /> <attr name="highlightWidth" format="float" /> </declare-styleable>

在构造函数里读取这些属性，替换掉硬编码的mColors和mPositions。这样改造之后，同一个控件可以在不同页面用不同配色，不需要复制多个类。

5.2 接入真实播放器进度：从模拟到实战

模拟动画跑通之后，下一步是接入真实播放器的进度回调。大多数播放器 SDK 都会提供onProgressChanged(int currentMs, int durationMs)这样的回调。你需要在回调里算出progress = currentMs / (float) durationMs，然后调用setProgress。但这里有个细节：歌词的进度不是整首歌的进度，而是当前句歌词在它自己的时间区间内的进度。所以你需要先根据当前播放时间找到对应的歌词行，算出这句歌词的startTime和endTime，再用(currentMs - startTime) / (float)(endTime - startTime)得到句内进度。这个计算逻辑建议放在LyricAdapter或LyricManager里，GradientTextView只负责接收 0 到 1 的进度值，保持控件本身的纯粹性。

5.3 性能验证与效果对比

改造完成后，怎么验证效果？我一般会做两个测试。第一个是滑动测试：在RecyclerView里放 50 条以上歌词，快速滑动，看有没有明显的掉帧或渐变残留。第二个是长时间运行测试：让模拟进度循环跑 10 分钟以上，观察内存占用是否稳定，有没有因为Matrix或Shader对象持续创建导致的内存增长。如果发现内存曲线持续上升，检查一下setProgress里有没有意外的对象分配。一个合格的实现，在 10 分钟循环后内存应该是一条平稳的线，不会持续爬升。

5.4 一个容易忽略的细节：文字测量与渐变范围

最后说一个我踩过的坑。GradientTextView的渐变范围是基于View的宽度算的，但文字实际占用的宽度可能小于View宽度，尤其是gravity="center"的时候。这会导致渐变带有一部分落在空白区域，视觉上亮带扫过文字的速度和预期不一致。解决办法是用getLayout().getLineWidth(0)拿到第一行文字的实际宽度，用这个宽度来创建LinearGradient，而不是用getWidth()。如果文字是居中的，还需要算出文字左边缘的偏移量，把渐变的起点对齐到文字左边缘。这个细节在单行短歌词上不明显，但歌词长度变化大时就会暴露出来。

从那以后我每次做自定义文字控件，都会先确认测量宽度和绘制宽度的差异，再决定渐变坐标系怎么建。希望帮到你。

本文还有配套的精品资源，点击获取