اعلان (Sonner)
سیستم toast برای نمایش اعلان‌های موقت
معرفی
کامپوننت Sonner یک سیستم toast برای نمایش اعلان‌های موقت است. از toast() API برای نمایش پیام و از <Toaster /> در layout برای ثبت محل نمایش استفاده کنید.
چه زمانی استفاده کنیم:
- برای اطلاع‌رسانی‌های گذرا پس از انجام عملیات (ذخیره، ارسال، حذف)
- برای بازخورد سریع که نیاز به اقدام فوری ندارد
- برای نمایش وضعیت عملیات async (بارگذاری، موفقیت، خطا) با
toast.promise()
چه زمانی استفاده نکنیم:
- برای خطاهایی که نیاز به اقدام دارند — از
Alertاستفاده کنید - برای موفقیتی که باید تأیید شود — از
Dialogاستفاده کنید - برای پیام‌های دائمی — toast گذرا است، از
Alertاستفاده کنید
انواع Toast
با توضیحات
با دکمه Action
Promise Toast
با دکمه بستن
نصب
ابتدا Toaster را در layout اصلی خود اضافه کنید:
import { Toaster } from '@parto-system-design/ui'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Toaster />
</body>
</html>
)
}استفاده
import { toast } from '@parto-system-design/ui'
// toast ساده
toast('پیام شما اینجاست')
// toast موفقیت (پس‌زمینه سبز)
toast.success('عملیات موفقیت‌آمیز بود')
// toast خطا (پس‌زمینه قرمز)
toast.error('خطایی رخ داد')
// toast هشدار (پس‌زمینه نارنجی)
toast.warning('این یک هشدار است')
// toast اطلاعات
toast.info('اطلاعاتی برای شما')با توضیحات
toast('رویداد برنامه‌ریزی شد', {
description: 'جلسه شما برای فردا ساعت ۱۰ صبح برنامه‌ریزی شده است',
})با دکمه Action
toast('فایل حذف شد', {
action: {
label: 'بازگردانی',
onClick: () => console.log('بازگردانی'),
},
})Promise Toast
toast.promise(fetch('/api/data'), {
loading: 'در حال بارگذاری...',
success: 'داده‌ها بارگذاری شد',
error: 'خطا در بارگذاری',
})با مدت زمان سفارشی
toast('این پیام ۱۰ ثانیه نمایش داده می‌شود', {
duration: 10000,
})با دکمه بستن
// در layout
;<Toaster closeButton />
// یا برای هر toast خاص
toast('پیام', {
closeButton: true,
})موقعیت
<Toaster position="top-center" />
<Toaster position="top-right" />
<Toaster position="bottom-center" />
<Toaster position="bottom-left" /> {/* پیش‌فرض برای RTL */}با آیکون سفارشی
import { Star } from 'lucide-react'
toast('پیام سفارشی', {
icon: <Star className="size-4" />,
})حذف Toast
const toastId = toast('پیام')
// حذف toast خاص
toast.dismiss(toastId)
// حذف همه
toast.dismiss()راهنمای استفاده
بکنید
- از variant مناسب (
success،error،warning،info) استفاده کنید تا کاربر سریع متوجه نوع پیام شود - برای عملیات قابل بازگشت، دکمهaction(مثلاً «بازگردانی») ارائه دهید -<Toaster />را فقط یک‌بار در layout اصلی قرار دهید
نکنید
- از toast برای خطاهایی که نیاز به اقدام کاربر دارند استفاده نکنید — از
Alertاستفاده کنید - پیام‌های بلند در toast قرار ندهید — ازdescriptionبرای جزئیات استفاده کنید - بیش از یک toast همزمان برای یک عملیات نمایش ندهید
جدول ویژگی‌ها
Toaster
toast options
انواع
| متد | توضیحات | رنگ پس‌زمینه |
|---|---|---|
toast() | پیام عادی | خاکستری |
toast.success() | موفقیت | سبز |
toast.error() | خطا | قرمز |
toast.warning() | هشدار | نارنجی |
toast.info() | اطلاعات | خاکستری |
toast.promise() | با promise | متغیر |
toast.loading() | لودینگ | خاکستری |
toast.custom() | سفارشی | - |
دسترسی‌پذیری
- اعلان‌ها با
role="status"وaria-live="polite"به screen readers اعلام می‌شوند - دکمه بستن و action با کیبورد قابل دسترسی هستند
- انیمیشن‌ها
prefers-reduced-motionرا رعایت می‌کنند - رنگ‌بندی variant ها کنتراست WCAG AA را رعایت می‌کند