MotionPager

صفحات قابلة للسحب من البيانات: التعريف بالتطبيق والدوّارات ولوحات التبويب.

الويبReact Nativeالاختيار والصفحات

جرّبه

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

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

App.jsx

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

const slides = [
  { id: 'welcome', title: 'Welcome', text: 'Swipe, drag or use the arrow keys.', tone: 'deep' },
  { id: 'data', title: 'Your data', text: 'Pages come from an array.', tone: 'forest' },
  { id: 'flick', title: 'Flick', text: 'A quick flick always turns one page.', tone: 'mint' },
  { id: 'done', title: 'Done', text: 'The index is yours to control.', tone: 'light' },
];

export default function App({ gap = 16, spring = 'default' }) {
  const [page, setPage] = useState(0);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];

  return (
    <div className="stage">
      <MotionPager
        className="pager"
        items={slides}
        index={page}
        onIndexChange={setPage}
        gap={gap}
        transition={transition}
        renderItem={(slide) => (
          <article className={`slide ${slide.tone}`}>
            <h2>{slide.title}</h2>
            <p>{slide.text}</p>
          </article>
        )}
      />
      <div className="controls">
        <button onClick={() => setPage(Math.max(0, page - 1))} disabled={page === 0}>
          Back
        </button>
        <MotionHighlight
          className="dots"
          itemClassName="dot"
          highlightClassName="dot-active"
          items={slides}
          value={slides[page].id}
          transition={transition}
          onValueChange={(key) => setPage(slides.findIndex((slide) => slide.id === key))}
          renderItem={(slide, { index }) => <span className="dot-number">{index + 1}</span>}
        />
        <button
          onClick={() => setPage(Math.min(slides.length - 1, page + 1))}
          disabled={page === slides.length - 1}
        >
          Next
        </button>
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  gap: 16px;
  max-width: 560px;
  margin: 0 auto;
  padding: 24px 20px;
}

.pager {
  border-radius: 20px;
}

.slide {
  display: grid;
  align-content: end;
  gap: 6px;
  height: 240px;
  padding: 24px;
  border-radius: 20px;
  user-select: none;
}

.slide h2 {
  margin: 0;
  font:
    800 30px/1.1 system-ui,
    sans-serif;
}

.slide p {
  margin: 0;
}

.deep {
  background: #0e2e24;
  color: #fff;
}

.forest {
  background: #176b52;
  color: #fff;
}

.mint {
  background: #43c58f;
  color: #0e2e24;
}

.light {
  background: #eaf6f0;
  color: #0e2e24;
}

.controls {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 12px;
}

.controls > button {
  flex: none;
  min-height: 44px;
  padding: 0 18px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 15px system-ui,
    sans-serif;
  cursor: pointer;
}

.controls > button:disabled {
  opacity: 0.4;
}

.dots {
  display: flex;
  min-width: 0;
  gap: 4px;
}

/* On a narrow phone the page dots shrink (never below 28px); Back and Next keep their size. */
.dot {
  flex: 0 1 36px;
  min-width: 28px;
  aspect-ratio: 1;
  border: 0;
  border-radius: 50%;
  background: none;
  cursor: pointer;
}

.dot-number {
  font:
    600 13px system-ui,
    sans-serif;
  color: #5b616b;
}

.dot-active {
  border-radius: 50%;
  background: #eaf6f0;
  box-shadow: inset 0 0 0 2px #176b52;
}

@media (max-width: 340px) {
  .controls {
    gap: 8px;
  }

  .controls > button {
    padding: 0 14px;
  }
}

أقصر استخدام

Onboarding.jsx

<MotionPager
  items={slides}
  index={page}
  onIndexChange={setPage}
  gap={16}
  renderItem={(slide) => <Slide slide={slide} />}
/>;

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

تتبع الصفحات السحب باللمس والفأرة، وتقاوم بعد الطرفين، وتستقر وفق سرعة إفلاتك.
النقرة السريعة تقلب صفحة دائمًا، ولا تقلب الإيماءة الواحدة أكثر من صفحة.
التمرير الأفقي بلوحة اللمس يقلب الصفحات أيضًا، ويُتجاهل ذيل زخمه.
تعمل مفاتيح الأسهم وHome وEnd حين يكون مقلّب الصفحات في التركيز، ويستمر التمرير العمودي في العمل.
الصفحات غير النشطة خاملة.

استخدمه لـ

مسار تعريف بالتطبيق.
دوّار صور.
لوحات تبويب قابلة للسحب مقرونة بـ MotionHighlight.

Props

Prop	النوع	الافتراضي	الوصف
`items`	`readonly T[]`	`—`إلزامي	مصفوفة بياناتك.
`index`	`number`		الصفحة المعروضة. اتركها ليحتفظ مقلّب الصفحات بصفحته.
`defaultIndex`	`number`	`0`	الصفحة الأولى حين لا يكون `index` متحكَّمًا به.
`onIndexChange`	`(index, item) => void`		يعمل مع الفهرس والعنصر بمجرد أن تستقر سحبة أو مفتاح أو إيماءة عجلة.
`getKey`	`(item) => string \| number`	`item.id`	تعيد مفتاحًا فريدًا ثابتًا لعنصر. افتراضيًا `item.id`، أو العنصر نفسه للنصوص والأرقام.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	يرسم صفحة؛ ويتلقى فهرسها وما إذا كانت نشطة.
`gap`	`number`	`0`	المسافة بين الصفحات بالبكسل.
`itemClassName`	`string`		صنف لعنصر كل بند؛ ويضبط `itemStyle` نمطه المضمّن.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

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

الويب وReact Native

يمكن التحكم في index (ويُبلغ onIndexChange(index, item) عن كل استقرار) أو تركه لمقلّب الصفحات عبر defaultIndex.

يعمل المكوّن نفسه وprops نفسها في React Native.

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

خلاصة الصورتنقّل بين الصور بالسحب، وانتقل عبر الصور المصغّرة، وافتح أي صورة بملء الشاشة واسحب تفاصيلها إلى الأعلى.MotionPagerMotionHighlightMotionZoomMotionSheet