اسکلتون (Skeleton)

معرفی

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

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

• برای placeholder محتوا جایی که قالبی حالت را نمی‌کشد (یک Sheet، یک پنل، محتوای یک CustomPage)
• وقتی layout محتوا از قبل مشخص است و می‌خواهید layout shift را حذف کنید
• برای عملیات‌هایی که بیش از 200ms طول می‌کشند

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

• برای عملیات‌های کوتاه‌تر از 200ms — نمایش 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.

ChartSkeleton

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

TableSkeleton

TableRowSkeleton

یک ردیف skeleton برای درج در جدول موجود. سلول‌هایش تراکم همان جدول را می‌گیرند (ردیف 44 پیکسل، در جدول compact 36).

CardSkeleton

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

AvatarTextSkeleton

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

FormRowSkeleton

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

واریانت shimmer، و یک پاسخ برای بارگذاری

Skeleton دو حالت انیمیشن دارد: pulse (پیش‌فرض) و shimmer (درخشش متحرک).

<Skeleton variant="shimmer" className="h-4 w-40" />
<Skeleton variant="shimmer" shape="line" count={3} />

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

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

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

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

• Spinner — اگر عملیات کوتاه است و layout محتوا مشخص نیست، از Spinner استفاده کنید
• ErrorState — اگر بارگذاری با خطا مواجه شد، از ErrorState استفاده کنید
• PageState — بارگذاری، خالی و خطای یک بلوک در یک جا