کامپوننت‌ها
اعلان کوتاه
پیام کوتاه و موقت پس از یک عمل، مثل «ذخیره شد»؛ با توقف هنگام hover و امکان واگرد.
import { Toaster, toast } from "@kashi-ui/react";<Toaster /> را یک بار در ریشهٔ برنامه بگذارید؛ سپس از هر جای برنامه toast() را صدا بزنید.
نمونه
toast.success("تغییرات ذخیره شد", { description: "…" });
toast.error("پرداخت ناموفق بود");
toast.warning("اتصال اینترنت ناپایدار است");
toast({
title: "پیام بایگانی شد",
action: { label: "واگرد", onClick: () => restore() },
});
// در ریشهٔ برنامه
<Toaster />رفتار
- زمان: پیش‌فرض ۵ ثانیه. نوار پایین زمان باقی‌مانده را نشان می‌دهد و با hover یا فوکوس متوقف می‌شود.
- با عمل: اعلانی که دکمه دارد (مثل «واگرد») خودکار بسته نمی‌شود تا کاربر فرصت کافی داشته باشد.
- بستن: با دکمهٔ بستن یا Esc وقتی فوکوس روی اعلان است.
کار زمان‌بر و جایگاه
toast.promise اعلان «در حال ذخیره…» را نشان می‌دهد و پس از پایان کار، همان اعلان را به پیام موفقیت یا خطا تغییر می‌دهد. (در این نمونه از هر چهار بار، حدود یک بار خطا شبیه‌سازی می‌شود.)
toast.promise(saveFiles(), {
loading: "در حال ذخیره…",
success: (n) => `${n} فایل ذخیره شد`,
error: (e) => `ذخیره نشد: ${e.message}`,
});
<Toaster placement="top-center" max={3} />| نام | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
placement (Toaster) | "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end" | "bottom-end" | جایگاه؛ در RTL «end» سمت چپ است |
max (Toaster) | number | 5 | بیشترین اعلان هم‌زمان |
toast.promise | (promise, { loading, success, error }) | — | اعلان یک کار زمان‌بر |
id (toast) | number | string | — | با شناسهٔ تکراری، اعلان قبلی به‌روز می‌شود |
ویژگی‌های toast()
| نام | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
title | ReactNode | — | متن اصلی |
description | ReactNode | — | توضیح |
tone | "neutral" | "success" | "error" | "warning" | "info" | "neutral" | رنگ و آیکون |
duration | number | ۵۰۰۰، یا بی‌نهایت با action | میلی‌ثانیه |
action | { label, onClick } | — | دکمهٔ عمل |
دسترس‌پذیری
- ناحیهٔ اعلان‌ها با
aria-live="polite"از ابتدا در صفحه است تا اعلان‌های جدید بدون جابه‌جایی فوکوس خوانده شوند؛ اعلان خطا باrole="alert"فوراً خوانده می‌شود. - توقف زمان هنگام hover و فوکوس و ماندن اعلان‌های دارای عمل، معیار WCAG 2.2.1 (زمان کافی) را برآورده می‌کنند.
- اطلاعات حیاتی را فقط در اعلان کوتاه نگذارید؛ ممکن است کاربر آن را نبیند.