Three.js 动画系统核心 API

AnimationMixer — 混合器（播放动画的“播音器”）

功能简介：为某个根对象（rootObject）播放管理动画动作（AnimationAction）。一个场景里多个独立对象可分别使用各自的 AnimationMixer。

主要属性（简述）

• mixer.time：混合器的全局时间（秒），从创建时的 0 开始。
• mixer.timeScale：时间缩放（倍速）。把它设为 0 可以临时“暂停”这个 mixer 控制的所有动作。

常用方法（每个带示例）

• new THREE.AnimationMixer(rootObject) — 构造函数

• mixer.clipAction( clipOrName, optionalRoot ) — 创建/返回一个 AnimationAction（缓存机制）

(注意：通常用 mixer.clipAction 来拿 action，不直接 new AnimationAction。)

• mixer.existingAction( clipOrName, optionalRoot ) — 如果已经有缓存的 action，返回它，否则返回 undefined

• mixer.update( deltaSeconds ) — 推进混合器时间（必须在渲染循环里调用）

（这是最常用的一行。）

• mixer.setTime( timeInSeconds ) — 跳到指定的全局时间点（定位）

• mixer.stopAllAction() — 立即停止该 mixer 下的所有 action

• mixer.uncacheClip( clip ) / mixer.uncacheAction( clip, root ) / mixer.uncacheRoot( root ) — 清理内部缓存（释放资源）

（通常在销毁模型或需要回收内存时调用。）

AnimationAction — 动作（单个动画片段的“播放单元”）

功能简介：由 AnimationMixer.clipAction() 创建，表示播放某个 AnimationClip 的实例，包含混入、权重、时序控制等。多数方法可链式调用。

重要属性（说明 + 示例）

• action.blendMode：设置混合模式，取值 THREE.NormalAnimationBlendMode（默认）或 THREE.AdditiveAnimationBlendMode。

• action.clampWhenFinished：布尔。为 true 时到最后帧会停在最后一帧（clamp）；默认 false（到末尾会 disable 或按 loop 行为处理）。

• action.enabled：布尔。设为 false 时该 action 对结果无影响（但不会重置 time）。

• action.loop / action.repetitions：循环模式与重复次数，可用常量 THREE.LoopOnce、THREE.LoopRepeat、THREE.LoopPingPong 配合 setLoop() 设置。

• action.paused：布尔。为 true 会把 effective time scale 设为 0，暂停。

• action.time：本地（action）时间（秒），可以读写用于跳帧/定位。

• action.getEffectiveTimeScale() / action.getEffectiveWeight()：返回当前（考虑 warps/fades/paused/enabled）对动画实际生效的 timeScale/weight。示例：

关键方法（说明 + 示例）

这里只列最常用/关键的方法并给示例；其它可在 docs 里查阅。

• action.play() / action.stop() / action.reset()

• action.setLoop(loopMode, repetitions) — 设置循环模式与重复次数

• action.setDuration(seconds) — 强制设定单次循环时长（会修改 timeScale）

• action.setEffectiveTimeScale(ts) / action.setEffectiveWeight(w) — 直接设置生效的时间缩放/权重（并停止计划中的 warping/fading）

• 淡入/淡出/交叉：fadeIn(duration)、fadeOut(duration)、crossFadeTo(otherAction, duration, warp)

• startAt( mixer.time + delta ) — 延迟开始（常配合 play）

• stopFading() / stopWarping() — 取消计划中的 fade / warp

• syncWith(otherAction)、warp(startTS, endTS, duration)、halt(duration)

• 状态检查：isRunning() / isScheduled()

• 获取关联对象：getClip() / getMixer() / getRoot()

• 事件（在 mixer 上监听）：mixer.addEventListener('finished'|'loop', callback)（事件对象里通常带 action）

（建议多用 fadeIn/crossFadeTo 做平滑切换；syncWith 用于立即对齐时间/速率。）

AnimationClip — 动画片段（keyframe track 的集合）

功能简介：可重用的一组 KeyframeTrack，代表一个具体动画（如 “walk”）。可从 JSON 解析或通过工具函数创建。

构造与常用属性

• new THREE.AnimationClip( name, duration, tracks )
• name：字符串。
• duration：秒；传负值时会根据 tracks 自动计算。
• tracks：KeyframeTrack 数组。

const clip = new THREE.AnimationClip('wave', -1, [positionTrack, rotationTrack]);

常用方法（说明 + 示例）

• clip.clone() — 复制 clip

• clip.toJSON() / THREE.AnimationClip.parse(json) — 序列化/反序列化

• clip.optimize() / clip.resetDuration() / clip.trim() / clip.validate() — 优化/重算/裁剪/校验（常用于导入后处理）

• 静态工具：THREE.AnimationClip.findByName( clipsArray, name )

• 与 morph target 相关的创建方法（常见于面部表情等）：
• THREE.AnimationClip.CreateFromMorphTargetSequence(name, morphTargets, fps, noLoop)
• THREE.AnimationClip.CreateClipsFromMorphTargetSequences( geometry )

• AnimationUtils.subclip(originalClip, name, startFrame, endFrame, fps?)（把一个大 clip 切成子片段）通常通过 AnimationUtils 创建子 clip，然后再 mixer.clipAction(subClip) 播放。

KeyframeTrack（及其子类） — 关键帧轨道

功能简介：按时间序列保存 keyframe 的时间数组 times 和对应值数组 values，驱动对象的单个属性（比如 node.position、node.quaternion、.material.color、.morphTargetInfluences[n] 等）。轨道类型有 VectorKeyframeTrack、QuaternionKeyframeTrack、NumberKeyframeTrack、ColorKeyframeTrack、BooleanKeyframeTrack、StringKeyframeTrack 等。轨道的 name 字符串会被 PropertyBinding 用来定位目标属性。

重要属性

• track.name：用于绑定目标（形式有多种，详见 PropertyBinding.parseTrackName）。
• track.times：Float32Array 的时间点数组。
• track.values：Float32Array 或普通数组（取决 Track 类型）的值平铺数组。
• KeyframeTrack.DefaultInterpolation：默认是 THREE.InterpolateLinear（常量见下）。

常用方法与示例（构造与使用）

• Vector（位置）轨道示例：

• Quaternion（旋转）轨道示例：

• Number（单值）轨道（用来驱动 morphTargetInfluences 或材质某个数值）：

• Color、Boolean、String 轨道示例类似（使用 ColorKeyframeTrack、BooleanKeyframeTrack 等）。

轨道重要方法（示例）

• track.clone() — 复制轨道

• track.createInterpolant() — 根据 interpolation 类型创建（内部）插值器（通常不需要手动调用）
• track.getInterpolation() — 获取插值类型（THREE.InterpolateDiscrete/Linear/Smooth）
• track.getValueSize() — 每个 value 的尺寸（例如 vector=3，quaternion=4）
  示例：

（插值常量参考下一段。）

动画插值常量（用得多）

• THREE.InterpolateDiscrete、THREE.InterpolateLinear（默认）、THREE.InterpolateSmooth。

PropertyBinding — 把轨道名解析并绑定到场景属性（内部用，但也可手动操作）

功能简介：把 KeyframeTrack.name（例如 "Armature/boneName.position" 或 ".material.color" 等）解析为对场景里具体对象属性的 getter/setter，然后允许 PropertyMixer 读写该属性。常用于内部实现，但你也能用它进行自定义绑定或调试（如解析 trackName、手动 getValue/setValue）。(Three.js)

重要方法（说明 + 示例）

• PropertyBinding.parseTrackName(trackName) — 解析一个轨道名，返回解析结果（可用于调试）

• THREE.PropertyBinding.create(root, path, parsedPath) — 创建 binding（如果 root 是 AnimationObjectGroup 会创建复合 binding）

• binding.getValue(targetArray, offset) / binding.setValue(sourceArray, offset) — 读写绑定值（格式和 valueSize 对应）
• binding.bind() / binding.unbind() — 建立或解除内部 getter/setter 引用。

注意事项：PropertyBinding 对 track 名字符串有严格解析规则，如果路径写错会出现 PropertyBinding: No target node found for track: ... 的警告/错误，常见于导出/命名不一致时。

PropertyMixer — 为单个绑定维护缓冲（加权累积、应用）

功能简介：内部使用的“多通道累加器”：每个 PropertyBinding 会被一个或多个 PropertyMixer 操作（用于混合多条 action 的影响），支持普通累积与加性累积。通常内部生成，你很少需要直接 new 它，但理解它很有助于理解权重/加性动画的工作机制。

关键属性与方法（简述 + 示例）

• 构造：new THREE.PropertyMixer( binding, typeName, valueSize )

• mixer.accumulate(accuIndex, weight) / mixer.accumulateAdditive(weight) — 把 incoming buffer 累加到指定 accu。
• mixer.apply(accuIndex) — 将 buffer 中 accu 的值写回绑定（当两个 accu 不同时）。
• mixer.saveOriginalState() / mixer.restoreOriginalState() — 记住原始状态并能恢复（在做叠加动画时很有用）。

（这些 API 更偏内部实现，日常用到的少，但理解作用有助于调试 blending/additive 情况。）

AnimationUtils — 一些动画工具函数（静态工具集）

功能简介：内部与外部都能使用的工具集合，例如：把数组类型转换、从大 clip 切子 clip、把 clip 转为 additive 格式等。

常用方法与示例

• THREE.AnimationUtils.convertArray(array, type, forceClone) — 转换数组到指定类型（如 Float32Array）

const floatTimes = THREE.AnimationUtils.convertArray([0,1,2], Float32Array, false);

• THREE.AnimationUtils.getKeyframeOrder(times) / THREE.AnimationUtils.sortedArray(values, stride, order) — 用于给 times/values 排序（解析时用）
• THREE.AnimationUtils.subclip(clip, name, startFrame, endFrame, fps?) — 从已有 clip 创建子 clip（非常常用）

• THREE.AnimationUtils.makeClipAdditive(targetClip, referenceFrame?, referenceClip?, fps?) — 把 clip 转换为 additive 形式（用于叠加）

（这些工具在处理从 Blender / glTF 导出的混合大动画时非常有用。）

AnimationObjectGroup — 将多个对象视作同一动画目标组

功能简介：当不同对象需要共享相同动画状态（例如一组实例化对象），可以把它们放到 AnimationObjectGroup，然后把 group 作为 root 传给 mixer/clipAction，这样它们会共享一套绑定/状态，节省开销。注意：组内对象必须在要动画的属性上兼容。

常用方法（示例）

• new THREE.AnimationObjectGroup(obj1, obj2, ...)

• group.add(obj1, obj2...) / group.remove(obj1...) / group.uncache(obj1...)（uncache 用于释放 group 中对象相关的内部资源）

（对于大量相似对象的动画，这个 API 非常有意义。）