حالت خالی — EmptyState

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

وضعیت: beta · لایه: ۳ (@tokapps/tukکپی کد) · کد: packages/tuk/src/feedback/empty-state/کپی کد

import { EmptyState } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

پایه: عنوان و توضیح

import { EmptyState } from '@tokapps/tuk';export function EmptyIdeas() {  return (    <EmptyState      title="هنوز ایده‌ای ثبت نشده"      description="اولین ایدهٔ خود را با جامعهٔ توکاپس به اشتراک بگذارید."    />  );}

حالت پیشرفته: با کنش

import { Button, EmptyState } from '@tokapps/tuk';export function EmptyIdeasWithAction({ onCreate }: { onCreate: () => void }) {  return (    <EmptyState      title="هنوز ایده‌ای ثبت نشده"      description="اولین ایدهٔ خود را ثبت کنید."      action={<Button onClick={onCreate}>ثبت ایده</Button>}    />  );}

حالت جستجوی بی‌نتیجه: اندازهٔ کوچک، آیکون سفارشی

import { Icon } from '@tokapps/icons';import { EmptyState } from '@tokapps/tuk';export function NoSearchResults() {  return (    <EmptyState      icon={<Icon name="search.empty" size="lg" />}      title="نتیجه‌ای پیدا نشد"      description="عبارت دیگری را جستجو کنید یا فیلترها را بردارید."      size="sm"      headingAs="h2"    />  );}

همهٔ پیکربندی‌ها

ساختار و اسلات‌ها

ترتیب ثابت: div[data-tds="empty-state"]کپی کد ← span[data-part="icon"]کپی کد (اگر iconکپی کد مخالف nullکپی کد) · عنوان با تگ headingAsکپی کد و data-part="title"کپی کد · p[data-part="description"]کپی کد (اگر توضیح باشد) · div[data-part="action"]کپی کد (اگر کنش باشد).

• بنیان ثابت: ترتیب بالا و ارتباط عنوان با ناحیه.
• قابل‌تغییر: آیکون، متن، کنش، اندازه و سطح عنوان.

همهٔ حالت‌ها

تغییرات مجاز برای توسعه‌دهنده

• آیکون: هر ReactNodeکپی کد یا nullکپی کد. برای آیکون معنایی از Iconکپی کد با نام معنایی استفاده کنید.
• اندازه: smکپی کد، mdکپی کد، lgکپی کد.
• سطح عنوان: h2کپی کد، h3کپی کد، h4کپی کد یا pکپی کد.
• محتوا: titleکپی کد، descriptionکپی کد، actionکپی کد (قابل ترجمه).
• چاپ: print="show"کپی کد یا print="hide"کپی کد.
• توکن سطح کامپوننت: --tds-empty-state-gapکپی کد، --tds-empty-state-padding-smکپی کد، --tds-empty-state-padding-mdکپی کد، --tds-empty-state-padding-lgکپی کد، --tds-empty-state-max-widthکپی کد، --tds-empty-state-icon-boxکپی کد، --tds-empty-state-icon-radiusکپی کد.
• نقاط توسعه: classNameکپی کد، data-*کپی کد و ویژگی‌های <div>کپی کد.

تغییرات ممنوع (بنیان ثابت)

• تغییر data-tds="empty-state"کپی کد یا data-sizeکپی کد.
• تغییر ترتیب عنوان، توضیح و کنش.
• حذف عنوان یا استفاده از آیکون به‌جای عنوان.
• استفاده از EmptyState برای خطای بارگذاری (از Alert با کنش «تلاش دوباره» استفاده کنید).
• تعریف رنگ خام؛ رنگ‌ها فقط از توکن معنایی می‌آیند.

RTL، کیبورد و صفحه‌خوان

• RTL: چیدمان وسط‌چین و بدون وابستگی به جهت است.
• کیبورد: خودِ EmptyState فوکوس نمی‌گیرد؛ فقط کنش داخل actionکپی کد فوکوس می‌گیرد و از قرارداد خودش (مثلاً Button) پیروی می‌کند.
• صفحه‌خوان: عنوان با سطح headingAsکپی کد اعلام می‌شود و توضیح خوانده می‌شود. آیکون تزئینی است.
• رنگ: پیام متنی است؛ آیکون فقط تزئین است.

صدا، حرکت، چاپ و کاهش حرکت

• صدا: ندارد.
• حرکت: ندارد؛ کاهش حرکت لازم نیست.
• چاپ: پیش‌فرض showکپی کد با break-inside: avoidکپی کد؛ پیام خالی در چاپ هم معنا دارد.

توکن‌ها

• معنایی: --tds-fg-defaultکپی کد، --tds-fg-mutedکپی کد، --tds-surface-sunkenکپی کد.
• کامپوننتی: --tds-empty-state-*کپی کد (فهرست بالا).
• تایپوگرافی و کنترل: --tds-font-size-smکپی کد، --tds-font-size-lgکپی کد، --tds-font-size-xlکپی کد، --tds-font-weight-semiboldکپی کد، --tds-line-height-normalکپی کد، --tds-control-height-lgکپی کد، --tds-space-2کپی کد.
• مسیر فایل توکن: packages/tokens/src/component/empty-state.cssکپی کد.
• مسیر فهرست توکن مصرفی: packages/tuk/src/feedback/empty-state/EmptyState.tokens.tsکپی کد.

قرارداد ARCH

• آیکون پیش‌فرض با Iconکپی کد و نام معنایی emptyکپی کد ساخته می‌شود؛ مسیر asset در API نیاید.
• تم فقط توکن را تغییر می‌دهد؛ ساختار و سطح عنوان ثابت‌اند.
• EmptyState gesture ندارد.
• کاهش حرکت لازم نیست چون حرکتی ندارد.

نکات

• برای خطا یا هشدار از Toast با کنش «تلاش دوباره» استفاده کنید.
• در حالت بارگذاری از Skeleton استفاده کنید، نه EmptyState.
• اگر کنش اصلی دکمه است، از Button داخل actionکپی کد استفاده کنید.