بنر (Banner)

معرفی

کامپوننت Banner برای نمایش اطلاعیه‌های سیستمی، هشدارهای نگهداری، یا پیام‌های مهم در بالای صفحه استفاده می‌شود. برخلاف Alert که درون محتوا قرار می‌گیرد، Banner معمولاً در بالاترین نقطه صفحه قرار دارد.

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

• برای اطلاع‌رسانی نسخه جدید یا قابلیت‌های تازه
• برای هشدار نگهداری سرور یا قطعی سرویس
• برای پیام‌های سیستمی که همه کاربران باید ببینند

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

• برای پیام‌های مرتبط با یک بخش خاص محتوا — از پیام متنی (Callout) استفاده کنید
• برای اعلان‌های موقت پس از یک عملیات — از اعلان (Sonner) استفاده کنید
• برای خطاهای فرم — از فیلد (Field) استفاده کنید

زمین بازی

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

import { Banner } from '@partodata/ui'

<Banner>
  یک پیام مهم برای کاربر.
</Banner>

استفاده

import { Banner } from '@partodata/ui'
;<Banner variant="info">نسخه جدید سامانه منتشر شده است.</Banner>

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

انواع بنر

پنج نوع بنر در دسترس است:

<Banner variant="info">اطلاع‌رسانی</Banner>
<Banner variant="warning">هشدار</Banner>
<Banner variant="destructive">خطا</Banner>
<Banner variant="success">موفقیت</Banner>
<Banner variant="neutral">خنثی</Banner>

قابل رد کردن

با dismissible کاربر می‌تواند بنر را ببندد:

<Banner variant="info" dismissible onDismiss={() => console.log('بسته شد')}>
  این بنر قابل بستن است.
</Banner>

کنترل‌شده (نمایش/عدم‌نمایش از بیرون)

با open و onOpenChange می‌توانید وضعیت نمایش بنر را از بیرون کنترل کنید — مثلاً برای ذخیره‌سازی انتخاب «دیگر نشان نده» در localStorage، یا نمایش دوباره‌ی بنر بدون remount کردن با key جدید:

const [open, setOpen] = React.useState(true)

;<Banner variant="warning" dismissible open={open} onOpenChange={setOpen}>
  سامانه فردا ساعت 2 بامداد به مدت یک ساعت در دسترس نخواهد بود.
</Banner>

با آیکون و اکشن

import { InfoIcon } from 'lucide-react'
;<Banner
  variant="info"
  icon={<InfoIcon className="size-4" />}
  action={
    <Button size="sm" variant="secondary">
      به‌روزرسانی
    </Button>
  }
>
  نسخه جدید در دسترس است.
</Banner>

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

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

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

• بنر یک ناحیه زنده (live region) است، نه لندمارک: نقش آن از روی variant تعیین می‌شود — role="alert" برای warning و destructive و role="status" برای info، success و neutral
• نقش banner در ARIA همان لندمارک سرصفحه سند است و در هر صفحه فقط یکی مجاز است؛ به همین دلیل استفاده نمی‌شود. اگر به نقش دیگری نیاز دارید، می‌توانید آن را با پراپ role بازنویسی کنید
• دکمه بستن دارای aria-label="بستن" است
• با Escape قابل بستن نیست (عمدی — بنر نباید اشتباهاً بسته شود)

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

• اگر اعلان موقت پس از عملیات نیاز دارید → از اعلان (Sonner) استفاده کنید
• اگر پیام متنی ساده درون محتوا نیاز دارید → از پیام متنی (Callout) استفاده کنید