حالت خطا (ErrorState)

معرفی

کامپوننت ErrorState برای نمایش وضعیت خطا در هنگام بارگذاری داده استفاده می‌شود.

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

• جایی که قالبی حالت را نمی‌کشد (یک Sheet، یک پنل، محتوای یک CustomPage): خطای بارگذاری داده با امکان تلاش مجدد
• وقتی بخشی از چنین جزئی (نه کل صفحه) دچار خطا شده است

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

• برای خطاهای validation فرم — از FormMessage استفاده کنید
• برای اعلان‌های خطای toast — از Sonner استفاده کنید
• برای پیام‌های warning — از Callout استفاده کنید

زمین بازی

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

import { ErrorState } from '@partodata/ui'

<ErrorState title="داده‌ها بارگذاری نشد" message="دوباره تلاش کنید." />

استفاده

import { ErrorState } from '@partodata/ui'
;<ErrorState onRetry={() => refetch()} />

با پیام سفارشی

<ErrorState message="اتصال به سرور ممکن نشد" retryLabel="تلاش دوباره" onRetry={() => refetch()} />

با عنوان

title یک عنوان واقعی (<h3>) بالای پیام می‌سازد، با وزن یگانهٔ عنوان‌ها (600)؛ در اندازهٔ پیش‌فرض نقش عنوان کارت است (14 / 600). پیام متن خواندنی است و از نسخهٔ 4.0 در اندازهٔ متن بدنه (14) نمایش داده می‌شود، نه 12. بدون title، چیدمان همان حالت فقط‌پیام است.

<ErrorState title="بارگذاری گزارش ناموفق بود" message="اتصال به سرور ممکن نشد" onRetry={() => refetch()} />

سطح عنوان به‌طور پیش‌فرض h3 است. با titleAs آن را با ساختار عنوان‌های صفحه هماهنگ کنید: h2 برای خطای کل صفحه که زیر h1 صفحه می‌نشیند، و p داخل کارتی که عنوان خودش را دارد. ظاهر عنوان با titleAs تغییر نمی‌کند.

<ErrorState title="بارگذاری صفحه ناموفق بود" titleAs="h2" size="lg" onRetry={() => reset()} />

محتوای اضافه (children)

هر چه به‌عنوان فرزند بدهید، پس از پیام و دکمهٔ تلاش مجدد نمایش داده می‌شود؛ مثلاً یک اقدام دوم یا یک خط توضیح. فرزندان جای پیام را نمی‌گیرند: متن اصلی را با message بدهید (بدون آن، پیام پیش‌فرض نمایش داده می‌شود).

<ErrorState message="این بخش در حال حاضر در دسترس نیست." onRetry={() => refetch()}>
  <Button variant="outline" onClick={() => router.push('/')}>
    بازگشت به صفحهٔ اصلی
  </Button>
</ErrorState>

اندازه‌ها

<ErrorState size="xs" onRetry={() => {}} />
<ErrorState size="sm" onRetry={() => {}} />
<ErrorState size="md" onRetry={() => {}} />
<ErrorState size="lg" onRetry={() => {}} />
<ErrorState size="xl" onRetry={() => {}} />

عنوان هیچ‌گاه از پیام کوچک‌تر نیست: در xs و sm هم‌اندازهٔ پیام است و وزن 600 آن را جدا می‌کند، و از md یک پله بزرگ‌تر است. آیکون دکمهٔ تلاش مجدد آیکون شروعِ Button است و اندازه و فاصله‌اش را از پلهٔ همان دکمه می‌گیرد.

تا 3٫x پیام در lg و xl بزرگ‌تر بود (16 و 18 پیکسل؛ ErrorBoundary هم پیش‌فرضش lg است). هیچ ویژگی‌ای آن را برنمی‌گرداند؛ اگر جایی لازم است، روی ریشه (یا روی ErrorBoundary) کلاس بدهید: className="[&_[data-slot=error-state-message]]:text-base" برای 16 پیکسل.

بدون دکمه تلاش مجدد

<ErrorState message="خطایی رخ داد" />

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

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

• از role="alert" برای اعلام خطا به screen readers استفاده می‌شود
• دکمه تلاش مجدد با کیبورد قابل دسترسی است
• آیکون خطا دارای aria-hidden است تا screen reader فقط متن را بخواند

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

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

• ErrorBoundary — وقتی می‌خواهید خطاهای runtime React را catch کنید و خودکار ErrorState نمایش دهید
• Callout — وقتی پیام warning یا اطلاعاتی inline نیاز دارید (نه خطای بارگذاری)
• Sonner — وقتی خطا گذرا است و نیاز به اقدام فوری ندارد