MotionSwap

محتوى يتبدّل بتلاشٍ متقاطع بينما يتبعه الحجم.

الويبReact Nativeالمحتوى والحجم

جرّبه

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

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

App.jsx

import { useEffect, useState } from 'react';
import { MotionSwap, motionTokens } from '@kkwaenggwari/animated-chorus';
import './styles.css';

function Check() {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16">
      <path d="m3 8.5 3 3 7-7" fill="none" stroke="currentColor" strokeWidth="2" />
    </svg>
  );
}

export default function App({ effect = 'up', align = 'center', spring = 'default' }) {
  const [status, setStatus] = useState('idle');
  const [loaded, setLoaded] = useState(true);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];

  useEffect(() => {
    if (status === 'idle') return;
    const next = status === 'saving' ? 'saved' : 'idle';
    const timer = setTimeout(() => setStatus(next), status === 'saving' ? 1100 : 1600);
    return () => clearTimeout(timer);
  }, [status]);

  useEffect(() => {
    if (loaded) return;
    const timer = setTimeout(() => setLoaded(true), 1200);
    return () => clearTimeout(timer);
  }, [loaded]);

  return (
    <div className="stage">
      <button className={`save ${status}`} onClick={() => setStatus('saving')}>
        <MotionSwap value={status} effect={effect} align={align} transition={transition}>
          {status === 'idle' && 'Save changes'}
          {status === 'saving' && 'Saving…'}
          {status === 'saved' && (
            <>
              <Check /> Saved
            </>
          )}
        </MotionSwap>
      </button>

      <MotionSwap
        as="div"
        inline={false}
        value={loaded ? 'profile' : 'loading'}
        effect={effect}
        transition={transition}
        className="profile"
      >
        {loaded ? (
          <div className="person">
            <span className="avatar">MK</span>
            <div>
              <strong>Min-ji Kim</strong>
              <p>Design engineer. Builds the motion system and the component docs.</p>
            </div>
          </div>
        ) : (
          <div className="skeleton">
            <span />
            <span />
          </div>
        )}
      </MotionSwap>
      <button className="reload" onClick={() => setLoaded(false)}>
        Reload profile
      </button>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  justify-items: center;
  gap: 18px;
  max-width: 460px;
  margin: 0 auto;
  padding: 32px 20px;
}

.save {
  min-height: 48px;
  padding: 0 22px;
  border: 0;
  border-radius: 999px;
  background: #176b52;
  color: #fff;
  font:
    650 16px system-ui,
    sans-serif;
  cursor: pointer;
  transition: background-color 0.2s;
}

.save.saving {
  background: #2e8f6d;
}

.save.saved {
  background: #0e2e24;
}

.save svg {
  vertical-align: -2px;
}

.profile {
  width: 100%;
  border: 1px solid #cfe8dc;
  border-radius: 16px;
  background: #fff;
}

.person {
  display: flex;
  gap: 14px;
  padding: 18px;
}

.person p {
  margin: 4px 0 0;
  color: #5b616b;
}

.avatar {
  display: grid;
  flex: none;
  place-items: center;
  width: 48px;
  height: 48px;
  border-radius: 50%;
  background: #eaf6f0;
  color: #176b52;
  font-weight: 700;
}

.skeleton {
  display: grid;
  gap: 10px;
  padding: 22px 18px;
}

.skeleton span {
  height: 12px;
  border-radius: 6px;
  background: #eaf6f0;
}

.skeleton span:last-child {
  width: 60%;
}

.reload {
  min-height: 40px;
  padding: 0 16px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 14px system-ui,
    sans-serif;
  cursor: pointer;
}

أقصر استخدام

SaveButton.jsx

<button onClick={save}>
  <MotionSwap value={status} effect="up">
    {status === 'saving' ? 'Saving…' : status === 'saved' ? 'Saved' : 'Save'}
  </MotionSwap>
</button>;

ما يتولّاه عنك

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

استخدمه لـ

حفظ، ثم جارٍ الحفظ…، ثم تم الحفظ.
هيكل تحميل يتحول إلى بطاقة ملف شخصي.
زر تشغيل يصبح إيقافًا مؤقتًا.

Props

Prop	النوع	الافتراضي	الوصف
`value`	`unknown`		هوية المحتوى؛ والقيمة الجديدة تبدّله. الأبناء النصية هي هويتها.
`children`	`ReactNode`		المحتوى.
`as`	`element`	`'span'`	العنصر المراد عرضه.
`inline`	`boolean`	`as === 'span'`	يتحجّم `true` حسب المحتوى (تسميات، أيقونات)؛ ويملأ `false` عرض الأب ويحرّك الارتفاع.
`align`	`'start' \| 'center' \| 'end'`	`'center'`	أين يقع المحتوى أثناء تغيّر الحجم.
`effect`	`'fade' \| 'up' \| 'down' \| 'scale'`	`'fade'`	كيف يدخل المحتوى ويخرج: `up` يصعد، و`down` يهبط، و`scale` يكبر.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.
`onMotionComplete`	`(value) => void`		يعمل حين تستقر الحركة.

تذهب props الأخرى إلى العنصر المعروض، فتعمل className وstyle ومعالجات الأحداث كالمعتاد.

الويب وReact Native

يحرّك inline (الافتراضي حين يُعرض كـ span) العرض والارتفاع؛ ويملأ inline={false} عرض الأب ويحرّك الارتفاع.

في React Native تقيس التبديلات المضمّنة المحتوى الجديد على سطر واحد؛ استخدم inline={false} للمحتوى الذي يلتف.

مستخدم في هذه الأمثلة

إجابة المحادثةاقتراحات تنطوي، وإجابة تتدفق بإيقاع ثابت، وسطر حالة يتبدّل.MotionStreamMotionListMotionSwapMotionHeight