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

ناوبری بین صفحات با دکمه‌های قبلی، بعدی و شماره صفحه با پشتیبانی کامل از RTL

نصب (Installation)

1npx @quark-lab/rad-ui add pagination

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

صفحه‌بندی کامل با دکمه‌های قبلی، بعدی، شماره صفحات و بیضی

مشاهده کد
1import {
2  Pagination,
3  PaginationContent,
4  PaginationEllipsis,
5  PaginationItem,
6  PaginationLink,
7  PaginationNext,
8  PaginationPrevious,
9} from "@/components/ui/pagination";
10
11export default function BasicExample() {
12  return (
13    <Pagination>
14      <PaginationContent>
15        <PaginationItem>
16          <PaginationPrevious href="#" />
17        </PaginationItem>
18        <PaginationItem>
19          <PaginationLink href="#">۱</PaginationLink>
20        </PaginationItem>
21        <PaginationItem>
22          <PaginationLink href="#" isActive>
23            ۲
24          </PaginationLink>
25        </PaginationItem>
26        <PaginationItem>
27          <PaginationLink href="#">۳</PaginationLink>
28        </PaginationItem>
29        <PaginationItem>
30          <PaginationEllipsis />
31        </PaginationItem>
32        <PaginationItem>
33          <PaginationNext href="#" />
34        </PaginationItem>
35      </PaginationContent>
36    </Pagination>
37  );
38}
39

ساده (Simple)

فقط شماره صفحات بدون دکمه‌های قبلی و بعدی

مشاهده کد
1import {
2  Pagination,
3  PaginationContent,
4  PaginationItem,
5  PaginationLink,
6} from "@/components/ui/pagination";
7
8export default function SimpleExample() {
9  return (
10    <Pagination>
11      <PaginationContent>
12        <PaginationItem>
13          <PaginationLink href="#">۱</PaginationLink>
14        </PaginationItem>
15        <PaginationItem>
16          <PaginationLink href="#" isActive>
17            ۲
18          </PaginationLink>
19        </PaginationItem>
20        <PaginationItem>
21          <PaginationLink href="#">۳</PaginationLink>
22        </PaginationItem>
23        <PaginationItem>
24          <PaginationLink href="#">۴</PaginationLink>
25        </PaginationItem>
26        <PaginationItem>
27          <PaginationLink href="#">۵</PaginationLink>
28        </PaginationItem>
29      </PaginationContent>
30    </Pagination>
31  );
32}
33

فقط آیکون (Icons Only)

فقط دکمه‌های قبلی و بعدی — مناسب برای جداول داده با انتخاب تعداد در هر صفحه

مشاهده کد
1import { Field, FieldLabel } from "@/components/ui/field";
2import {
3  Pagination,
4  PaginationContent,
5  PaginationItem,
6  PaginationNext,
7  PaginationPrevious,
8} from "@/components/ui/pagination";
9import {
10  Select,
11  SelectContent,
12  SelectGroup,
13  SelectItem,
14  SelectTrigger,
15  SelectValue,
16} from "@/components/ui/select";
17
18export default function IconsOnlyExample() {
19  return (
20    <div className="flex items-center justify-between gap-4">
21      <Field orientation="horizontal" className="w-fit">
22        <FieldLabel htmlFor="select-rows-per-page">تعداد در هر صفحه</FieldLabel>
23        <Select defaultValue="25">
24          <SelectTrigger className="w-20" id="select-rows-per-page">
25            <SelectValue />
26          </SelectTrigger>
27          <SelectContent align="start">
28            <SelectGroup>
29              <SelectItem value="10">۱۰</SelectItem>
30              <SelectItem value="25">۲۵</SelectItem>
31              <SelectItem value="50">۵۰</SelectItem>
32              <SelectItem value="100">۱۰۰</SelectItem>
33            </SelectGroup>
34          </SelectContent>
35        </Select>
36      </Field>
37      <Pagination className="mx-0 w-auto">
38        <PaginationContent>
39          <PaginationItem>
40            <PaginationPrevious href="#" />
41          </PaginationItem>
42          <PaginationItem>
43            <PaginationNext href="#" />
44          </PaginationItem>
45        </PaginationContent>
46      </Pagination>
47    </div>
48  );
49}
50

مرجع API (API Reference)

Pagination

کامپوننت اصلی صفحه‌بندی

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestringundefinedکلاس‌های CSS سفارشی
dir"ltr" | "rtl"undefinedجهت متن برای RTL

PaginationLink

لینک شماره صفحه

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
hrefstring-آدرس لینک صفحه
isActivebooleanfalseنمایش صفحه فعلی
size"sm" | "md" | "lg""md"اندازه دکمه
classNamestringundefinedکلاس‌های CSS سفارشی

PaginationPrevious

دکمه صفحه قبلی

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
textstring"قبلی"متن دکمه قبلی (برای i18n)
hrefstring-آدرس صفحه قبلی
size"sm" | "md" | "lg""md"اندازه دکمه
classNamestringundefinedکلاس‌های CSS سفارشی

PaginationNext

دکمه صفحه بعدی

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
textstring"بعدی"متن دکمه بعدی (برای i18n)
hrefstring-آدرس صفحه بعدی
size"sm" | "md" | "lg""md"اندازه دکمه
classNamestringundefinedکلاس‌های CSS سفارشی

دسترسی‌پذیری (Accessibility)

نقش و برچسب (Role & Labeling)

کامپوننت از عنصر nav با role="navigation" و aria-label استفاده می‌کند. دکمه‌های قبلی و بعدی دارای aria-label مناسب هستند.

صفحه فعلی (Current Page)

برای صفحه فعلی از aria-current="page" استفاده می‌شود تا صفحه‌خوان‌ها بتوانند موقعیت کاربر را تشخیص دهند.

کیبورد (Keyboard)

تمام لینک‌ها با Tab قابل دسترسی هستند و با Enter فعال می‌شوند. حلقه فوکوس واضح برای ناوبری با کیبورد وجود دارد.

بهترین شیوه‌ها (Best Practices)

لینک‌های معنادار (Meaningful Links)

همیشه از href معتبر برای هر صفحه استفاده کنید تا کاربران بتوانند لینک را باز کنند یا ذخیره کنند. از # برای صفحات غیرفعال استفاده نکنید.

بیضی (Ellipsis)

برای لیست‌های طولانی از PaginationEllipsis استفاده کنید تا تعداد صفحات نمایش داده شده محدود شود و رابط کاربری تمیز بماند.

بین‌المللی‌سازی (i18n)

از propهای text در PaginationPrevious و PaginationNext برای ترجمه متن دکمه‌ها استفاده کنید. مقادیر پیش‌فرض به فارسی هستند.

جداول داده (Data Tables)

برای جداول با تعداد زیاد ردیف، از ترکیب Pagination با Select برای انتخاب تعداد در هر صفحه استفاده کنید (مثال فقط آیکون).

نحوه استفاده (Usage)

1import {
2  Pagination,
3  PaginationContent,
4  PaginationEllipsis,
5  PaginationItem,
6  PaginationLink,
7  PaginationNext,
8  PaginationPrevious,
9} from "@/components/ui/pagination";
10
11export default function Example() {
12  return (
13    <Pagination>
14      <PaginationContent>
15        <PaginationItem>
16          <PaginationPrevious href="/page/1" />
17        </PaginationItem>
18        <PaginationItem>
19          <PaginationLink href="/page/1">۱</PaginationLink>
20        </PaginationItem>
21        <PaginationItem>
22          <PaginationLink href="/page/2" isActive>
23            ۲
24          </PaginationLink>
25        </PaginationItem>
26        <PaginationItem>
27          <PaginationLink href="/page/3">۳</PaginationLink>
28        </PaginationItem>
29        <PaginationItem>
30          <PaginationEllipsis />
31        </PaginationItem>
32        <PaginationItem>
33          <PaginationNext href="/page/3" />
34        </PaginationItem>
35      </PaginationContent>
36    </Pagination>
37  );
38}
39