شیمرینگ لودر (ShimmeringLoader)

معرفی

ShimmeringLoader یک پلیس‌هولدر بارگذاری است که یک نوار درخشش باریک روی یک زمینهٔ خاموش به‌آرامی حرکت می‌کند. این کامپوننت نسخهٔ غنی‌تر Skeleton است: به‌جای پالس ساده، یک استریک روشن روی سطح می‌لغزد و همان کیفیت بارگذاری Supabase را می‌دهد. برای حالت‌های بارگذاری هم‌شکل با محتوا (خطوط متن، ردیف‌های جدول، بلوک‌های محتوا) استفاده می‌شود.

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

• برای بارگذاری بلوک‌های محتوا که چند خط یا چند ردیف دارند (خلاصهٔ گزارش، فهرست فعالیت)
• وقتی می‌خواهید حس «در حال آماده‌سازی» فعال‌تری از پالس ساده منتقل کنید
• برای جدول‌ها و کارت‌هایی که در حال دریافت داده هستند — با GenericTableLoader و GenericSkeletonLoader

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

• برای یک پلیس‌هولدر دایره‌ای/تک‌عنصری ساده (آواتار، آیکون) — از Skeleton با shape="circle" استفاده کنید
• وقتی محتوا واقعاً «بارگذاری» نیست بلکه «خالی» است — از Empty استفاده کنید، نه لودر
• برای اسپینر کوتاه‌مدت یک اقدام (کلیک دکمه) — از Spinner استفاده کنید

استفاده

import { ShimmeringLoader, GenericSkeletonLoader, GenericTableLoader } from '@partodata/ui'

export default function LoadingBlock() {
  return (
    <div className="space-y-2">
      <ShimmeringLoader />
      <ShimmeringLoader className="w-3/4" delayIndex={1} />
      <ShimmeringLoader className="w-1/2" delayIndex={2} />
    </div>
  )
}

هر ShimmeringLoader به‌صورت پیش‌فرض یک نوار تمام‌عرض با ارتفاع py-3 است. عرض را با کلاس‌های Tailwind (w-3/4، w-1/2) کنترل کنید و با delayIndex درخشش ردیف‌ها را پلکانی کنید تا استریک از بالا به پایین آبشاری حرکت کند.

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

آبشار پلکانی با delayIndex

هر واحد افزایش delayIndex، شروع درخشش را به‌اندازهٔ animationDelay (پیش‌فرض ۱۵۰ms) عقب می‌اندازد تا ردیف‌ها پشت سر هم روشن شوند.

<div className="space-y-2">
  <ShimmeringLoader delayIndex={0} />
  <ShimmeringLoader delayIndex={1} className="w-3/4" />
  <ShimmeringLoader delayIndex={2} className="w-1/2" />
</div>

GenericSkeletonLoader — بلوک محتوای سه‌خطی

پرکاربردترین حالت «بارگذاری یک بلوک محتوا»: سه خط درخشش با عرض کاهشی که به‌صورت آبشاری روشن می‌شوند.

<GenericSkeletonLoader />

GenericTableLoader — جدول کامل در حال بارگذاری

یک جدول پلیس‌هولدر داخل Card که هر ردیف یک نوار درخشش پلکانی است. سرستون‌ها را با prop headers و تعداد ردیف‌ها را با numRows تعیین کنید.

<GenericTableLoader headers={['کمپین', 'پلتفرم', 'نرخ تعامل', 'وضعیت']} numRows={5} />

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

جدول ویژگی‌ها

ShimmeringLoader

GenericSkeletonLoader

GenericTableLoader

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

• هر لودر role="status"، aria-busy="true" و aria-label="Loading" دارد تا صفحه‌خوان وضعیت بارگذاری را اعلام کند
• ردیف‌های داخلی (خطوط آبشاری، سلول‌های جدول) aria-hidden="true" هستند تا فقط یک اعلان بارگذاری به‌جای ده‌ها عنصر تکراری شنیده شود
• انیمیشن با motion-reduce:animate-none و بلوک سراسری prefers-reduced-motion به یک نوار گرادیان ثابت خنثی تبدیل می‌شود — برای کاربرانی که حرکت را کاهش داده‌اند

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

• Skeleton — اگر یک پلیس‌هولدر پالسی ساده یا یک شکل تکی (دایره/مستطیل) می‌خواهید، از Skeleton استفاده کنید؛ همچنین Skeleton یک variant="shimmer" دارد که همان درخشش را روی یک عنصر تکی می‌دهد
• Spinner — اگر بارگذاری کوتاه‌مدت و بدون شکل محتوا دارید (کلیک دکمه، ارسال فرم)، از Spinner استفاده کنید
• PageLoader — برای بارگذاری کل صفحه پیش از آماده‌شدن محتوا، از PageLoader استفاده کنید