Lottie-Android 文本范围选择器实战：索引与百分比两种模式怎么选，字符级文本动画怎么做

【免费下载链接】lottie-androidRender After Effects animations natively on Android and iOS, Web, and React Native项目地址: https://gitcode.com/gh_mirrors/lo/lottie-android

在 Lottie-Android 里做文本动画，绕不开一个组件：文本范围选择器（Text Range Selector）。它让一段文字里的任意子集可以单独拥有动画——昵称逐字变亮、标题前 30% 渐入、点赞数字按位滚动，靠的都是它。这个功能从 6.5.0 版本开始提供，本文基于仓库源码与测试素材，讲清它的原理、两种选择模式的取舍、一个完整效果的实现路径，以及容易踩的坑。

🧩 文本范围选择器如何切分一段文字

Lottie 渲染的是动画合成，文本以 Text Layer 的形式存在于 JSON 里。选择器描述"哪些字符受某个动画器影响"。源码中的 AnimatableTextRangeSelector 只有三个核心字段：

• start/end/offset：三个可动画的整数，共同圈出作用区间；
• units：取值来自 TextRangeUnits 枚举，即 INDEX（索引）或 PERCENT（百分比）。

TextLayer 在创建时把这三个字段注册成关键帧动画，所以区间本身可以随时间变化——选择"前 N 个字符"这件事本身就能动起来，这正是逐字渐显类效果的来源。区间外的字符不受影响，这也是"范围"二字的含义。

📏 索引模式与百分比模式怎么选

两种units的差异决定了一个实际取舍：

• INDEX（索引模式）：start/end是字符序号。文案固定时最精确，想点亮"第 2 到第 5 个字"就直接写死。局限是它不认识内容语义：文本一变，序号就错位；含 emoji、组合字符、零宽连接符时，计数也可能和肉眼数出来的不一样。
• PERCENT（百分比模式）：取值 0–100，按文本长度折算。内容动态变化时选择比例保持相对稳定，适合用户名、价格、状态语这类会变的文本。代价是"第几个字符"不再是精确值，长文本下粒度偏粗。

经验法则：文案写死进 JSON、追求逐字精确，用索引；内容运行时常换，用百分比。拿不准时，先用百分比验证视觉节奏，再决定要不要切回索引微调。

✍️ 用范围选择器做出一个逐字亮起的标题

仓库里自带一个可直接参考的合成：text_range_test.json，内容是一行 "Paris, France" 的逐字动画（60fps、900x325）。它的工作方式：

1. 在 After Effects 里用 Text Animator 给文本层加动画属性，再挂 Range Selector 并给关键帧；
2. 导出 JSON 后，动画器字段tr（字符计数阈值）随时间推进，渲染时每帧计算落在区间内的字符并应用效果，宏观上就呈现出逐字变化；
3. 在 Android 侧用一个 LottieAnimationView 加载该 JSON 即可播放，仓库 GIF 区有一段对应的打字效果演示：

如果要让内容运行时可变，配合setText系列 API（Compose 端是 TextDelegate）替换文本内容，选择器作用在同一层上继续生效。

⚡ 坑、性能与边界

• 版本门槛：选择器是 6.5.0 才加入的"initial support"，见 CHANGELOG.md 中 "Add initial support for text range selectors" 条目。低于该版本的项目升级前，先用其他方案或接受回退。
• 字符计数不直观：INDEX 模式下，emoji 和组合字符会改变实际计数。仓库的快照测试 TextTestCase 覆盖了中文、emoji、ZWJ 序列等边界输入，改动渲染逻辑前可以照着它验证。
• 别把区间动画当高频手段：start/end/offset都是关键帧动画，频繁修改会导致文本层反复重排重绘；优先用一条合理的缓动曲线，而不是给每个字符单独排动画。
• 长文本与加载：文本层越重，布局与光栅化开销越大；常用动画可先用 LottieCompositionFactory 预加载，把解析成本移出首帧。
• 选择器之外是另一套能力：整段变色、逐字发光这类全局文本属性走的是AnimatableTextProperties，范围选择器只负责"选哪些字符"。两者配合使用，不要混为一谈。

📦 仓库里的资源清单

• CHANGELOG.md：6.5.0 条目记录了该功能的引入，可作版本核对依据。
• snapshot-tests/src/main/assets/Tests/：text_range_test.json、text_range_test_2.json、text_range_test_glyphs.json三个范围选择器样本，外加Text.json、DynamicText.json、TextBaseline.json等文本动画素材，是调参时最快的对照物。
• snapshot-tests/src/androidTest/java/com/airbnb/lottie/snapshots/tests/TextTestCase.kt：文本渲染与动态文本的快照测试入口。
• gifs/：README 的演示素材，文字在真实界面中的效果示例如下（首帧展示的是文字标题动画的静态帧）：

• sample/：可运行的演示 App，文本相关的资源与布局在sample/src/main/res与sample/assets下。

小结：范围选择器解决的是"选中哪几个字符"，动画器解决的是"对这些字符做什么"；INDEX 管精确、PERCENT 管自适应，先用 6.5.0 以上的版本加载一个text_range_test.json跑通播放，再按内容是否动态来决定单位，基本就能覆盖多数文本动画场景。

【免费下载链接】lottie-androidRender After Effects animations natively on Android and iOS, Web, and React Native项目地址: https://gitcode.com/gh_mirrors/lo/lottie-android