MotionPager

Các trang vuốt được từ dữ liệu: giới thiệu, băng chuyền và bảng tab.

WebReact NativeLựa chọn và phân trang

Thử ngay

Đang chuẩn bị ví dụ…

JavaScript đang tắt. Đoạn mã bên dưới là ví dụ đầy đủ.

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

Cách dùng ngắn nhất

Onboarding.jsx

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

Những gì nó xử lý giúp bạn

Trang bám theo thao tác vuốt và kéo chuột, có lực cản ở hai đầu và dừng theo tốc độ bạn thả.
Một cú hất luôn lật một trang, và một cử chỉ không bao giờ lật quá một trang.
Cuộn ngang trên trackpad cũng lật trang, và phần quán tính phía sau bị bỏ qua.
Phím mũi tên, Home và End hoạt động khi pager được focus, và cuộn dọc vẫn hoạt động.
Các trang không phải trang hiện tại đều bị vô hiệu.

Dùng cho

Luồng giới thiệu.
Băng chuyền ảnh.
Bảng tab vuốt được, ghép với MotionHighlight.

Props

Prop	Kiểu	Mặc định	Mô tả
`items`	`readonly T[]`	`—`bắt buộc	Mảng dữ liệu của bạn.
`index`	`number`		Trang đang hiển thị. Bỏ trống để pager tự quản lý.
`defaultIndex`	`number`	`0`	Trang bắt đầu khi `index` không được kiểm soát.
`onIndexChange`	`(index, item) => void`		Chạy với index và mục ngay khi cử chỉ vuốt, phím hoặc con lăn dừng lại.
`getKey`	`(item) => string \| number`	`item.id`	Trả về key duy nhất, ổn định cho một mục. Mặc định là `item.id`, hoặc chính mục đó với chuỗi và số.
`renderItem`	`(item, { index, active }) => ReactNode`	`item.label`	Vẽ một trang; nhận index của nó và việc nó có đang hiện hành không.
`gap`	`number`	`0`	Khoảng cách giữa các trang tính bằng pixel.
`itemClassName`	`string`		Class cho từng phần tử mục; `itemStyle` đặt style nội tuyến của nó.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Các props khác được chuyển tới phần tử được render, nên className, style và trình xử lý sự kiện hoạt động như bình thường.

Web và React Native

index có thể được kiểm soát (onIndexChange(index, item) báo mỗi lần dừng) hoặc giao cho pager với defaultIndex.

Cùng component và props hoạt động trên React Native.

Được dùng trong các ví dụ này

Bảng tin ảnhVuốt qua ảnh, nhảy bằng ảnh thu nhỏ, mở bất kỳ ảnh nào ra toàn màn hình và kéo lên xem chi tiết.MotionPagerMotionHighlightMotionZoomMotionSheet