מדריכים · 01

ערכים וסגנון

החזיקו ערך ברכיב, גזרו פלטים עם calc() ובחרו איפה משתנה ה־CSS נכתב.

להחזיק ערך

useAnimatedValue(initial) יוצר Value ששייך לרכיב. השתמשו במספר, או ברשומה כמו { x: 0, opacity: 1 } שהשדות שלה הם ערכים נפרדים.

ב־style רגיל, ערך של hook הוא הטוקן 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 }} />;

לתת ל־hook להחזיק מתכון

useAnimated(initial, factory, deps) מחזיק את הערך ואת כל בקר שמוצהר באופן סינכרוני ב־factory. מתחיל בהרכבה, מתחיל מחדש כשתלות משתנה ונעצר בהסרה.

העבירו { 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} קובע scope ברירת מחדל לכל ערכי ה־hooks מתחתיו.

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 או לאנליטיקה, לא לרינדור.