Guides · 02

Timing, ressorts et composition

Choisir un driver, en composer plusieurs, et savoir exactement ce qui se passe quand l’un est arrêté ou remplacé.

timing, spring et decay

timing suit une courbe pendant une duration fixe. spring suit la physique et n’a pas de durée fixe. decay démarre avec une vitesse et ralentit.

Les mêmes drivers acceptent un nombre, un ValueXY ou un enregistrement : { x, y, opacity } peuvent bouger ensemble.

Préparation de l’exemple…

JavaScript est désactivé. Le code ci-dessous est l’exemple complet.

App.jsx

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

export default function App({ stiffness = 180, damping = 12, mass = 1, duration = 500 }) {
  const eased = useAnimatedValue(0);
  const standard = useAnimatedValue(0);
  const custom = useAnimatedValue(0);

  const go = () => {
    const toValue = custom.getValue() < 0.5 ? 1 : 0;
    parallel([
      timing(eased, { toValue, duration, easing: Easing.inOut(Easing.cubic) }),
      spring(standard, { toValue }),
      spring(custom, { toValue, stiffness, damping, mass }),
    ]).start();
  };

  const lanes = [
    ['timing', eased],
    ['spring()', standard],
    ['spring(props)', custom],
  ];

  return (
    <div className="stage">
      <button type="button" onClick={go}>
        Go
      </button>
      {lanes.map(([label, value]) => (
        <div key={label} className="lane">
          <code>{label}</code>
          <div className="rail">
            <span
              style={{
                left: `calc(${value} * (100% - 40px))`,
              }}
            />
          </div>
        </div>
      ))}
    </div>
  );
}

styles.css

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

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

.lane {
  display: grid;
  grid-template-columns: 120px 1fr;
  align-items: center;
  gap: 12px;
}

.lane code {
  color: #1a33c7;
  font-size: 13px;
}

.rail {
  position: relative;
  height: 40px;
  border-radius: 999px;
  background: #f5f6fb;
  box-shadow: inset -2px 0 0 #e4e6ef;
}

.rail span {
  position: absolute;
  top: 0;
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background: #8fb0ff;
}

.lane:first-of-type .rail span {
  background: #5c7cff;
}

.lane:last-of-type .rail span {
  background: #2854ff;
}

Paramètres du ressort

Utilisez une seule paramétrisation. Sans aucune, vous obtenez le ressort par défaut de React Native (tension 40, friction 7). La velocity d’un ressort reprend par défaut la vitesse de la trajectoire qu’il interrompt.

springs.js

spring(value, { toValue: 1 }); // React Native default
spring(value, { toValue: 1, stiffness: 260, damping: 20 }); // physical
spring(value, { toValue: 1, bounciness: 8, speed: 12 }); // React Native style
spring(value, { toValue: 1, tension: 40, friction: 7 }); // origami style

Composer

sequence enchaîne, parallel exécute ensemble, stagger démarre chacun après un délai, delay attend et loop répète. Le résultat est encore un contrôleur : les compositions s’imbriquent.

Préparation de l’exemple…

JavaScript est désactivé. Le code ci-dessous est l’exemple complet.

App.jsx

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

const keys = ['a', 'b', 'c', 'd', 'e'];

export default function App({ mode = 'stagger', gap = 90 }) {
  const bars = useAnimated(
    { a: 0, b: 0, c: 0, d: 0, e: 0 },
    (value) => {
      const group = (list) =>
        mode === 'sequence'
          ? sequence(list)
          : mode === 'parallel'
            ? parallel(list)
            : stagger(gap, list);
      const rise = keys.map((key) =>
        spring(value[key], { toValue: 1, stiffness: 220, damping: 16 }),
      );
      const fall = keys.map((key) => timing(value[key], { toValue: 0, duration: 260 }));
      loop(sequence([group(rise), delay(500), group(fall), delay(300)]));
    },
    [mode, gap],
  );

  return (
    <div className="stage">
      {keys.map((key) => (
        <span key={key} style={{ transform: `scaleY(calc(0.15 + ${bars[key]} * 0.85))` }} />
      ))}
    </div>
  );
}

styles.css

.stage {
  display: flex;
  align-items: flex-end;
  justify-content: center;
  gap: 14px;
  height: 260px;
  padding: 32px;
}

.stage span {
  width: 44px;
  height: 100%;
  border-radius: 12px;
  background: #2854ff;
  transform-origin: bottom;
}

.stage span:nth-child(2n) {
  background: #8fb0ff;
}

.stage span:nth-child(3) {
  background: #5c7cff;
}

start, stop et reset

Chaque contrôleur a start(callback?), stop() et reset(). Le callback reçoit { finished } : false quand le mouvement a été arrêté ou remplacé.

Démarrer un nouveau driver sur la même valeur remplace celui en cours depuis la position actuelle. Aucun saut vers l’une ou l’autre extrémité.

controller.js

const move = timing(value, { toValue: 1, duration: 600 });

move.start(({ finished }) => {
  // finished is false when stopped or replaced by a new animation
});
move.stop(); // keeps the value where it is on screen
move.reset(); // returns to where this animation started

Suivre une autre valeur

Un toValue vivant redémarre le driver chaque fois que cette valeur change, comme le tracking de React Native. follow(target, source) est la même connexion à ressort sous forme de fonction nommée.

tracking.js

// A live toValue tracks another value, like React Native tracking.
spring(badge, { toValue: pointer, stiffness: 300, damping: 26 }).start();

// follow() is the same connection as a named function.
follow(badge, pointer, { stiffness: 300, damping: 26 });

Easing et keyframes

Easing correspond à React Native : linear, quad, cubic, sin, circle, exp, elastic, back, bounce, bezier et les aides in, out et inOut. keyframes(value, frames, options) fait passer une valeur par plusieurs nombres, avec times et repeat facultatifs.