اسکلتون (Skeleton)

معرفی

کامپوننت Skeleton برای نمایش وضعیت لودینگ استفاده می‌شود.

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

• برای نمایش placeholder محتوا هنگام بارگذاری اولیه صفحه
• وقتی layout محتوا از قبل مشخص است و می‌خواهید layout shift را حذف کنید
• برای عملیات‌هایی که بیش از ۲۰۰ms طول می‌کشند

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

• برای عملیات‌های کوتاه‌تر از ۲۰۰ms — نمایش skeleton و حذف آن ناگهانی به نظر می‌رسد
• برای حالت‌های خطا — از ErrorState استفاده کنید
• برای نمودارها — از prop isLoading در کامپوننت نمودار استفاده کنید

زمین بازی

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

استفاده

import { Skeleton } from '@partodata/ui'

export default function MyComponent() {
  return (
    <div className="flex flex-col gap-3">
      <Skeleton className="h-12 w-12 rounded-full" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-[250px]" />
        <Skeleton className="h-4 w-[200px]" />
      </div>
    </div>
  )
}

اشکال مختلف

از prop shape برای تعیین شکل اسکلتون استفاده کنید:

<Skeleton shape="rect" className="h-12 w-full" />
<Skeleton shape="circle" size="lg" />
<Skeleton shape="line" />
<Skeleton shape="text" />

تکرار

از prop count برای نمایش چند اسکلتون پشت سر هم استفاده کنید:

<Skeleton shape="line" count={3} />

پریست‌های آماده

هفت پریست آماده برای استفاده سریع:

import {
  MetricCardSkeleton,
  ChartSkeleton,
  TableSkeleton,
  TableRowSkeleton,
  CardSkeleton,
  AvatarTextSkeleton,
  FormRowSkeleton,
} from '@partodata/ui';

<MetricCardSkeleton />
<ChartSkeleton />
<TableSkeleton rows={5} />
<TableRowSkeleton cells={4} />
<CardSkeleton withImage bodyLines={2} withFooter />
<AvatarTextSkeleton size="md" lines={2} />
<FormRowSkeleton field="input" withHelp />

Props

Skeleton

MetricCardSkeleton

اسکلتون آماده برای MetricCard. بدون props اضافی.

ChartSkeleton

اسکلتون آماده برای نمودارها. بدون props اضافی.

TableSkeleton

TableRowSkeleton

یک ردیف skeleton برای درج در جدول موجود.

CardSkeleton

اسکلتون کارت با عنوان، خطوط بدنه و تصویر/فوتر اختیاری.

AvatarTextSkeleton

اسکلتون آواتار دایره‌ای به‌همراه چند خط متن (سبک لیست/نظر).

FormRowSkeleton

اسکلتون یک ردیف فرم شامل label و placeholder ورودی.

واریانت shimmer و انتخاب بین Skeleton و ShimmeringLoader

Skeleton دو idiom دارد: pulse (پیش‌فرض، پالس ثابت — بدون تغییر برای همهٔ مصرف‌کننده‌های موجود) و shimmer که همان درخشش متحرک کامپوننت ShimmeringLoader را روی یک عنصر تکی می‌دهد.

<Skeleton variant="shimmer" className="h-4 w-40" />

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

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

• ریشهٔ Skeleton دارای role="status"، aria-busy="true" و aria-label="Loading" است تا فناوری کمکی وضعیت «در حال بارگذاری» را اعلام کند
• aria-hidden="true" فقط روی شکل‌های تکرارشونده (وقتی count بزرگ‌تر از ۱ است) و شکل‌های داخلی پریست‌ها اعمال می‌شود تا شکل‌های تزئینی نادیده گرفته شوند
• انیمیشن pulse در صورت فعال بودن prefers-reduced-motion: reduce غیرفعال می‌شود
• محتوای واقعی پس از بارگذاری جایگزین Skeleton می‌شود بدون تغییر layout

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

• Spinner — اگر عملیات کوتاه است و layout محتوا مشخص نیست، از Spinner استفاده کنید
• ErrorState — اگر بارگذاری با خطا مواجه شد، از ErrorState استفاده کنید
• ShimmeringLoader — برای بلوک‌های محتوای چندخطی/جدول با درخشش آبشاری، از ShimmeringLoader استفاده کنید (نسخهٔ غنی‌تر همین درخشش)