الحركة في React DOM · واجهة Animated API من React Native

اكتب الحركة مرة واحدة. تجري بسلاسة ولا تنكسر أبدًا.

يجلب Animated مكتبة Animated من React Native إلى الويب. قيمة واحدة تحرّك أي عدد من العناصر من دون عرض React في كل إطار، والحركة المدعومة يشغّلها المتصفح نفسه، وكل مقاطعة تكمل مما على الشاشة.

ابدأ شاهد الأمثلة

التثبيت

npm install @kkwaenggwari/animated

قيمة ساعة واحدة تقود تموّج الأشكال الأربعة والستين كلها. حرّك المؤشر فوق المسرح.

مقيس على هذا الإصدار

قيس بإصدار البناء 1.0.0 في Chrome من دون واجهة على PC مكتبي. تختلف الأرقام حسب الجهاز. كيف قسنا

0.00msJavaScript لكل إطار أثناء حركة 400 عنصر
الحركة المحدودة لـ transform وopacity على عناصر Animated يشغّلها المتصفح. لا تؤدي استدعاءات الإطارات في الصفحة أي عمل.
0.13msJavaScript لكل إطار حين تقود قيمة واحدة 10,000 عنصر
تكتب القيمة متغيّر CSS واحدًا؛ ويشتق كل عنصر نمطه منه عبر CSS.
0عمليات عرض React أثناء الحركة
لا تمر القيم أبدًا عبر حالة React. تُعرض المكوّنات حين تتغيّر props الخاصة بك، لا حين يتغيّر إطار.

01 · سهل

الـ API التي تعرفها، على style العادي في React

تحتفظ timing وspring وinterpolate وloop وAnimated.event بأسماء React Native وإعداداتها. تدخل القيمة مباشرة في الخاصية style العادية، فلا يوجد مكوّن خاص تتعلمه قبل أول حركة.

انقل شيفرة React Native بإعادة تسمية Animated.View إلى Animated.div.
قيمة واحدة يمكنها تحريك شريط ومؤشر دائري وصف من البطاقات معًا، لكلٍّ منها نطاقه.
يمتلك useAnimated الوصفة: يبدأ عند التركيب، ويعيد البدء حين تتغيّر تبعية، وينظّف عند الإزالة.

جارٍ تجهيز المثال…

JavaScript معطّل. الشيفرة أدناه هي المثال الكامل.

App.jsx

import { Easing, delay, loop, sequence, spring, timing, useAnimated } from '@kkwaenggwari/animated';
import './styles.css';

const curves = {
  linear: Easing.linear,
  inOut: Easing.inOut(Easing.cubic),
  back: Easing.out(Easing.back(1.7)),
  bounce: Easing.bounce,
};

export default function App({ tempo = 'spring', duration = 900, easing = 'inOut' }) {
  // One value. The recipe restarts when a prop changes.
  const progress = useAnimated(
    0,
    (value) => {
      const go = (toValue) =>
        tempo === 'spring'
          ? spring(value, { toValue, stiffness: 120, damping: 11 })
          : timing(value, { toValue, duration, easing: curves[easing] });
      loop(sequence([go(1), delay(500), go(0), delay(500)]));
    },
    [tempo, duration, easing],
  );

  const x = progress.interpolate({ inputRange: [0, 1], outputRange: ['0px', '200px'] });
  const turn = progress.interpolate({ inputRange: [0, 1], outputRange: ['-90deg', '180deg'] });

  return (
    <div className="stage">
      <div className="track">
        <div className="fill" style={{ transform: `scaleX(${progress})` }} />
      </div>
      <div className="row">
        <div className="dial">
          <i style={{ transform: `rotate(${turn})` }} />
        </div>
        <div className="lane">
          <div className="puck" style={{ transform: `translateX(${x})` }} />
        </div>
      </div>
      <div className="cards">
        {[0, 1, 2, 3].map((index) => {
          const start = index * 0.15;
          const lift = progress.interpolate({
            inputRange: [start, start + 0.55],
            outputRange: ['0px', '-26px'],
            extrapolate: 'clamp',
          });
          return (
            <div key={index} className="card" style={{ transform: `translateY(${lift})` }}>
              {index + 1}
            </div>
          );
        })}
      </div>
      <p className="note">One value → 7 elements, ordinary React style</p>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 22px;
  padding: 28px;
}

.track {
  height: 12px;
  border-radius: 999px;
  background: #eef2ff;
  overflow: hidden;
}

.fill {
  height: 100%;
  background: #2854ff;
  transform-origin: left center;
}

.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 24px;
}

.dial {
  position: relative;
  flex: none;
  width: 72px;
  height: 72px;
  border: 2px solid #e4e6ef;
  border-radius: 50%;
}

.dial i {
  position: absolute;
  inset: 50% auto auto 50%;
  width: 30px;
  height: 4px;
  margin-top: -2px;
  border-radius: 2px;
  background: #8fb0ff;
  transform-origin: left center;
}

.lane {
  flex: 1 1 244px;
  max-width: 260px;
  height: 44px;
  border-radius: 999px;
  background: #f5f6fb;
}

.puck {
  width: 44px;
  height: 44px;
  border-radius: 50%;
  background: #5c7cff;
}

.cards {
  display: flex;
  gap: 12px;
  padding-top: 30px;
}

.card {
  display: grid;
  place-items: center;
  width: 64px;
  height: 64px;
  border-radius: 14px;
  background: #16181d;
  color: #fff;
  font-weight: 700;
}

.note {
  margin: 0;
  color: #5b6070;
  font-size: 14px;
}

الاستدعاءات نفسها كما في React Native

Spinner.jsx

// React Native
<Animated.View style={{ transform: [{ rotate }] }} />

// React DOM with @kkwaenggwari/animated — the rest is identical
<Animated.div style={{ transform: [{ rotate }] }} />

const spin = useAnimatedValue(0);
const rotate = spin.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] });

Animated.loop(
  Animated.timing(spin, { toValue: 1, duration: 900, easing: Easing.linear, useNativeDriver: true }),
).start();

02 · سريع

لا عرض React في كل إطار

قيمة الخطّاف متغيّر CSS. تصبح الاستيفاءات الخطية والعمليات الحسابية تعبيرات calc() دقيقة لذلك المتغيّر، فيكون كل إطار كتابة واحدة ويشتق المتصفح الباقي. والحركة المحدودة لـ transform وopacity على عناصر Animated.<tag> يشغّلها المتصفح من دون استدعاءات إطارات.

غيّر عدد النقاط: يُظهر العدّاد أن React عرض مرة واحدة لكل تغيير، لا لكل إطار.
يكتب scope القيمة مرة واحدة على حاوية بدل كل عنصر.
يخبرك inspect(element) بالمسار الذي تستخدمه كل خاصية ولماذا.

جارٍ تجهيز المثال…

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;
}

03 · مستقر

قاطعه في أي مكان. يكمل طريقه.

يبدأ الهدف الجديد من حيث يقع العنصر على الشاشة، ويحتفظ النابض أيضًا بسرعته، فيكون الالتفاف في منتصف الطريق سلسًا بدل أن يتوقف أولًا. والمتحكمات المعرّفة في خطّاف تتوقف وتُحرَّر عند الاستبدال والإزالة، وتواصل العلامات المعروضة على الخادم حركتها بعد الإماهة.

انقر مرتين بسرعة: مع spring ينحني المسار، ومع timing يحتفظ بالموضع لكن يبدأ منحنى جديدًا.
الإيقاف يترك القيمة في مكانها؛ لا شيء يقفز إلى حالة نهائية.
لا حلقات إطارات منسية بعد الإزالة أو تغيير المسار أو إخفاء علامة التبويب.

جارٍ تجهيز المثال…

JavaScript معطّل. الشيفرة أدناه هي المثال الكامل.

App.jsx

import { useRef } from 'react';
import {
  Easing,
  spring,
  timing,
  useAnimatedListener,
  useAnimatedValueXY,
} from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ tempo = 'spring', stiffness = 140, damping = 14 }) {
  const point = useAnimatedValueXY({ x: 80, y: 120 });
  const canvas = useRef(null);

  const moveTo = (event) => {
    const box = event.currentTarget.getBoundingClientRect();
    const toValue = { x: event.clientX - box.left, y: event.clientY - box.top };
    // A new target starts from where the puck is now.
    const motion =
      tempo === 'spring'
        ? spring(point, { toValue, stiffness, damping })
        : timing(point, { toValue, duration: 700, easing: Easing.inOut(Easing.cubic) });
    motion.start();
  };

  // Draw the path the puck actually travels.
  const last = useRef(null);
  useAnimatedListener(point, ({ x, y }) => {
    const context = canvas.current?.getContext('2d');
    if (!context) return;
    context.fillStyle = 'rgba(11, 20, 64, 0.025)';
    context.fillRect(0, 0, context.canvas.width, context.canvas.height);
    if (last.current) {
      context.strokeStyle = tempo === 'spring' ? '#8fb0ff' : '#ffffff';
      context.lineWidth = 4;
      context.lineCap = 'round';
      context.beginPath();
      context.moveTo(last.current.x, last.current.y);
      context.lineTo(x, y);
      context.stroke();
    }
    last.current = { x, y };
  });

  return (
    <div className="stage">
      <div className="track" onPointerDown={moveTo}>
        <canvas ref={canvas} width={720} height={320} />
        <div
          className="puck"
          style={{
            transform: `translate(calc(${point.x} * 1px - 50%), calc(${point.y} * 1px - 50%))`,
          }}
        />
        <p>Click anywhere. Click again before it stops.</p>
      </div>
    </div>
  );
}

styles.css

.stage {
  padding: 20px;
}

.track {
  position: relative;
  height: 320px;
  border-radius: 16px;
  background: #0b1440;
  overflow: hidden;
  cursor: crosshair;
  touch-action: none;
  user-select: none;
}

.track canvas {
  position: absolute;
  inset: 0;
  width: 720px;
  height: 320px;
}

.puck {
  position: absolute;
  top: 0;
  left: 0;
  width: 36px;
  height: 36px;
  border: 3px solid #fff;
  border-radius: 50%;
  background: #2854ff;
}

.track p {
  position: absolute;
  inset: auto 16px 12px;
  margin: 0;
  color: #b8c4ef;
  font-size: 14px;
  pointer-events: none;
}

ما يمكنك بناؤه

أنماط كاملة بإعدادات قابلة للضبط وشيفرة مصدرية كاملة.

كل الأمثلة

مبني على Animated

تحتاج إلى مكوّن جاهز؟ Animated Chorus.

أرقام تتدحرج، وتمييز علامات تبويب ينتقل، وتقدّم، ولوحات، وقوائم متحركة تندمج مباشرة في React وReact Native. هذه الثلاثة تعمل في هذه الصفحة الآن.

زُر Animated Chorus

ابدأ في ثلاث دقائق

ثبّت الحزمة، وحرّك قيمتك الأولى، ثم اختر دليلًا للمهمة التي أمامك.

npm install @kkwaenggwari/animated