1. 为什么一个动画库的API值得单独拎出来聊
做Unity客户端开发的人，几乎都绕不开补间动画这件事。UI弹窗要缩放、按钮要回弹、血条要平滑过渡、道具要飘动、相机要跟随，这些需求如果全部手写协程或者Update里插值，代码很快就会变成一锅粥。LeanTween就是在这个场景下被大量使用的轻量级补间动画库，它的定位很明确：用极少的代码量，把"从A状态平滑过渡到B状态"这件事做到极致。
我最早接触它是因为一个卡牌类项目，UI动效需求密集到离谱，用原生协程写缩放加淡入加位移的组合动画，一个弹窗就要写几十行，改一个缓动曲线要翻半天代码。换成LeanTween之后，同样的效果三五行就搞定，而且链式调用读起来非常直观。但问题也随之而来——它的API数量不少，命名风格又高度相似，move、moveLocal、moveSpline、value、alpha、scale、rotate，加上各种setEase、setDelay、setLoop、setOnComplete，新手很容易在"我到底该用哪个"这个问题上卡住。
这篇内容就是把我这几年在项目里反复用到的LeanTween常用API做一次系统梳理。不是照搬官方文档的罗列，而是按"实际开发中你会遇到什么需求"来组织，把每个API的适用场景、参数含义、容易踩的坑讲清楚。适合已经上手Unity、正在做UI动效或者游戏表现层开发的人参考，也适合刚接触LeanTween、被它那一长串方法名搞晕的人当作速查手册。
需要说明的是，LeanTween的版本迭代中部分API有过调整，下面讲的内容以当前主流稳定版本的常见用法为准，如果你用的是很老的版本，个别方法名可能有差异，以实际工程里的智能提示为准。
2. 位移类API：move、moveLocal与moveSpline的取舍
位移是补间动画里用得最多的操作，LeanTween围绕位移提供了好几个方法，名字看着像，实际行为差别不小。选错了轻则动画方向不对，重则物体直接飞到屏幕外，所以这块必须先讲透。
2.1 move与moveLocal：世界坐标和本地坐标的分水岭
LeanTween.move(gameObject, targetPosition, duration)是最基础的一个，它操作的是物体的世界坐标。也就是说，不管这个物体挂在哪个父节点下、父节点有没有旋转缩放，它最终都会移动到你把targetPosition填进去的那个世界位置。
LeanTween.moveLocal(gameObject, targetLocalPosition, duration)操作的是本地坐标，也就是相对于父节点的位置。这个区别在UI开发里尤其关键。UGUI的节点都是嵌套的，一个按钮可能挂在三层父节点下面，如果你用move去设置一个世界坐标，父节点一移动，按钮的实际表现就会和你预期的不一样；而用moveLocal，你填的就是它在父节点坐标系里的位置，父节点怎么动，它跟着动，逻辑更符合UI布局的直觉。
我踩过的一个典型坑：做一个列表项滑入效果，用move设置了目标世界坐标，结果列表容器本身有个滚动偏移，滑入的终点全歪了。改成moveLocal之后，直接按本地坐标算，问题当场消失。所以我的经验是——UI节点优先用moveLocal，3D场景里的独立物体用move，除非你明确知道自己要的就是世界坐标。
这两个方法都支持传入Vector3作为目标位置，也支持传入一个返回Vector3的委托，后者适合目标位置在动画开始前才能确定的场景。duration是动画时长，单位秒。
2.2 moveSpline：让物体沿着路径走
LeanTween.moveSpline是位移API里比较特别的一个，它让物体沿着一条样条曲线移动，而不是直线。用法上你需要传入一组路径点：
Vector3[] path = new Vector3[] { p0, p1, p2, p3 }; LeanTween.moveSpline(gameObject, path, 2.0f);它内部会用Catmull-Rom样条把这些点连成平滑曲线。这个API在做巡逻路线、飞行轨迹、抛物线效果时特别好用。但有几个细节要注意：
第一，路径点的数量。至少需要两个点才能构成一条路径，但如果只有两个点，它退化成直线，和move没区别。想要曲线效果，至少给三个点。
第二，路径点的坐标系。moveSpline默认也是基于世界坐标的，如果你的物体在移动的父节点下，路径点要按世界坐标来算，否则轨迹会偏。
第三，性能。样条计算比直线插值开销大，如果同时有几十上百个物体在跑样条，移动端要留意帧率。我一般会把同屏样条动画的数量控制在合理范围，或者用对象池复用。
还有一个容易忽略的点：moveSpline的路径点数组在动画开始后如果被修改，动画不会实时反映变化，因为它在启动时就把路径数据缓存了。要动态改路径，得先取消再重新调用。
2.3 位移API的参数补充与常见误区
位移类方法除了基本的位置和时长，还经常配合setEase使用。默认的缓动是LeanTweenType.linear，也就是匀速，但实际项目里匀速运动看起来最"假"，UI动效一般会用easeOutQuad、easeOutBack这类先快后慢或者带一点回弹的曲线。
一个常见误区是认为duration越小动画越"流畅"。实际上duration决定的是动画总时长，流畅度取决于帧率，两者不是一回事。duration设得太小（比如0.05秒），动画会一闪而过，用户根本看不清；设得太大又显得拖沓。UI动效的经验值是0.15到0.4秒之间，具体看元素大小和动效类型。
另外，move系列方法返回的是一个LTDescr对象，你可以链式调用各种配置方法。这个返回值一定要接住，后面取消动画、设置回调都靠它。很多人写完LeanTween.move(...)就不管了，结果想中途停止的时候找不到句柄，只能暴力销毁物体，这就很被动。
3. 缩放、旋转与透明度：表现层三件套
位移之外，UI和物体表现最常用的就是缩放、旋转和透明度变化。这三个操作在LeanTween里各有对应的API，用法上有共性也有各自的坑。
3.1 scale与scaleX/Y/Z：整体缩放和单轴缩放
LeanTween.scale(gameObject, targetScale, duration)做的是整体缩放，传入一个Vector3表示目标缩放值。比如从Vector3.one缩到Vector3.zero就是缩小消失，反过来就是弹出。
如果只想改某一个轴的缩放，可以用scaleX、scaleY、scaleZ，它们接受一个float值。做血条的时候我经常用scaleX，因为血条通常只横向变化，纵向保持不变，用整体scale会把高度也改了，还得额外补偿，不如直接单轴操作干净。
这里有个UGUI特有的坑：RectTransform的scale和localScale。LeanTween的scale操作的是Transform的localScale，对于UGUI节点来说就是RectTransform的localScale。如果你在代码里同时用anchoredPosition或者sizeDelta去改布局，又用scale做动画，两者会叠加，视觉效果可能超出预期。我的做法是动画归动画、布局归布局，尽量不混着改同一个属性。
还有一个细节：缩放动画的起点是物体当前的localScale，不是固定的1。如果你想要"从0弹到1"的效果，得先把localScale设成0再调用scale，或者用setFrom指定起始值。setFrom这个配置方法很实用，它能让动画从一个指定值开始，而不是从当前值开始，省去了手动初始化的步骤。
3.2 rotate与rotateLocal：旋转的方向问题
LeanTween.rotate(gameObject, targetEulerAngles, duration)传入的是欧拉角，做的是世界空间的旋转。rotateLocal则是本地空间旋转。和位移一样，UI节点优先考虑rotateLocal。
旋转最容易出问题的地方是角度插值的路径。比如从350度转到10度，直觉上应该转20度，但如果不做处理，它可能会反向转340度，看起来就是物体绕了一大圈。LeanTween内部对欧拉角插值做了一定处理，但在角度跨越0/360边界时仍然可能出意外。我的经验是，做旋转动画时尽量把角度控制在合理范围内，或者用四元数的方式思考，避免大角度跨越。
另外，rotate还有一个重载是绕某个轴旋转指定角度，比如LeanTween.rotateAround(gameObject, axis, degrees, duration)，这个在做转盘、指针、齿轮效果时很好用，它明确指定了旋转轴，比直接给欧拉角更可控。
3.3 alpha与canvasGroup：淡入淡出的两种做法
透明度动画有两个层面。如果对象是普通的SpriteRenderer或者有Material的物体，用LeanTween.alpha(gameObject, targetAlpha, duration)，它改的是渲染器的颜色alpha。如果是UGUI节点，更推荐用LeanTween.alphaCanvas(canvasGroup, targetAlpha, duration)，操作的是CanvasGroup组件的alpha。
为什么UI推荐用CanvasGroup？因为直接改Image或者Text的color alpha，只影响单个组件，一个弹窗里有十几个子元素的话，你得逐个改，而且半透明叠加时容易出现颜色不均。CanvasGroup的alpha是作用于整个组的，一次设置，组内所有元素统一变化，而且还能配合blocksRaycasts和interactable控制交互，做弹窗淡入淡出时非常顺手。
用CanvasGroup还有一个好处：它不会触发UI的网格重建。改单个Graphic的color会触发重建，频繁改的话有性能开销；CanvasGroup的alpha变化是渲染层面的，开销小得多。做频繁的淡入淡出，这一点很关键。
alpha和alphaCanvas的targetAlpha都是0到1的float。注意alpha动画结束后，如果alpha是0，物体虽然看不见但还在场景里，射线检测可能还会命中。做弹窗关闭时，记得在setOnComplete里把物体SetActive(false)，或者把CanvasGroup的blocksRaycasts关掉。
4. 通用配置方法：让动画真正听话
前面讲的都是"做什么动画"，这一节讲"怎么控制动画"。LeanTween的配置方法都挂在LTDescr上，通过链式调用设置，它们决定了动画的节奏、循环、回调和生命周期。这部分是区分"能用"和"用好"的关键。
4.1 setEase：缓动曲线决定动画的"手感"
setEase(LeanTweenType easeType)是使用频率最高的配置方法。缓动曲线决定了动画在时间轴上的速度分布，同样的位移和时长，换一条曲线，观感完全不同。
LeanTween内置了相当丰富的缓动类型，常用的几类：
- 线性类：
linear，匀速，机械感强，一般只用于需要严格匀速的场景。 - 二次缓动：
easeInQuad、easeOutQuad、easeInOutQuad，最常用的通用曲线，easeOutQuad适合入场，easeInQuad适合退场。 - 三次缓动：
easeInCubic、easeOutCubic、easeInOutCubic，比二次更"猛"，适合需要明显加速感的场景。 - 回弹类：
easeOutBack、easeInBack，带一点超出再回弹的效果，做按钮点击、弹窗弹出特别有活力。 - 弹性类：
easeOutElastic、easeOutBounce，弹性十足，适合强调性的动效，但用多了会显得浮夸。
选曲线的经验：入场动画用easeOut系列（先快后慢，符合物体减速停下的直觉），退场动画用easeIn系列（先慢后快，符合加速离开的直觉），需要强调的用back或elastic，需要平稳的用quad或cubic的inOut。
除了预设类型，setEase还支持传入AnimationCurve，这给了你完全自定义的能力。项目里如果有统一的设计规范，可以把曲线做成配置，所有动画从配置读取，保证风格一致。
4.2 setDelay、setLoop与setRepeat：时间控制
setDelay(float delay)让动画延迟指定秒数后开始。做序列动画时，给不同元素设置递增的delay，就能做出错落有致的入场效果，比手动写协程等待优雅得多。
setLoop(int count)设置循环次数，setLoopClamp是循环到指定次数后停止，setLoopPingPong是来回循环（正放一遍反放一遍）。做呼吸灯、心跳、待机浮动这类循环动效时，setLoopPingPong特别合适，因为它自动处理了往返，不用你手动写两段动画。
setRepeat(int count)是重复播放，和loop的区别在于repeat是每次从头开始，loop在pingpong模式下会反向。实际用的时候，循环动画记得给一个合理的次数或者用setLoopClamp配合条件判断，否则无限循环的动画在物体销毁时如果没取消，可能引发空引用。
4.3 setOnComplete、setOnStart与setOnUpdate：回调的时机
setOnComplete(System.Action callback)在动画结束时调用，这是最常用的回调。做序列动画时，前一段的onComplete里启动下一段，就能串起复杂的动画流程。
setOnStart在动画开始时调用，适合做动画前的准备工作，比如激活物体、初始化状态。
setOnUpdate(System.Action<float> callback)每帧调用，参数是0到1的进度值。这个在需要根据动画进度同步其他属性时很有用，比如动画移动的同时更新一个进度条，或者根据进度播放音效。
回调里最容易踩的坑是闭包捕获变量。在循环里给多个物体设置onComplete，如果回调里用了循环变量，由于闭包的特性，所有回调看到的可能是同一个最终值。解决办法是在循环内用一个局部变量拷贝当前值，或者用参数化的方式传递。这个坑和LeanTween本身无关，是C#闭包的通用问题，但在批量设置动画回调时特别容易中招。
4.4 setIgnoreTimeScale：暂停时的动画处理
setIgnoreTimeScale(bool ignore)决定动画是否受Time.timeScale影响。游戏暂停时，timeScale设为0，普通动画会停住，但如果你希望某些UI动画（比如暂停菜单的弹出）在暂停状态下仍然播放，就要设setIgnoreTimeScale(true)。
这个配置在做暂停功能时是刚需。我见过不少项目暂停后菜单弹不出来，就是因为菜单动画没忽略时间缩放，timeScale为0导致动画永远停在第一帧。反过来，游戏内的角色动画一般不应该忽略时间缩放，否则暂停时角色还在动，就穿帮了。
5. 取消、暂停与生命周期管理
动画写出来容易，管好难。一个场景里同时跑几十个动画，切换界面时如果不清理，轻则动画错乱，重则内存泄漏和空引用。这一节讲LeanTween的生命周期管理。
5.1 cancel与cancelAll：精准和粗暴的两种清理
每个动画方法返回的LTDescr对象上都有cancel()方法，调用它就能取消这一个动画。这是精准清理，适合你知道要停哪个动画的场景。
LeanTween.cancel(gameObject)取消某个物体上的所有动画，LeanTween.cancelAll()取消场景里所有LeanTween动画。切换界面时，我通常会在界面的OnDestroy或者关闭逻辑里调用LeanTween.cancel(gameObject)，把这个界面相关的动画全部清掉，避免残留的动画在物体销毁后还在跑，导致空引用报错。
这里有个非常关键的坑：动画的目标物体被销毁后，动画不会自动停止。LeanTween内部持有物体的引用，如果物体Destroy了但动画还在跑，下一帧访问Transform就会抛异常。所以销毁物体前，务必先cancel它身上的动画。我一般的做法是封装一个扩展方法，在销毁前统一清理，养成习惯。
5.2 pause与resume：临时挂起动画
LeanTween.pause(gameObject)暂停物体上的动画，LeanTween.resume(gameObject)恢复。和cancel不同，pause保留了动画状态，恢复后从暂停处继续。
这个在做"打开背包时暂停场景动画"这类需求时有用。但要注意，pause和timeScale是两套机制，pause是LeanTween层面的，timeScale是引擎层面的，两者可以叠加。如果timeScale为0，即使resume了动画也不会动。
5.3 动画ID与批量管理
LeanTween支持给动画设置唯一ID：LeanTween.move(...).setId(myId)，之后可以用LeanTween.cancel(myId)按ID取消。这在需要按逻辑分组管理动画时很有用，比如所有属于某个角色的动画共用一个ID前缀，角色离场时一次性取消。
不过ID是int类型，要自己保证唯一性，用不好反而容易冲突。我的建议是，简单的场景用物体引用取消就够了，只有在确实需要跨物体分组管理时才用ID，并且做好ID的分配规划。
6. 实战中那些文档不会告诉你的细节
前面按API类别讲了一遍，这一节专门讲实战经验，都是踩过坑之后总结出来的，文档里基本不会写。
6.1 动画叠加与属性冲突
同一个物体上同时跑两个改同一属性的动画，结果是不确定的。比如一个move动画还没结束，你又启动一个move，两个动画会互相抢控制权，物体可能抖动或者瞬移。解决办法是要么先cancel再启动新的，要么用setOnComplete串行执行。
改不同属性的动画可以并行，比如一边move一边alpha，这没问题。但要注意，如果两个动画都用了setEase且曲线不同，视觉上可能不协调，最好统一风格。
6.2 对象池与动画的配合
用对象池复用物体时，从池里取出的物体可能还残留着上次的动画状态。比如上次是缩小到0消失的，这次取出来scale还是0，直接显示就看不见了。所以从池里取出时，要么先cancel所有动画并重置Transform，要么在动画开始时用setFrom明确指定起始值。我倾向于在对象池的取出回调里统一重置，这样最保险。
6.3 移动端的性能考量
LeanTween本身很轻量，但动画数量多了照样吃性能。移动端上，同屏活跃动画建议控制在一定数量内，尤其是样条动画和带回调的复杂动画。另外，频繁创建和销毁LTDescr对象会产生GC压力，能复用动画配置的尽量复用，或者用对象池管理动画目标。
还有一个细节：UI动画尽量用CanvasGroup而不是逐个改Graphic的color，前面提过，这里再强调一次，因为它对性能的影响在移动端很明显。
6.4 编辑器里预览动画
LeanTween的动画在编辑器非运行状态下不会播放，调试时只能运行起来看。如果要做精细调整，可以写一个简单的编辑器脚本，在OnValidate或者自定义按钮里触发一次动画预览。这个投入在动效密集的项目里很值得，能省下大量反复运行的时间。
6.5 版本差异与API兼容
LeanTween不同版本之间，个别API的名字和行为有变化。比如早期版本某些方法的参数顺序和现在不同，升级时要注意。我的做法是，项目锁定一个稳定版本后不轻易升级，升级前先在测试工程里跑一遍所有用到的API，确认行为一致再合并。工程里如果用了反射或者字符串调用LeanTween方法，升级时更要小心。
7. 一套可复用的动画封装思路
讲了这么多API，最后分享一个我在项目里常用的封装思路，把常用动效做成语义化的方法，业务代码调用时不用关心底层是move还是scale。
核心思路是建一个静态工具类，把"弹窗弹出""弹窗关闭""按钮点击反馈""列表项入场"这些高频动效封装成方法，内部用LeanTween实现，参数只暴露时长和回调。这样业务层写起来就是一行调用，动效风格也统一。
比如弹窗弹出，内部就是CanvasGroup的alpha从0到1配合scale从0.8到1，用easeOutBack，时长0.25秒。弹窗关闭反过来，用easeInBack，时长0.2秒，onComplete里SetActive(false)。这些参数集中在一个配置类里，改风格只改一处。
封装的时候要注意，工具类方法要返回LTDescr或者一个取消句柄，让调用方能取消。另外，所有方法内部都要处理物体为null、CanvasGroup不存在等边界情况，避免业务层传错参数导致报错。
这套封装用下来，团队里新人也能快速做出风格一致的动效，不用每个人都去研究缓动曲线。当然，封装不是万能的，遇到特殊动效还是得直接调LeanTween的API，封装只是覆盖高频场景。
我个人在实际项目里的体会是，LeanTween的价值不在于它有多少API，而在于它让你能用最少的代码表达动画意图。把常用API吃透，再配合合理的封装和生命周期管理，UI动效这块基本就不会成为项目的痛点。真正要花心思的，是动效的节奏和曲线选择，那是设计层面的功夫，API只是工具。
