MotionList

قائمة من البيانات لا تحرّك إلا ما تغيّر.

الويبReact Nativeالقوائم

جرّبه

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

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

App.jsx

import { useState } from 'react';
import { MotionList } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const ideas = [
  'Plan the launch',
  'Write release notes',
  'Record a demo',
  'Update the docs',
  'Reply to issues',
  'Tag the release',
];

export default function App({ effect = 'rise', stagger = 40, distance = 18 }) {
  const [tasks, setTasks] = useState([
    { id: 1, title: 'Review the design' },
    { id: 2, title: 'Fix the flaky test' },
    { id: 3, title: 'Ship the changelog' },
  ]);
  const [next, setNext] = useState(4);

  const add = () => {
    setTasks([{ id: next, title: ideas[next % ideas.length] }, ...tasks]);
    setNext(next + 1);
  };
  const remove = (id) => setTasks(tasks.filter((task) => task.id !== id));
  const shuffle = () => setTasks([...tasks.slice(1), tasks[0]].filter(Boolean));
  const sort = () => setTasks([...tasks].sort((a, b) => a.title.localeCompare(b.title)));

  return (
    <div className="stage">
      <div className="buttons">
        <button className="primary" onClick={add}>
          Add task
        </button>
        <button onClick={shuffle}>Move first to end</button>
        <button onClick={sort}>Sort A–Z</button>
      </div>
      <MotionList
        as="ul"
        className="tasks"
        items={tasks}
        effect={effect}
        stagger={stagger}
        distance={distance}
        renderItem={(task) => (
          <div className="task">
            <span>{task.title}</span>
            <button onClick={() => remove(task.id)}>Done</button>
          </div>
        )}
      />
    </div>
  );
}

styles.css

.stage {
  display: grid;
  gap: 16px;
  max-width: 520px;
  min-height: 360px;
  margin: 0 auto;
  padding: 24px 20px;
  align-content: start;
}

.buttons {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

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

.buttons .primary {
  border-color: #176b52;
  background: #176b52;
  color: #fff;
}

.tasks {
  display: grid;
  gap: 8px;
  margin: 0;
  padding: 0;
  list-style: none;
}

.task {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
  padding: 10px 10px 10px 16px;
  border: 1px solid #cfe8dc;
  border-radius: 12px;
  background: #fff;
}

.task button {
  min-height: 36px;
  padding: 0 14px;
  border: 0;
  border-radius: 999px;
  background: #eaf6f0;
  color: #176b52;
  font:
    650 13px system-ui,
    sans-serif;
  cursor: pointer;
}

أقصر استخدام

Todos.jsx

<MotionList as="ul" items={todos} renderItem={(todo) => <TodoRow todo={todo} />} />;

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

تدخل العناصر الجديدة بتتابع محدود بينما تبقى العناصر غير المتأثرة ثابتة.
تخرج العناصر المحذوفة من التدفق وتتحرك خارجة في مكانها بينما ينزلق الباقي لسدّ الفراغ.
تنزلق العناصر المعاد ترتيبها إلى مواضعها الجديدة.
التحرّكات التي يقاطعها تغيير آخر تحتفظ بسرعتها.
يحرّك present={false} كل العناصر خارجة، ويعيد playKey تشغيل الدخول.

استخدمه لـ

قائمة مهام.
نتائج بحث مصفّاة.
سلة تسوّق.

Props

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`	`—`إلزامي	مصفوفة بياناتك.
`getKey`	`(item) => string \| number`	`item.id`	تعيد مفتاحًا فريدًا ثابتًا لعنصر. افتراضيًا `item.id`، أو العنصر نفسه للنصوص والأرقام.
`renderItem`	`(item, index) => ReactNode`	`item.label`	يرسم عنصرًا.
`as`	`element`	`'div'`	العنصر المراد عرضه.
`itemAs`	`element`	`'li' \| 'div'`	العنصر لكل بند.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.
`effect`	`'rise' \| 'fade' \| 'scale' \| 'slide'`	`'rise'`	كيف تدخل العناصر وتخرج.
`distance`	`number`	`16`	مسافة `rise` و`slide` بالبكسل.
`stagger`	`number`	`40`	مللي ثوانٍ بين العناصر الداخلة.
`order`	`'forward' \| 'reverse'`	`'forward'`	اتجاه التتابع.
`present`	`boolean`	`true`	يحرّك `false` كل العناصر خارجة مع الحفاظ على التخطيط؛ ويعيدها `true`.
`initial`	`boolean`	`true`	شغّل الدخول حين تُركَّب القائمة.
`playKey`	`string \| number`		تغييره يعيد تشغيل الدخول.
`transition`	`Transition`	`spring`	الانتقال للعناصر الداخلة والخارجة.
`layoutTransition`	`Transition`	`spring`	الانتقال للعناصر المنزلقة إلى مواضع جديدة.

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

الويب وReact Native

يحصل كل عنصر على عنصر غلاف (li داخل ul أو ol، وإلا div؛ ويغيّره itemAs) منسّق عبر itemClassName.

يجب أن تكون المفاتيح فريدة. غلّف القائمة في MotionHeight لتحريك ارتفاعها الكلي أيضًا.