اعلان (Sonner)
سیستم toast برای نمایش اعلان‌های موقت
معرفی
کامپوننت Sonner یک سیستم toast برای نمایش اعلان‌های موقت است. از toast() API برای نمایش پیام و از <Toaster /> در layout برای ثبت محل نمایش استفاده کنید.
چه زمانی استفاده کنیم:
- برای اطلاع‌رسانی‌های گذرا پس از انجام عملیات (ذخیره، ارسال، حذف)
- برای بازخورد سریع که نیاز به اقدام فوری ندارد
- برای نمایش وضعیت عملیات async (بارگذاری، موفقیت، خطا) با
toast.promise()
چه زمانی استفاده نکنیم:
- برای خطاهایی که نیاز به اقدام دارند — از
Alertاستفاده کنید - برای موفقیتی که باید تأیید شود — از
Dialogاستفاده کنید - برای پیام‌های دائمی — toast گذرا است، از
Alertاستفاده کنید
زمین بازی
با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.
زمین بازی
تنظیمات
ظاهر
محتوا
کد این نمونه به‌صورت خودکار قابل تولید نیست — برای کد آماده‌ی copy/paste به بخش «استفاده» در بالای صفحه مراجعه کنید.
انواع 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 را رعایت می‌کند