بارگذاری صفحه (PageLoader)

معرفی

کامپوننت PageLoader نشانگر بارگذاری مرکزچین برای بارگذاری اولیهٔ یک صفحه یا یک ناحیهٔ بزرگ آن است؛ به‌اندازهٔ ظرفش است (پایین‌تر را ببینید) و با fullScreen کل صفحه را مسدود می‌کند. از کامپوننت Spinner به‌صورت داخلی استفاده می‌کند.

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

• برای بارگذاری بخشی از صفحه — از Skeleton استفاده کنید
• برای بارگذاری داخل modal یا card — از Spinner یا isLoading prop استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

import { PageLoader } from '@partodata/ui'

<PageLoader />

به‌اندازهٔ ظرفش

از نسخهٔ 4.0 لودر (بدون fullScreen) حداقل ارتفاع ثابت ندارد: ارتفاعش 100٪ ظرفش است و flex-1 دارد. پس ظرفی را که ارتفاع دارد پر می‌کند و اسپینر را وسطش می‌گذارد، وقتی تنها فرزند آن ظرف باشد یا فرزند یک ستون flex (زیر یک سربرگ، همان ارتفاعی را می‌گیرد که سربرگ باقی می‌گذارد). در ظرفِ بی‌ارتفاع به‌اندازهٔ اسپینر و پیام با 48 پیکسل فاصلهٔ بالا و پایین است؛ پس در ظرفی کوتاه‌تر از حدود 100 پیکسل جا نمی‌شود و آنجا Spinner درست است. در ظرفِ block با ارتفاع ثابت که سربرگ هم دارد، کل ارتفاع ظرف را می‌گیرد و به‌اندازهٔ سربرگ بیرون می‌زند؛ آن ظرف را ستون flex کنید:

<section className="flex h-80 flex-col">
  <h2 className="text-heading">گزارش هفتگی</h2>
  <PageLoader message="در حال بارگذاری گزارش..." />
</section>

ظاهر 3٫x (حداقل 400 پیکسل) فقط با کلاس برمی‌گردد:

<PageLoader className="h-auto min-h-[400px] flex-initial" />

مثال‌ها

با پیام

<PageLoader message="در حال بارگذاری اطلاعات..." />

تمام‌صفحه با overlay

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

<PageLoader fullScreen message="بارگذاری…" />

در این حالت کل صفحه واقعاً مسدود می‌شود: ورودی ماوس با overlay گرفته می‌شود، فوکوس صفحه‌کلید داخل overlay نگه داشته می‌شود (Tab به عناصر پشت آن نمی‌رسد)، اسکرول بدنه قفل می‌شود و با برداشته‌شدن لودر فوکوس به همان عنصری برمی‌گردد که قبلاً فوکوس داشت.

اندازه‌های مختلف اسپینر

<div className="flex flex-col gap-8">
  <PageLoader spinnerSize="sm" message="اندازه کوچک" />
  <PageLoader spinnerSize="lg" message="اندازه بزرگ" />
  <PageLoader spinnerSize="xl" message="اندازه خیلی بزرگ" />
</div>

Props

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

• دارای role="status" برای اعلام وضعیت به screen reader
• aria-label به‌صورت خودکار از پیام یا متن پیش‌فرض فارسی تنظیم می‌شود
• در حالت fullScreen مقدار aria-busy="true" می‌گیرد و فوکوس صفحه‌کلید داخل overlay محدود می‌شود؛ در غیر این صورت فقط کاربران ماوس مسدود می‌شدند و کاربران صفحه‌کلید همچنان به صفحه تارشده دسترسی داشتند
• با برداشته‌شدن لودر، فوکوس به عنصر قبلی بازگردانده می‌شود تا مسیر کاربر صفحه‌کلید گم نشود
• PageLoader یک dialog نیست؛ اگر کاربر باید در حین انتظار تصمیمی بگیرد یا عملیات را لغو کند، از Dialog استفاده کنید

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

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

• Skeleton — برای بارگذاری بخشی از محتوا
• Spinner — برای اعمال کوتاه