指南 · 08

性能与播放

Animated 如何避免每帧的工作、如何确认元素走的是哪条路径，以及首页的数据是如何测得的。

三种播放路径

Animated 按属性选择路径。API 不会因路径不同而改变。

路径	适用情况	每帧的工作
browser	`Animated.<tag>` 元素上有限的 transform 和 opacity 动效，包括弹簧	页面的 JavaScript 不做任何工作
css	浏览器可以用共享 CSS 关键帧表达的精确曲线	页面的 JavaScript 不做任何工作
js	普通 style 变量、输入、自定义计算以及 sequence 的边界	每个值写入一次，没有 React 渲染

一个值，多个元素

Hook 值的派生结果都是 calc() 表达式。使用 scope 时，每帧写入一次变量就能驱动容器中的所有元素。

正在准备示例…

JavaScript 已关闭。下面的代码就是完整的示例。

App.jsx

import { useRef } from 'react';
import { Easing, loop, timing, useAnimated } from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ count = 1600, amplitude = 16, duration = 2400 }) {
  const field = useRef(null);
  const renders = useRef(0);
  renders.current += 1;

  // Written once per frame on the field; every dot derives from it in CSS.
  const wave = useAnimated(
    0,
    (value) => {
      loop(timing(value, { toValue: 1, duration, easing: Easing.linear }));
    },
    [duration],
    { scope: field },
  );

  const columns = Math.ceil(Math.sqrt(count * 2.8));
  const dots = Array.from({ length: count }, (_, index) => index);

  return (
    <div className="stage">
      <div className="meta">
        <span>{count.toLocaleString('en-US')} dots</span>
        <span>React renders: {renders.current}</span>
      </div>
      <div className="field" ref={field} style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
        {dots.map((index) => {
          const phase = (index % columns) / columns + Math.floor(index / columns) / 18;
          return (
            <i
              key={index}
              style={{
                transform: `translateY(calc(sin((${wave} + ${phase}) * 1turn) * ${amplitude}px))`,
                opacity: `calc(0.55 + cos((${wave} + ${phase}) * 1turn) * 0.45)`,
              }}
            />
          );
        })}
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 16px;
  padding: 24px;
}

.meta {
  display: flex;
  flex-wrap: wrap;
  justify-content: space-between;
  gap: 8px;
  font:
    600 14px/1.4 ui-monospace,
    SFMono-Regular,
    Consolas,
    monospace;
  color: #1a33c7;
}

.field {
  display: grid;
  grid-auto-rows: 1fr;
  gap: 2px;
  height: 280px;
  padding: 28px 16px;
  border-radius: 16px;
  background: #0b1440;
  overflow: hidden;
}

.field i {
  display: block;
  width: 100%;
  max-width: 8px;
  aspect-ratio: 1;
  align-self: center;
  justify-self: center;
  border-radius: 50%;
  background: #5c7cff;
}

.field i:nth-child(3n) {
  background: #8fb0ff;
}

.field i:nth-child(7n) {
  background: #ffffff;
}

确认路径

inspect(element) 会在实际运行时返回每个动画属性的驱动器和回退原因。

debug.js

import { inspect } from '@kkwaenggwari/animated';

console.table(inspect(element));
// property   driver     reason
// transform  browser    null
// opacity    css        null
// --level    js         css-variable-requires-js

从第一帧开始

如果启动动效的任务让主线程一直忙碌（例如水合或一次大型提交），动效会在那项工作结束后重新开始，而不是看起来已经播到一半。在隐藏的页面中启动的动效会在后台完成。

首页的数据是如何测得的

每个场景都在全新的页面中运行：先预热一次，再记录三次样本，取中位数。JavaScript 时间是动效运行期间在动画帧回调中花费的时间。它不包括样式计算、布局和绘制——这些在任何方案中浏览器都要做——所以它不衡量总 CPU 占用或帧率。

浏览器播放并不会让布局、绘制、合成或内存变得免费。请在你支持的设备上测量真实的界面。

场景	设置	结果
400 Animated.div elements move translateX and fade in (timing, 1800 ms)	seed/pose/tempo on Animated.div; 800 browser animations	0.00 ms
One useAnimated value drives 10,000 elements in ordinary style (loop, 1200 ms)	transform and opacity as calc() of one CSS variable written on a scope element	0.13 ms

2026-09-28 · Chrome 153.0.8010.52 (headless) · Windows_NT x64 · Intel(R) Core(TM) i7-14700K