خالی (Empty)

معرفی

کامپوننت Empty برای نمایش وضعیت خالی بودن استفاده می‌شود: کادر حالت خالی با آیکون، عنوان، توضیح و یک اقدام.

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

• درون جزئی از رابط که حالت خالی‌اش را خودش می‌کشد و قالب صفحه ندارد: پنل کناری، Popover، یک Sheet، یا محتوای یک CustomPage
• در کامپوننتی که prop حالت خالی دارد و فهرست یک صفحه نیست (emptyState در ActionTimeline، empty در EntityCollection، …)، از طریق همان prop

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

• برای فهرست یا جدول یک صفحه — state قالب صفحه (بالا)؛ نه Empty در emptyState جدول
• برای صفحه‌ای که هنوز محتوایی ندارد — UtilityPage kind="empty"
• برای حالت خطا — از ErrorState استفاده کنید (در صفحه: state قالب)
• برای صفحه 404 — UtilityPage kind="404"

زمین بازی

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

استفاده

import { Empty, EmptyIcon, EmptyTitle, EmptyDescription, EmptyAction } from '@partodata/ui'
import { Icons } from '@partodata/ui/icons'

export default function MyComponent() {
  return (
    <Empty>
      <EmptyIcon>
        <Icons.inbox className="h-6 w-6" />
      </EmptyIcon>
      <EmptyTitle>هیچ موردی یافت نشد</EmptyTitle>
      <EmptyDescription>شما هنوز هیچ موردی اضافه نکرده‌اید</EmptyDescription>
    </Empty>
  )
}

کامپوننت‌ها

Empty ترکیبی است: عنوان، توضیح و اقدام فرزند آن هستند، نه ویژگی. <Empty title="…"> از نسخهٔ 4.0 خطای نوع می‌دهد، چون پیش از آن کامپایل می‌شد ولی هیچ عنوانی نمایش نمی‌داد (فقط یک راهنمای شناور HTML). description و action هم ویژگی Empty نیستند؛ از EmptyTitle، EmptyDescription و EmptyAction استفاده کنید.

• Empty — wrapper اصلی با layout عمودی مرکزچین
• EmptyIcon — محل نمایش آیکون؛ رنگِ معناییِ اختیاری دارد (پایین را ببینید)
• EmptyTitle — عنوان وضعیت خالی
• EmptyDescription — توضیح تکمیلی
• EmptyAction — wrapper دکمه اقدام (CTA) با فاصله‌گذاری خودکار

Props

Empty

EmptyIcon

EmptyTitle

EmptyDescription

EmptyAction

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

با دکمه اقدام

<Empty>
  <EmptyIcon>
    <Icons.inbox className="h-6 w-6" />
  </EmptyIcon>
  <EmptyTitle>هنوز منبعی به این پنل افزوده نشده است</EmptyTitle>
  <EmptyDescription>منبعی را که می‌خواهید در این پنل ببینید از فهرست منبع‌ها انتخاب کنید.</EmptyDescription>
  <EmptyAction>
    {/* اقدام حالت خالی ثانوی است (default) و کاری می‌کند: یک handler یا پیوند، هرگز دکمه‌ای بی‌عمل */}
    <Button variant="default" onClick={openSources}>
      انتخاب منبع
    </Button>
  </EmptyAction>
</Empty>

با آیکونِ رنگی

برای وضعیت‌هایی که «خالی بودن» خودش خبرِ خوبی است (مثلاً «هیچ هشداری ثبت نشده») یا نیاز به یک نشانهٔ رنگیِ معنایی دارید، variant را به EmptyIcon بدهید:

import { CheckCircle2 } from 'lucide-react'
;<Empty>
  <EmptyIcon variant="success">
    <CheckCircle2 className="h-6 w-6" />
  </EmptyIcon>
  <EmptyTitle>هیچ هشداری ثبت نشده</EmptyTitle>
  <EmptyDescription>این خوبه — در 24 ساعت گذشته بدون مشکل بوده.</EmptyDescription>
</Empty>

شش مقدار در دسترس است: brand، success، warning، destructive، info، neutral (پیش‌فرض — دقیقاً همان دیسکِ خاکستریِ قبلی، پس این prop تغییری در ظاهرِ کد قبلی ایجاد نمی‌کند).

حالت ساده بدون آیکون

<Empty>
  <EmptyTitle>نتیجه‌ای یافت نشد</EmptyTitle>
  <EmptyDescription>فیلترهای جستجو را تغییر دهید و دوباره تلاش کنید.</EmptyDescription>
</Empty>

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

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

• متن عنوان و توضیحات توسط screen reader خوانده می‌شود
• اگر دکمه اقدام دارید، با Tab قابل دسترسی است
• سازگار با RTL

تصویرها و نمودار خالی

تصویرهای حالت خالی و EmptyChart (حالت خالی داخلی نمودارها) زیرمجموعهٔ همین کامپوننت‌اند. قاعده: یک بلوک → PageState؛ یک صفحهٔ کامل → UtilityPage؛ یک سطح سفارشی → Empty و ErrorState.

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

• ErrorState — وقتی خطایی رخ داده و نیاز به نمایش وضعیت خطا دارید، نه وضعیت خالی
• حالت‌های خالی — راهنمای کامل الگوهای empty state