SDAIA

الإشعار المنبثق

الإشعار المنبثق رسالة قصيرة ومؤقتة تؤكّد نتيجة إجراء مثل الحفظ أو الحذف أو الإرسال. يظهر عند حافة الشاشة ويُغلق نفسه دون أن يقاطع المستخدم.

التثبيت

npx sdaia-ui@latest add toast

الاستخدام

import { Toast, ToastProvider, useToast } from '@/components/ui/Toast';
1<Toast
2  type="success"
3  title="تم حفظ التغييرات"
4  message="تم حفظ التغييرات الخاصة بك بنجاح."
5  actionLabel="تراجع"
6  onAction={undo}
7  onClose={() => setOpen(false)}
8  labels={{ close: "إغلاق" }}
9/>
1const toast = useToast();
2toast.show({ type: "success", title: "تم حفظ السجل", actionLabel: "تراجع", onAction: undo });

أمثلة

الافتراضي

عنوان ورسالة وإجراء واحد وزر الإغلاق. يُغلق الإشعار نفسه بعد خمس ثوانٍ، ويتوقف المؤقت عند تمرير المؤشر أو التركيز عليه.

جارٍ تحميل العرض التوضيحي: toast-default

الأنواع

خمسة أنواع يجمع كل منها بين لون وأيقونة لتتضح النتيجة بنظرة.

جارٍ تحميل العرض التوضيحي: toast-types

محايد

معلومة عامة ليست خبراً جيداً أو سيئاً.

جارٍ تحميل العرض التوضيحي: toast-neutral

معلومات

سياق مفيد عمّا يفعله النظام.

جارٍ تحميل العرض التوضيحي: toast-info

نجاح

اكتمل الإجراء كما هو متوقع.

جارٍ تحميل العرض التوضيحي: toast-success

تحذير

نجح الإجراء لكنه يحتاج إلى انتباه.

جارٍ تحميل العرض التوضيحي: toast-warning

خطأ

فشل الإجراء. أرفقه بإجراء لإعادة المحاولة. يبقى إشعار الخطأ حتى يغلقه المستخدم.

جارٍ تحميل العرض التوضيحي: toast-error

العنوان فقط

الرسالة والإجراء اختياريان.

جارٍ تحميل العرض التوضيحي: toast-title-only

ToastProvider و useToast

اعرض الإشعارات من أي مكان داخل المزوّد. تظهر في الزاوية السفلية عند نهاية الشاشة، واحداً تلو الآخر؛ ينتظر الإشعار التالي حتى يُغلق الحالي.

جارٍ تحميل العرض التوضيحي: toast-provider

العربية (من اليمين إلى اليسار)

ينعكس التخطيط ويُقرأ من اليمين إلى اليسار.

جارٍ تحميل العرض التوضيحي: toast-rtl

متى تستخدمه

استخدم الإشعار المنبثق لـ:

  • تأكيد الحفظ أو الحذف أو الإرسال
  • إتاحة تراجع سريع بعد إجراء
  • الإبلاغ عن انتهاء مهمة في الخلفية
  • تحديثات الحالة منخفضة الأهمية

لا تستخدمه لـ:

  • الأخطاء التي تمنع إكمال المهمة: استخدم تنبيهاً داخل الصفحة
  • الرسائل التي تتطلب قراراً: استخدم نافذة حوار
  • المحتوى الطويل أو المفصّل
  • عرض عدة إشعارات فوق بعضها في وقت واحد

أفضل الممارسات

  • اجعل الرسالة قصيرة: قل ما حدث في جملة واحدة، فالإشعار يُغلق بعد نحو خمس ثوانٍ.
  • طابق النوع مع الرسالة: النجاح للإجراءات المكتملة، والتحذير لما يحتاج إلى مراجعة، والخطأ للإخفاق.
  • امنح المستخدم التحكم: أتِح إجراءً واحداً مثل التراجع وأبقِ زر الإغلاق متاحاً.

الخصائص

Toast

الخاصية

النوع

القيمة الافتراضية

مطلوبة

type

"neutral" | "info" | "success" | "warning" | "error"

"neutral"

اختيارية

title

ReactNode

—

مطلوبة

message

ReactNode

—

اختيارية

actionLabel

ReactNode

—

اختيارية

onAction

(event) => void

—

اختيارية

actionHref

string

—

اختيارية

closeButton

boolean

true

اختيارية

onClose

(reason: "timeout" | "close-button" | "escape" | "action") => void

—

اختيارية

duration

number | null

5000

اختيارية

dir

"ltr" | "rtl"

—

اختيارية

labels

{ close?: string }

{ close: "Close" }

اختيارية

ToastProvider

الخاصية

النوع

القيمة الافتراضية

مطلوبة

placement

"top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end"

"bottom-end"

اختيارية

limit

number

1

اختيارية

hotkey

string | null

"F8"

اختيارية

dir

"ltr" | "rtl"

—

اختيارية

labels

{ region?: string; close?: string }

{ region: "Notifications", close: "Close" }

اختيارية

useToast()

الخاصية

النوع

القيمة الافتراضية

مطلوبة

show

(options: ToastProps & { id?: string }) => string

—

اختيارية

dismiss

(id?: string) => void

—

اختيارية

إمكانية الوصول

  • تُعلَن إشعارات المحايد والمعلومات والنجاح والتحذير بهدوء (role="status")، وتُعلَن إشعارات الخطأ فوراً (role="alert"). يُقرأ العنوان والرسالة فقط.
  • لا يأخذ الإشعار التركيز أبداً. يصل مفتاح Tab إلى الإجراء وزر الإغلاق، ومع ToastProvider ينقل المفتاح F8 التركيز إلى الإشعارات.
  • يُغلق مفتاح Escape الإشعار الذي عليه التركيز، ويعود التركيز إلى حيث كان المستخدم.
  • لا تقل المدة عن خمس ثوانٍ، ويتوقف المؤقت عند تمرير المؤشر أو التركيز أو إخفاء الصفحة. إشعارات الخطأ لا تُغلق نفسها.
  • اسم زر الإغلاق «Close» قابل للترجمة، وحجمه 32 × 32 بكسل. يظهر النوع بالأيقونة والعنوان وليس باللون وحده.

السلوك المتجاوب

  • أقصى عرض للإشعار 420 بكسل ويتقلص ليناسب شاشة الهاتف؛ تلتف الرسائل الطويلة ويزداد ارتفاع الإشعار.
  • يحافظ ToastProvider على مسافة 16 بكسل من حواف الشاشة في كل العروض.
  • تتبع أحجام النصوص والمسافات والأيقونات الرموز المتجاوبة العامة.
هياكل الصور الرمزية
تلميح الأداة