AnimationExtensions

概述（Overview）

AnimationExtensions 是一个针对 Unity Legacy Animation 系统 的静态扩展方法集合，位于 PFGameFramework.Library 命名空间。

主要功能包括：

• 精确控制动画帧位置（跳到起始帧 / 结束帧）
• 普通播放、加速播放、倒放
• 异步播放并等待动画完成（支持 CancellationToken 取消）
• 指定时间区间播放动画片段
• 判断动画状态、停止、重置
• 兼容 UniTask 的异步等待机制
• 少量相机动画辅助方法

适用于需要精确控制 Legacy 动画播放顺序、步骤等待、支持取消的实验/教学/交互场景。 注意：本类主要针对旧版 Animation 系统（Legacy），新项目推荐使用 Animator + Mecanim。

---

方法一览（API Index）

方法名	类型	异步	返回类型	主要功能	典型用途
SetFrame	static	否	void	将动画设置为指定时间（常用于第一帧）	重置到初始状态
SetToEndFrame	static	否	void	将动画直接跳到最后一帧	直接显示结束状态
PlayAnimation	static	否	void	立即播放指定动画片段	普通同步播放
Play (speed overload)	static	否	void	指定速度播放动画	加速/减速播放
PlayAsync	static	是	UniTask	异步播放并等待动画完成	步骤等待动画结束
PlayWithSpeedAsync	static	是	UniTask	异步播放 + 可控速度	带速度控制的等待
PlayBackAsync	static	是	UniTask	异步倒放动画	回退/撤销动画操作
PlayAniByAnimation	static	是	UniTask	从指定开始时间播放到结束时间	播放动画片段区间
PlayAnim / PlayAnim2	static	是	UniTask	带取消支持的指定区间 + 速度播放	可中断的区间动画
PlayAni (IEnumerable)	static	否	void	从多个 Animation 中播放指定名称的动画	多物体统一管理
IsPlayAni	static	否	bool	判断指定动画是否正在播放	状态检查
StopAni	static	否	void	停止并跳到动画末尾	强制结束
ReStartAni	static	否	void	重置动画到第0帧并停止	回到初始状态
AnimationStop	static	是	UniTask	等待动画停止	异步等待结束
PlayVideoToWeb	static	否	void	在网页端打开并播放 StreamingAssets 中的视频	WebGL 平台视频播放
CameraAni	static	否	void	相机从起点到终点线性插值移动（单帧调用）	简单相机过渡（需循环调用）

---

方法详情

SetFrame / SetToEndFrame

/// <summary>
/// 将动画设置为指定时间点（常用于跳到第0帧）
/// </summary>
public static void SetFrame(this Animation anim, string clipName, float length = 0)

/// <summary>
/// 将动画直接设置为最后一帧
/// </summary>
public static void SetToEndFrame(this Animation anim, string clipName)

用途：状态重置、直接显示结果、步骤跳转。

---

PlayAnimation / Play (带速度)

/// <summary>
/// 立即播放指定动画片段（同步）
/// </summary>
public static void PlayAnimation(this Animation anim, string clipName)

/// <summary>
/// 指定播放速度播放动画
/// </summary>
public static void Play(this Animation ani, string animation, int speed)

---

PlayAsync / PlayWithSpeedAsync / PlayBackAsync

/// <summary>
/// 异步播放动画并等待完成（推荐）
/// </summary>
public static async UniTask PlayAsync(this Animation anim, string clipName, CancellationToken cancellationToken)

/// <summary>
/// 异步播放 + 速度控制
/// </summary>
public static async UniTask PlayWithSpeedAsync(this Animation anim, string clipName, CancellationToken cancellationToken)

/// <summary>
/// 异步倒放动画
/// </summary>
public static async UniTask PlayBackAsync(this Animation ani, string animation, CancellationToken ctk)

特点：使用 UniTask.WaitUntil(!anim.IsPlaying(clipName)) 等待自然结束，支持取消。

---

PlayAniByAnimation / PlayAni (区间播放)

/// <summary>
/// 播放动画指定时间区间（startTime → endTime）
/// </summary>
public static async UniTask<bool> PlayAniByAnimation(this Animation ani, float startTime, float endTime, CancellationToken ctk)

/// <summary>
/// 从多个 Animation 中选择一个播放指定区间
/// </summary>
public static async UniTask<bool> PlayAni(this IEnumerable<Animation> animations, string name, float startTime, float endTime, CancellationToken ctk)

用途：精确剪辑动画片段、跳过前置/后置无关部分。

---

PlayAnim / PlayAnim2（带取消保护的区间播放）

/// <summary>
/// 播放指定区间动画，支持中途取消（WhenAny 实现）
/// </summary>
public static async UniTask<bool> PlayAnim(Animation anim, float startTime, float endTime, float speed, CancellationToken ctk)

/// <summary>
/// 播放指定区间动画，支持中途取消（每帧检查实现）
/// </summary>
public static async UniTask<bool> PlayAnim2(Animation Anim, float startTime, float endTime, float speed, CancellationToken ctk)

推荐：PlayAnim2 更稳定，取消响应更及时。

---

状态控制方法

// 判断是否正在播放
public static bool IsPlayAni(this IEnumerable<Animation> animations, string name)

// 停止并跳到末尾
public static void StopAni(this IEnumerable<Animation> animations, string name)

// 重置到第0帧并停止
public static void ReStartAni(this IEnumerable<Animation> animations, string name)

// 等待动画停止
public static UniTask AnimationStop(this Animation animation, CancellationToken ctk)

---

其他实用方法

/// <summary>
/// 在 WebGL 中打开 StreamingAssets 里的 mp4 视频
/// </summary>
public static void PlayVideoToWeb(string fileName)

/// <summary>
/// 简易相机位置+旋转插值（需在 Update 中持续调用）
/// </summary>
public static void CameraAni(Transform startCamera, Transform endCamera)

---