r3f-animation

React Three Fiber 动画

请先检查已安装的 Fiber、Drei 和 React 版本。这些示例面向 Fiber 9 / React 19。如果项目现有的动画库已能满足任务需求，请继续使用。

选择动画控制方

• 连续变换／uniform 使用 useFrame 和 refs；React 状态用于描述选中、打开或激活等离散目标。
• 对已制作动画的 GLTF 片段使用 Drei useAnimations。如需了解独立动画实例和清理，请阅读片段播放。
• 使用项目现有的弹簧／补间库协调过渡；添加前请检查其 React 对等依赖。不要仅仅为了给网格添加动画而引入状态管理器。
• 让 Rapier 管理模拟的刚体变换。通过物理 API 为运动学目标添加动画，不要用网格位置与模拟对抗。

可返回静止状态的阻尼

在 Canvas 下方挂载；这也适用于 frameloop="demand"。点击方块即可更改其目标。

import { useEffect, useRef, useState } from 'react'
import { useFrame, useThree } from '@react-three/fiber'
import { MathUtils, type Mesh } from 'three'

export default function Example() {
  const mesh = useRef<Mesh>(null)
  const [active, setActive] = useState(false)
  const invalidate = useThree((state) => state.invalidate)
  const target = active ? 1 : -1
  useEffect(() => { invalidate() }, [target, invalidate])

  useFrame((_, delta) => {
    if (!mesh.current) return
    // Cap a visual transition's resume jump, not a physics simulation step.
    const x = MathUtils.damp(mesh.current.position.x, target, 6, Math.min(delta, 0.1))
    const moving = Math.abs(x - target) > 0.001
    mesh.current.position.x = moving ? x : target
    if (moving) invalidate()
  })

  return (
    <mesh ref={mesh} name="moving-box" onClick={() => setActive((value) => !value)}>
      <boxGeometry />
      <meshStandardMaterial color={active ? 'orange' : 'coral'} />
    </mesh>
  )
}

计时与性能

• delta 的单位是秒。按 position += velocity * delta 积分速度；使用 MathUtils.damp 或 1 - exp(-lambda * delta) 进行 lerp，以实现指数平滑。固定的 lerp 系数会受刷新率影响；delta * speed 可能导致过冲。
• 重用向量／四元数；避免每帧都分配新对象。对于方向，使用四元数插值，不要在角度回绕边界上分别对 Euler 角进行 lerp。
• 只使用一个时间轴／时钟控制方。Fiber 9 仍会提供 state.clock；不要替换 Fiber 内部实现，因为 Three.js 已弃用独立创建的 Clock 实例。对于独立的 Three.js 计时，请参阅已安装版本中的 Timer。
• 使用按需渲染时，外部动画系统在运行期间需要触发失效。同步动画开始前先触发失效；如果首帧会因此产生跳变，请安排动画在下一帧开始。
• 在支持时，可在帧回调中直接读取快速变化的外部状态（例如，通过 store 的 getState()）；仅让 React 订阅与 UI 相关的变化。清理外部订阅。
• 不要声称普通的 React 重新渲染会停止动画。在进行组件记忆化之前，请先分析实际工作量和订阅频率。
• 隐藏对象不会停止其帧回调或 mixer。适当时显式暂停开销较大的动画；装饰性动画应尊重减少动态效果的偏好设置。
• 重复振荡和着色器动态效果可以根据经过的时间计算相位；需要可复现性的模拟应采用固定步长设计，而非任意限制 delta。

验证

在不同帧率下，以及后台运行／恢复和反复更改目标时，对比动画效果。使用按需渲染时，确认对象会唤醒、到达目标并停止请求帧。对于动画片段，请测试两个实例播放不同动作的情况。

来源

• Fiber hooks、性能陷阱、按需渲染。
• MathUtils.damp、Drei useAnimations。