الأدلة · 02

Timing والنوابض والتركيب

اختر مشغّلًا، وركّب عدة مشغّلات، واعرف بدقة ما يحدث حين يُوقَف أحدها أو يُستبدل.

timing وspring وdecay

يتبع timing منحنى لمدة duration ثابتة. ويتبع spring الفيزياء وليس له طول ثابت. ويبدأ decay بسرعة ثم يتباطأ.

تقبل المشغّلات نفسها رقمًا أو ValueXY أو سجلًا، فيمكن لـ { x, y, opacity } أن تتحرك معًا.

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

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

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

معاملات النابض

استخدم مجموعة معاملات واحدة. ومن دونها تحصل على نابض React Native الافتراضي (tension 40، friction 7). وقيمة velocity للنابض افتراضيًا هي سرعة المسار الذي يقاطعه.

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

التركيب

يشغّل sequence واحدًا تلو الآخر، وparallel معًا، وstagger يبدأ كلًا منها بعد تأخير، وdelay ينتظر، وloop يكرّر. والنتيجة متحكم مجددًا، فتتداخل التراكيب.

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

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

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 وreset

لكل متحكم start(callback?) وstop() وreset(). يتلقى الاستدعاء الراجع { finished }: وقيمته false حين تُوقَف الحركة أو تُستبدل.

بدء مشغّل جديد على القيمة نفسها يستبدل الجاري من الموضع الحالي. لا قفز إلى أيٍّ من الطرفين.

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

تتبّع قيمة أخرى

قيمة toValue الحية تعيد تشغيل المشغّل كلما تغيّرت تلك القيمة، مثل التتبّع في React Native. وfollow(target, source) هو وصلة النابض نفسها في صورة دالة مسمّاة.

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 والإطارات المفتاحية

يطابق Easing ما في React Native: linear وquad وcubic وsin وcircle وexp وelastic وback وbounce وbezier، والمساعدات in وout وinOut. ويقود keyframes(value, frames, options) قيمة واحدة عبر عدة أرقام مع times وrepeat اختياريين.