پرتوپرتو

صفحه‌بندی (Pagination)

کامپوننت ناوبری بین صفحات با props استاندارد

معرفی

کامپوننت Pagination برای ناوبری بین صفحات استفاده می‌شود. دو روش استفاده وجود دارد:

چه زمانی استفاده کنیم:

  • برای لیست‌ها یا جداول با تعداد زیاد آیتم که نیاز به تقسیم در چند صفحه دارند
  • وقتی کاربر باید بتواند به صفحه خاصی بپرد
  • برای نتایج جستجو یا فیلتر با حجم بالا

چه زمانی استفاده نکنیم:

  • وقتی داده‌ها کم هستند (کمتر از ۱۰ آیتم)
  • برای لیست‌های بی‌نهایت — از infinite scroll + LoadMore button استفاده کنید
  1. PaginationControlled: کامپوننت با props استاندارد (پیشنهادی)
  2. Pagination: کامپوننت پایه برای استفاده دستی

استفاده با PaginationControlled (پیشنهادی)

کامپوننت PaginationControlled با props استاندارد برای استفاده آسان:

Playground

در playground زیر می‌توانید props مختلف را تست کنید:

import { PaginationControlled } from '@parto-system-design/ui'
import { useState } from 'react'

export default function MyComponent() {
  const [currentPage, setCurrentPage] = useState(2)

  return <PaginationControlled currentPage={currentPage} totalPages={10} onPageChange={setCurrentPage} />
}

مثال با props اضافی

import { PaginationControlled } from '@parto-system-design/ui'

export default function MyComponent() {
  const [page, setPage] = useState(5)

  return (
    <PaginationControlled
      currentPage={page}
      totalPages={20}
      onPageChange={setPage}
      siblingCount={2} // تعداد صفحات در هر طرف صفحه فعلی
      showFirstLast={true} // نمایش دکمه‌های اول و آخر
      showPrevNext={true} // نمایش دکمه‌های قبلی و بعدی
      showEllipsis={true} // نمایش ellipsis برای صفحات مخفی
      dir="rtl" // جهت متن
    />
  )
}

استفاده دستی با Pagination

برای کنترل بیشتر، می‌توانید از کامپوننت‌های پایه استفاده کنید:

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  PaginationEllipsis,
} from '@parto-system-design/ui'

export default function MyComponent() {
  return (
    <Pagination dir="rtl">
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            2
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}

Props

PaginationControlled

Prop

Type

Prop

Type

PaginationPrevious / PaginationNext

Prop

Type

حالت‌ها و انواع

مثال ساده

const [page, setPage] = useState(1)

;<PaginationControlled currentPage={page} totalPages={5} onPageChange={setPage} />

مثال با صفحات زیاد

const [page, setPage] = useState(10)

;<PaginationControlled
  currentPage={page}
  totalPages={100}
  onPageChange={setPage}
  siblingCount={2}
  showEllipsis={true}
/>

مثال با دکمه‌های اول و آخر

const [page, setPage] = useState(5)

;<PaginationControlled
  currentPage={page}
  totalPages={20}
  onPageChange={setPage}
  showFirstLast={true}
  siblingCount={1}
/>

مثال بدون دکمه‌های قبلی/بعدی

<PaginationControlled currentPage={page} totalPages={10} onPageChange={setPage} showPrevNext={false} />

راهنمای استفاده

بکنید

  • از PaginationControlled برای اکثر موارد استفاده کنید — ساده‌تر و کامل‌تر است - dir="rtl" را تنظیم کنید تا جهت فلش‌ها در RTL صحیح باشد - از showFirstLast برای جداول با تعداد صفحات زیاد استفاده کنید

نکنید

  • برای داده‌های کم (کمتر از ۱۰ آیتم) از Pagination استفاده نکنید — همه را در یک صفحه نمایش دهید - از Pagination پایه استفاده نکنید مگر نیاز به سفارشی‌سازی عمیق دارید — PaginationControlled کافی است

دسترسی‌پذیری

  • از nav با aria-label="pagination" استفاده می‌شود
  • صفحه فعلی با aria-current="page" مشخص می‌شود
  • دکمه‌های قبلی/بعدی با aria-label مناسب
  • سازگار با RTL و LTR

کامپوننت‌های مرتبط

  • PaginationControlled — وقتی نسخه controlled با مدیریت خودکار state و ellipsis هوشمند نیاز دارید (پیشنهادی)