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`		class לאלמנט של כל פריט; `itemStyle` מגדיר את הסגנון המוטבע שלו.
`transition`	`Transition`	`spring`	עקומת timing `{ duration, easing }` או קפיץ `{ tempo: 'spring', spring }`. קפיצים שומרים על התנופה שלהם כשמפריעים להם.

props אחרים עוברים לאלמנט המרונדר, כך ש־className, style ומטפלי אירועים עובדים כרגיל.

אינטרנט ו־React Native

index יכול להיות מבוקר (onIndexChange(index, item) מדווח על כל התייצבות) או להישאר בידי מחליף העמודים עם defaultIndex.

אותו רכיב ואותם props עובדים ב־React Native.

בשימוש בדוגמאות האלה

פיד תמונותהחליקו בין תמונות, קפצו בעזרת תמונות ממוזערות, פתחו כל תמונה במסך מלא ומשכו למעלה את הפרטים שלה.MotionPagerMotionHighlightMotionZoomMotionSheet