告别各写各的！从 0 到 1 打造 React Native 客户端公共动效基础设施 🏗️

一、 背景痛点：为什么普通动画方案很容易翻车？

在很多团队里，动效往往处于"野生状态"： 设计师在 Figma 里定好了各种高级的弹簧阻尼和贝塞尔曲线，但到了前端落地时：

1. 参数杂乱无章 ：同学 A 写 duration: 200，同学 B 写 duration: 350，弹簧参数全凭手感调，整个 App 的动效节奏参差不齐。
2. 生命周期泄露：页面跳出或关掉后，动画定时器和监听依然在跑，控制台疯狂报警，甚至引发内存泄漏。
3. 高频点击"动画打架"：用户连续手速过快点两次按钮，前一个动画还没结束，新动画直接覆盖，界面元素在屏幕上"疯狂抽搐"。
4. 后台静默空耗：App 切到系统后台后，高频循环动效依然在持续消耗 CPU/GPU，用户手机发烫掉电。
5. 无障碍合规缺失：特殊用户在手机系统里开启了"减少动态效果（防眩晕）"，业务层 95% 的同学都会遗漏判断。

为了彻底终结"各写各的、反复踩坑"的现状，基于 React Native Reanimated 4 ，打造了一套全托管、零配置心智、复用 Motion Tokens 的客户端公共动效基础设施。

---

二、 整体架构分层设计

坚持"纯函数与 UI 渲染彻底解耦"的原则，将整套基建收敛为四层架构：

                    ┌──────────────────────────────────────────┐
  1. 业务消费层       │ useMotionValue / usePressMotion / Presets│
                    └────────────────────┬─────────────────────┘
                                         ▼
                    ┌──────────────────────────────────────────┐
  2. 生命周期与环境层 │   MotionLifecycle & Environment Binding   │
                    │   (卸载自动清理 / AppState后台休眠 / 防眩晕) │
                    └────────────────────┬─────────────────────┘
                                         ▼
                    ┌──────────────────────────────────────────┐
  3. 核心驱动引擎层   │               MotionDriver               │
                    │   (自动打断取消 / 时序调度 / 防幽灵回调)   │
                    └────────────────────┬─────────────────────┘
                                         ▼
                    ┌──────────────────────────────────────────┐
  4. 基础令牌与数学层 │     Cubic-Bezier Solver & Motion Tokens  │
                    │   (CSS曲线解耦计算 / 物理弹簧参数基线)      │
                    └────────────────────┴─────────────────────┘

---

三、 核心难点攻坚与关键代码解析

1. 动效令牌解耦：纯数学三次贝塞尔求解器

• 痛点 ：设计系统中输出的是标准 CSS 字符串（如 cubic-bezier(0.2, 0, 0, 1)），而 Reanimated 的 Easing.bezier 如果在通用工具中直接引入 react-native，会导致纯 Node 端的单测与脚本因 Flow 语法直接崩溃。
• 架构解法 ：编写零 Native 运行时耦合的纯数学三次贝塞尔求解算法，利用牛顿迭代法根据时间斜率解算物理进度，并打上 'worklet' 标记使其可在 UI 线程高性能运行：

'worklet';

export function cubicBezier(mX1: number, mY1: number, mX2: number, mY2: number): EasingFunction {
  'worklet';
  if (mX1 === mY1 && mX2 === mY2) return (t: number) => t; // 线性

  // 基于牛顿迭代法根据 X 轴时间切线反求 T，并计算 Y 轴最终进度
  return function BezierEasing(x: number): number {
    'worklet';
    if (x === 0 || x === 1) return x;
    return calcBezier(getTForX(x), mY1, mY2);
  };
}

export function parseCubicBezier(bezierStr: string): EasingFunction {
  'worklet';
  const match = bezierStr.match(/^cubic-bezier\(\s*([\d.]+)\s*,\s*([\d.-]+)\s*,\s*([\d.]+)\s*,\s*([\d.-]+)\s*\)$/);
  if (!match) return (t) => t; // 防御性兜底为线性，绝不崩溃
  const [, x1, y1, x2, y2] = match;
  return cubicBezier(parseFloat(x1), parseFloat(y1), parseFloat(x2), parseFloat(y2));
}

---

2. 核心发动机 MotionDriver：防打架与防"幽灵回调"

业务最常遇到的问题就是竞态（Race Condition）：连续两次触发动画，旧动画未取消；或者旧动画被取消后，底层在微任务里依然抛出了迟到的完成回调（幽灵回调）。

我们采用 "紧急刹车 + 代次追踪（Generation Counter）" 双重锁：

export class MotionDriver {
  private activeGenerations = new Map<AnimatableValue<number>, number>();
  private generationCounter = 0;

  public timing(target, toValue, options = {}, callback) {
    // 1. 紧急刹车：启动新动画前，安全打断前序活跃动画
    this.cancel(target);

    // 2. 无障碍降级：检测到系统防眩晕开启，时长自动归零瞬移到位
    const duration = this.resolveDuration(options.duration);
    if (duration === 0) {
      target.value = toValue;
      callback?.(true);
      return;
    }

    // 3. 代次追踪：为本次任务颁发专属代次身份证
    const generation = (this.generationCounter += 1);
    this.activeGenerations.set(target, generation);

    const wrappedCallback = (finished) => {
      // 4. 防幽灵回调：如果代次不匹配，说明是迟到的旧动画回调，直接丢弃！
      if (this.activeGenerations.get(target) !== generation) return;
      this.activeGenerations.delete(target);
      callback?.(finished);
    };

    // 5. 跨线程安全调度
    this.config.onAnimateTiming(target, toValue, duration, easing, wrappedCallback);
  }
}

---

3. 多线程安全跨桥：scheduleOnRN

在 Reanimated 4 中，动画逻辑运行在独立的 UI 线程（Worklet），但业务传入的 React 回调必须回到 JS 线程执行。 如果不做线程调度直接调用 JS 回调，真机上极易产生多线程竞态异常。

在 Hook 层，我们通过 scheduleOnRN 建立了极其安全的跨线程回调通道：

import { scheduleOnRN } from 'react-native-worklets';

const driver = useMemo(() => new MotionDriver({
  onAnimateTiming: (target, toVal, duration, easing, cb) => {
    target.value = withTiming(toVal, { duration, easing }, (finished) => {
      // 从底层的 C++/Native UI 线程安全跳回 React Native JS 线程
      if (cb) scheduleOnRN(cb, finished);
    });
  },
  onCancelAnimation: (target) => cancelAnimation(target),
}), []);

---

4. 真实环境守卫：后台休眠与系统无障碍联动

通过 bindMotionEnvironment，将组件生命周期、真实系统 AppState 与 AccessibilityInfo 动态事件全部绑定到驱动器：

export function bindMotionEnvironment({ driver, appState, accessibility }) {
  // 1. 监听系统真实无障碍防眩晕开关变动
  const sub = accessibility.addEventListener('reduceMotionChanged', (enabled) => {
    systemReduced = enabled;
    apply(); // 动态通知驱动器：后续所有动画全走 0ms 模式！
  });

  // 2. 监听前后台切换：切到 background 时自动休眠并取消活跃动画
  const lifecycle = new MotionLifecycleController({ driver, appState });

  return {
    destroy() {
      sub.remove();
      lifecycle.destroy(); // 组件卸载一网打尽，彻底清场
    }
  };
}

---

四、 封装属于团队的公共 Hooks

所有复杂的生命周期、多线程、无障碍降级被底层全包办后，留给上层调用的就是最舒服、最干净的纯逻辑 Hook：

1. useMotionValue ------ 万能动画值

适合宽度、高度、位移、旋转等任意连续数值动画：

const width = useMotionValue(100);

// 支持语义化 Token 名，卸载自动清理，防眩晕自动归零
width.to(240, { duration: 'normal' }); // 200ms
width.spring(300);                     // 物理弹簧
width.reset(100);                      // 瞬态重置

2. usePressMotion ------ 触感级微缩与弹性回弹

用于任何按钮、卡片、头像的物理点击微缩交互：

const { scale, pressProps } = usePressMotion();

<Pressable {...pressProps}>
  <Animated.View style={{ transform: [{ scale: scale.value.value }] }}>
    <Text>按住我感受物理微缩与回弹</Text>
  </Animated.View>
</Pressable>

• 效果：手指按下瞬间平滑收缩至 0.95，抬手时以自然物理弹簧（damping: 18, stiffness: 180）饱满回弹。

3. useTransitionMotion ------ 状态显隐与弹窗过渡

用于对话框、下拉菜单、浮层淡入淡出：

const { visible, motion, toggle } = useTransitionMotion();

// 入场 decelerate，退场 accelerate，快速重复点击自动平滑掉头反转
toggle();

---

五、 动效基础设施设计的 3 个通用心法

通过这次实战，我总结了 3 个在任何前端/客户端做基础设施时都适用的黄金准则，希望能给正在设计公共库的你一些启发：

1. "防御性收口"优于"开发者自觉" ： 永远不要指望每个业务同学在写完动画后都会记得去写 cancelAnimation，或者记得加上 if (isReducedMotion)。最靠谱的规范，是让别人想漏写都不可能。把脏活累活全部收口到基建内部，别人零心智使用，才能真正杜绝线上事故。
2. 环境解耦与纯函数先行： 在做核心计算（比如贝塞尔曲线、缓动推导、时序算法）时，尽量写成纯数学函数，脱离对宿主 UI 库的死锁绑定。这样不仅全端可复用，还能在纯 Node 环境下秒级跑通单元测试。
3. 多线程意识要贯穿始终 ： 在 React Native 或带有 Worker/多线程的现代框架中，UI 线程与逻辑线程是分离的。编写回调机制时，务必使用类似 scheduleOnRN 的跨线程调度工具，并用代次 ID 防御异步幽灵回调。