صفحه‌بندی — Pagination

صفحه‌بندی برای فهرست‌های محدود و شماره‌دار به کار می‌رود که کاربر بین صفحه‌های مشخص حرکت می‌کند. کامپوننت همیشه اولین و آخرین صفحه، صفحهٔ فعلی و هم‌جوارهای آن را نشان می‌دهد و بقیه را با «…» پنهان می‌کند. اگر بدهید هر صفحه لینک واقعی می‌شود (مناسب برای SEO و باز کردن در تب جدید)؛ در غیر این صورت با دکمه‌ها کار می‌کنند. ساختار و ، روی صفحهٔ فعلی و برچسب صفحه ثابت است.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Pagination } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

TSX

import { useState } from 'react';import { Pagination } from '@tokapps/tuk';export function ControlledPagination() {  const [page, setPage] = useState(1);  return <Pagination page={page} pageCount={20} onPageChange={setPage} />;}

TSX

import { Pagination } from '@tokapps/tuk';export function LinkPagination({ currentPage }: { currentPage: number }) {  return (    <Pagination      page={currentPage}      pageCount={8}      siblingCount={2}      hrefFor={(p) => `/forum?page=${p}`}      aria-label="صفحه‌بندی فهرست ایده‌ها"      print="show"    />  );}

TSX

import { useState } from 'react';import { Pagination } from '@tokapps/tuk';// حالت خاص: یک صفحه یا عدد لاتین؛ قبلی و بعدی غیرفعال می‌مانندexport function EdgeCasePagination() {  const [page, setPage] = useState(1);  return (    <>      <Pagination page={page} pageCount={1} onPageChange={setPage} previousLabel="قبلی" nextLabel="بعدی" />      <Pagination page={3} pageCount={9} digits="latin" onPageChange={setPage} />    </>  );}

همهٔ پیکربندی‌ها

پراپ	نوع	پیش‌فرض	توضیح
		— (الزامی)	صفحهٔ فعلی، ۱-مبنا. مقدارهای خارج از بازه به تا محدود می‌شوند.
		— (الزامی)	تعداد کل صفحه‌ها. کمتر از ۱ به تبدیل می‌شود.
		—	فراخوانی با شمارهٔ صفحهٔ مقصد هنگام انتخاب.
		—	اگر داده شود، همه‌چیز لینک واقعی است.
			تعداد صفحه‌های هم‌جوار در دو طرف صفحهٔ فعلی.
			ارقام فارسی یا لاتین برای شماره‌ها.
			متن دکمهٔ قبلی (در موبایل فقط آیکون می‌ماند).
			متن دکمهٔ بعدی (در موبایل فقط آیکون می‌ماند).
		+ شمارهٔ صفحه با	برچسب دسترس‌پذیری هر صفحه.
			برچسب برای صفحه‌خوان.
			پیش‌فرض در چاپ پنهان است.
		— (پیش‌فرض )	رندر لینک با روتر دلخواه؛ از به ارث رسیده است.
		— (پیش‌فرض )	جایگزین ساده‌تر ؛ از به ارث رسیده است.
		—	کلاس اضافی روی .

ساختار و اسلات‌ها

با
- - برای قبلی: با و آیکون (با )
    - (متن قبلی؛ در موبایل پنهان)
  - برای هر عضو بازه: یکی از این دو
    - با و برای صفحهٔ فعلی
    - برای «…»
  - برای بعدی: با و آیکون (با )
    - (متن بعدی؛ در موبایل پنهان)

بنیان ثابت: ترتیب قبلی، صفحه‌ها و «…»، روی صفحهٔ فعلی و منطق بازهٔ صفحه‌ها ().

بخش قابل‌تغییر: متن‌های قبلی و بعدی، برچسب صفحه، ارقام، و نوع لینک.

همهٔ حالت‌ها

حالت	نشانه	نمایش
پیش‌فرض	بدون data-attribute خاص	شمارهٔ صفحه‌ها با رنگ .
hover	روی	پس‌زمینهٔ و رنگ .
current	روی صفحهٔ فعلی	پس‌زمینهٔ ، متن و وزن پررنگ‌تر.
disabled	و (بدون )	قبلی در صفحهٔ اول و بعدی در صفحهٔ آخر؛ رنگ ، بدون واکنش به کلیک، وقتی دارد.
focus-visible	روی لینک	حلقهٔ فوکوس .
ellipsis	و	نمایش «…» بین بازه و ابتدا/انتها.
فشرده (موبایل)	رسانه	متن قبلی و بعدی پنهان؛ فقط آیکون و باقی می‌ماند.
چاپ		در چاپ پنهان است.

کامپوننت حالت‌های loading، invalid و readonly ندارد؛ در کد تعریف نشده‌اند.

تغییرات مجاز برای توسعه‌دهنده

variant: یک ظاهر ().
size: یک اندازه () با هدف لمسی ۴۴ پیکسل.
حالت کار: دکمه با یا لینک با (هر دو قابل ترکیب‌اند تا لینک را بسازد).
بازهٔ نمایش: برای تعداد صفحه‌های هم‌جوار.
ارقام و متن: ، ، و برای ترجمه.
لینک: یا برای روتر.
نقاط توسعه: ، ، توکن‌های (از جمله )، ، .
صدا و handler: رویداد صوتی ندارد؛ کلیک از طریق اعلام می‌شود.

تغییرات ممنوع (بنیان ثابت)

تغییر ترتیب قبلی ← صفحه‌ها ← بعدی یا حذف و .
حذف از صفحهٔ فعلی.
فعال‌کردن موارد غیرفعال با حذف یا .
نمایش «…» در صفحه‌خوان (باید بماند).
هدف لمسی کمتر از ۴۴ پیکسل برای موارد صفحه.
حذف فوکوس مرئی یا انتقال در .

RTL، کیبورد و صفحه‌خوان

RTL: «قبلی» در سمت راست و «بعدی» در سمت چپ قرار می‌گیرد و آیکون‌ها با برمی‌گردند. ارقام پیش‌فرض فارسی‌اند.
کیبورد: بین موارد حرکت می‌کند و یا به صفحه می‌رود. موارد غیرفعال با مشخص‌اند و کلیک‌شان نادیده گرفته می‌شود.
صفحه‌خوان: با (پیش‌فرض «صفحه‌بندی»)، هر صفحه با برچسب «صفحه N»، صفحهٔ فعلی با ، و «…» پنهان از صفحه‌خوان.
هدف لمسی: هر مورد حداقل ۴۴×۴۴ پیکسل ().

صدا، حرکت، چاپ و کاهش حرکت

صدا: بی‌صدا (). prop مربوط به در کد تعریف نشده است.
حرکت: نام معنایی با تغییر و (). با یا تغییر فوری است.
چاپ: پیش‌فرض پنهان (، رنگ تک‌رنگ) (). با در چاپ هم دیده می‌شود.

توکن‌ها

فایل توکن: و مقدارهای مرجع در .
توکن‌های معنایی مصرفی: ، ، ، ، ، ، ، ، ، ، ، ، .
توکن‌های سطح کامپوننت (): ، ، ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

آیکون‌های قبلی و بعدی فقط با و نام معنایی و با رندر می‌شوند؛ مسیر asset در کد مصرف‌کننده نمی‌آید.
تم فقط حرکت و توکن را تغییر می‌دهد؛ ترتیب DOM، ARIA و منطق بازهٔ صفحه‌ها ثابت است.
gesture ندارد؛ کار با کیبورد و pointer یکسان است.

نکات

برای فهرست‌های بی‌پایان از الگوی «بارگذاری بیشتر» با Button استفاده کنید.
برای مراحل ترتیبی یک فرایند از Stepper استفاده کنید.
اگر لینک‌های صفحه‌بندی برای SEO مهم‌اند، حتماً بدهید تا صفحه‌ها لینک واقعی باشند.
برای نمایش مسیر سلسله‌مراتبی صفحه، از درختواره داخل TopBar استفاده کنید؛ صفحهٔ مستقل مسیرنما وجود ندارد.