صفحه‌بندی (Pagination)
صفحه‌بند نتایج — کنترل‌شده یا کنترل‌نشده، با قطعه‌های سازنده برای حالت دست‌ساز
معرفی
کامپوننت Pagination برای ناوبری بین صفحات استفاده می‌شود. دو روش استفاده وجود دارد:
در صفحهٔ فهرست: pagination قالب ListPage
اگر صفحهٔ فهرست به‌دلیل بالا صفحه‌بندی لازم دارد، آن pagination قالب ListPage است
(هر پنج فیلد الزامی، با محدودهٔ «1 تا 25 از 60» زیر فهرست)؛ شمارهٔ صفحه React.useState صفحه است، هرگز نشانی صفحه
(URL). این صفحه برای صفحه‌بندی بیرون از یک صفحهٔ فهرست است.
پیش‌فرض هر فهرست: اسکرول خودکار، نه صفحه‌بندی
فهرست‌ها، فیدها، شبکهٔ کارت‌ها و جدول‌های یک صفحهٔ فهرست با اسکرول کاربر بیشتر بار می‌شوند (loadMore قالب
ListPage با mode: 'infinite'، یا
useInfiniteScroll): شمار «24 از 120»، ردیف آرام بارگذاری، نشانگر پایان و دکمهٔ
«نمایش بیشتر» برای صفحه‌کلید و صفحه‌خوان. صفحه‌بندی دستی فقط وقتی است که زیر فهرست چیز دیگری در همان صفحه هست (بخش
دیگر، جمع‌بندی، فوتر) که کاربر با اسکرول خودکار هرگز به آن نمی‌رسد، یا وقتی پرش به صفحهٔ N خودش کار کاربر است.
چه زمانی استفاده کنیم:
- فهرستی که بخش یا محتوای دیگری زیرش در همان صفحه است (مثلاً جدولی در میانهٔ یک گزارش)
- وقتی پرش به صفحهٔ مشخص کار خود کاربر است (مثلاً «برو به صفحهٔ 12» در یک بایگانی)
چه زمانی استفاده نکنیم:
- فهرستی که آخرین چیز صفحه است: اسکرول خودکار (
loadMore)، نه صفحه‌بندی - وقتی داده‌ها کم هستند (کمتر از 10 آیتم): همه را یک‌جا نشان دهید
ظاهر (7.13): فقط صفحهٔ جاری برجسته است: سطح خنثی، مرز foreground-lighter و متن foreground با وزن 500 (نه
سبز برند). شماره‌های دیگر و «قبلی/بعدی» بی‌مرز و آرام‌اند (foreground-light) و با hover یک سطح خنثی می‌گیرند. تفاوت
صفحهٔ جاری بدون رنگ هم دیده می‌شود (تنها شمارهٔ مرزدار ردیف است) و aria-current="page" دارد.
<Pagination totalPages={…} />: خودِ صفحه‌بند — کنترل‌شده (currentPage+onPageChange) یا کنترل‌نشده (defaultPage). پیشنهادی.- بدون
totalPages: ریشهٔ<nav>قطعه‌های سازنده (PaginationContent،PaginationLink، …) برای صفحه‌بندی دست‌ساز.
زمین بازی
با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.
import { Pagination, PaginationContent, PaginationItem, PaginationPrevious, PaginationNext, PaginationLink, PaginationEllipsis } from '@partodata/ui'
<Pagination>
<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><PaginationLink href="#">10</PaginationLink></PaginationItem>
<PaginationItem><PaginationNext href="#" /></PaginationItem>
</PaginationContent>
</Pagination>استفاده با totalPages (پیشنهادی)
Pagination با totalPages کل صفحه‌بند را می‌سازد:
Playground
در playground زیر می‌توانید props مختلف را تست کنید:
import { Pagination } from '@partodata/ui'
import { useState } from 'react'
export default function MyComponent() {
const [currentPage, setCurrentPage] = useState(2)
return <Pagination currentPage={currentPage} totalPages={10} onPageChange={setCurrentPage} />
}مثال با props اضافی
import { Pagination } from '@partodata/ui'
export default function MyComponent() {
const [page, setPage] = useState(5)
return (
<Pagination
currentPage={page}
totalPages={20}
onPageChange={setPage}
siblingCount={2} // تعداد صفحات در هر طرف صفحه فعلی
showFirstLast={true} // نمایش دکمه‌های اول و آخر
showPrevNext={true} // نمایش دکمه‌های قبلی و بعدی
showEllipsis={true} // نمایش ellipsis برای صفحات مخفی
locale="fa" // زبان و جهت (fa/ar → rtl)
/>
)
}استفاده دستی با Pagination
برای کنترل بیشتر، می‌توانید از کامپوننت‌های پایه استفاده کنید:
import {
Pagination,
PaginationContent,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
PaginationEllipsis,
} from '@partodata/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
Pagination (با totalPages)
defaultPage (پیش‌فرض 1) صفحهٔ شروع حالت کنترل‌نشده است؛ با currentPage کنترل‌شده می‌شود.
PaginationLink
PaginationPrevious / PaginationNext
حالت‌ها و انواع
مثال ساده
const [page, setPage] = useState(1)
;<Pagination currentPage={page} totalPages={5} onPageChange={setPage} />مثال با صفحات زیاد
const [page, setPage] = useState(10)
;<Pagination currentPage={page} totalPages={100} onPageChange={setPage} siblingCount={2} showEllipsis={true} />مثال با دکمه‌های اول و آخر
const [page, setPage] = useState(5)
;<Pagination currentPage={page} totalPages={20} onPageChange={setPage} showFirstLast={true} siblingCount={1} />مثال بدون دکمه‌های قبلی/بعدی
<Pagination currentPage={page} totalPages={10} onPageChange={setPage} showPrevNext={false} />راهنمای استفاده
بکنید
- صفحه‌بندی را فقط وقتی بگذارید که زیر فهرست بخش دیگری هست؛ وگرنه اسکرول خودکار (
loadMore) - ازPaginationباtotalPagesاستفاده کنید، ساده‌تر و کامل‌تر است -localeرا تنظیم کنید (fa/ar→ RTL) تا جهت فلش‌ها صحیح باشد؛ پیش‌فرضfaاست - ازshowFirstLastبرای جداول با تعداد صفحات زیاد استفاده کنید
نکنید
- فهرستی را که آخرین چیز صفحه است صفحه‌بندی نکنید - برای داده‌های کم (کمتر از 10 آیتم) از Pagination استفاده نکنید،
همه را یک‌جا نشان دهید - قطعه‌های سازنده را دستی نچینید مگر نیاز به سفارشی‌سازی عمیق دارید - به
PaginationLinkرنگ برند یا مرز برای همهٔ شماره‌ها ندهید: فقط صفحهٔ جاری برجسته است
دسترسی‌پذیری
- از
navباaria-label="pagination"استفاده می‌شود - صفحه فعلی با
aria-current="page"مشخص می‌شود - دکمه‌های قبلی/بعدی با
aria-labelمناسب PaginationEllipsisبرچسبِ پنهانِ «صفحه‌های بیشتر» (در حالتِ LTR: «More pages») دارد تا صفحه‌خوان بداند صفحه‌هایی جا افتاده‌اند؛ فقط آیکونaria-hiddenاست- سازگار با RTL و LTR