指南 · 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

從第一格開始

如果啟動動態的工作讓主執行緒一直忙碌（例如 hydration 或一次大型提交），動態會在那項工作結束後重新開始，而不是看起來已經播到一半。在隱藏的頁面中啟動的動態會在背景完成。

首頁的數據是如何測得的

每個情境都在全新的頁面中執行：先暖機一次，再記錄三次樣本，取中位數。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