الأدلة · 01

القيم والأنماط

امتلك قيمة في مكوّن، واشتق مخرجات عبر calc()، واختر أين يُكتب متغيّر CSS.

امتلاك قيمة

ينشئ useAnimatedValue(initial) قيمة Value يملكها المكوّن. استخدم رقمًا، أو سجلًا مثل { x: 0, opacity: 1 } حقوله قيم منفصلة.

في style العادي، قيمة الخطّاف هي الرمز var(--kkwa-…, initial). تكتب التحديثات هذا المتغيّر على العناصر التي تستخدمه؛ ولا يعرض React.

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

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

App.jsx

import { timing, useAnimatedValue } from '@kkwaenggwari/animated';
import './styles.css';

export default function App({ duration = 600 }) {
  const progress = useAnimatedValue(1);

  const toggle = () => {
    const toValue = progress.getValue() > 0.5 ? 0 : 1;
    timing(progress, { toValue, duration }).start();
  };

  return (
    <div className="stage">
      <button type="button" onClick={toggle}>
        Toggle
      </button>
      <div className="box" style={{ opacity: progress }}>
        Ready
      </div>
    </div>
  );
}

styles.css

.stage {
  display: flex;
  align-items: center;
  gap: 24px;
  min-height: 200px;
  padding: 28px;
}

button {
  min-height: 44px;
  padding: 0 20px;
  border: 0;
  border-radius: 999px;
  background: #2854ff;
  color: #fff;
  font: inherit;
  font-weight: 650;
  cursor: pointer;
}

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

الاشتقاق عبر calc()

الاستيفاء من دون easing وadd وsubtract وmultiply وdivide بثابت تصبح تعبيرات calc() دقيقة للمتغيّر نفسه. يشتقها المتصفح؛ ولا يعمل لها JavaScript في كل إطار.

Slide.jsx

const progress = useAnimatedValue(0);

// A linear interpolation of a hook value is a calc() of the same CSS variable.
const x = progress.interpolate({ inputRange: [0, 1], outputRange: ['0px', '180px'] });
const half = multiply(progress, 0.5);

<div style={{ opacity: half, transform: `translateX(${x})` }} />;

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

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

App.jsx

import { spring, useAnimatedValue } from '@kkwaenggwari/animated';
import './styles.css';

const colors = ['#2854ff', '#4a6bff', '#8fb0ff', '#7d9bff', '#5c7cff'];

export default function App({ distance = 220, spread = 0.12 }) {
  const progress = useAnimatedValue(0);

  const toggle = () => {
    const toValue = progress.getValue() < 0.5 ? 1 : 0;
    spring(progress, { toValue, stiffness: 150, damping: 16 }).start();
  };

  return (
    <div className="stage">
      <button type="button" onClick={toggle}>
        Move all
      </button>
      <div className="lanes">
        {colors.map((color, index) => {
          const start = index * spread;
          const x = progress.interpolate({
            inputRange: [start, start + 1 - spread * 4],
            outputRange: ['0px', `${distance}px`],
            extrapolate: 'clamp',
          });
          const turn = progress.interpolate({
            inputRange: [0, 1],
            outputRange: ['0deg', `${90 + index * 45}deg`],
          });
          return (
            <div key={color} className="lane">
              <span style={{ background: color, transform: `translateX(${x}) rotate(${turn})` }} />
            </div>
          );
        })}
      </div>
    </div>
  );
}

styles.css

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

button {
  justify-self: start;
  min-height: 44px;
  padding: 0 20px;
  border: 0;
  border-radius: 999px;
  background: #2854ff;
  color: #fff;
  font: inherit;
  font-weight: 650;
  cursor: pointer;
}

.lanes {
  display: grid;
  gap: 10px;
}

.lane {
  height: 36px;
  max-width: 320px;
  border-radius: 999px;
  background: #f5f6fb;
}

.lane span {
  display: block;
  width: 36px;
  height: 36px;
  border-radius: 10px;
}

الألوان والحسابات المخصّصة

لا يمكن كتابة الألوان والاستيفاءات ذات easing وmodulo وdiffClamp وAnimatedComputed كـ calc(). يمنحها useAnimatedCSS(node) متغيّر CSS خاصًا يحدّثه JavaScript، بعمر المكوّن نفسه.

استخدام عقدة كهذه مباشرة في style يرمي خطأً، فلا تبقى الكلفة مخفية أبدًا.

Glow.jsx

const progress = useAnimatedValue(0);

// Colors and eased curves are not calc() expressions: give them their own CSS value.
const color = useAnimatedCSS(
  progress.interpolate({ inputRange: [0, 1], outputRange: ['#3d3bf3', '#22b8f0'] }),
);

<div style={{ background: color }} />;

دع الخطّاف يمتلك الوصفة

يمتلك useAnimated(initial, factory, deps) القيمة وكل متحكم يُعرَّف بشكل متزامن في دالة المصنع. يبدأ عند التركيب، ويعيد البدء حين تتغيّر تبعية، ويتوقف عند الإزالة.

مرّر { autoStart: false } للتشغيل حسب الأحداث، ثم استدعِ start() أو stop() أو reset() على القيمة المُعادة.

Intro.jsx

const intro = useAnimated(
  { opacity: 0, y: 24 },
  (value) => {
    parallel([
      timing(value.opacity, { toValue: 1, duration: 400 }),
      spring(value.y, { toValue: 0, stiffness: 220, damping: 20 }),
    ]);
  },
  [],
);

<section style={{ opacity: intro.opacity, transform: `translateY(calc(${intro.y} * 1px))` }} />;

اكتب مرة واحدة لعناصر كثيرة

افتراضيًا، يتلقى المتغيّر كل عنصر يستخدم نمطه المضمّن القيمة. ومع scope، يُكتب المتغيّر مرة واحدة على حاوية ويرثه أبناؤها: الخيار الصحيح لمئات العناصر.

يضبط AnimatedProvider scope={ref} نطاقًا افتراضيًا لكل قيم الخطّافات تحته.

Field.jsx

const field = useRef(null);

// Written once on the field; every child that uses the value inherits it.
const wave = useAnimatedValue(0, { scope: field });

<div ref={field}>
  {items.map((item) => (
    <i key={item} style={{ transform: `rotate(calc(${wave} * 1turn))` }} />
  ))}
</div>;

قراءة القيم في JavaScript

يعيد getValue() لقطة من دون إشراك React. ويستدعيك useAnimatedListener(node, fn) عند كل تغيير ويزيل المستمع عند الإزالة. استخدمه للرسم على canvas أو للتحليلات، لا للعرض.