الانتقال إلى المحتوى الرئيسي

نظرة عامة

Toast يعرض إشعارًا واحدًا. يتحكم تطبيقك في وقت ظهوره وموضعه ووقت إزالته.

استخدام

خيارات مرئية

قارن بين التغذية الراجعة المحايدة والناجحة والخاطئة والإعلامية والتحذيرية باستخدام الرسالة نفسها والتقدم نفسه. لإشعارات التطبيق، لفّ التطبيق بـ ToastProvider، وثبّت Toaster بداخله، واستخدم useToast() من المكوّنات التابعة. يمتلك كل موفّر مخزن إشعارات مستقلاً، وعدّادات تنازلية، ودورة حياة للإغلاق. يمكن لعدة مكوّنات Toaster أن تعكس الموفّر نفسه.

إشعارات التطبيق

يقبل enqueueToast خصائص Toast ومفتاح dedupeKey اختياريًا، ويعيد معرّف الإشعار. يعيد المفتاح المرئي المطابق المعرّف الحالي دون إضافة إشعار آخر. يُعدّل updateToast({ id, ...changes }) ذلك الإشعار النشط. يرفض closeToast(id) إشعارًا واحدًا؛ ويرفض closeToast() جميع الإشعارات المرئية في الموفّر. يكون الإعداد الافتراضي للموفّر هو ثلاثة إشعارات مرئية. يجب أن يكون limit عدداً صحيحاً موجباً، ويمكن أن يتغير أثناء تثبيت الموفّر. يؤدي خفضه أو الإضافة فوقه إلى إغلاق أقدم الإشعارات المرئية أولاً. تؤدي زيادتها إلى إبقاء الإشعارات الحالية دون تغيير ولا تستعيد الإشعارات المغلقة. تحافظ تغييرات التهيئة على المخزن والمُعرّفات الباقية والترتيب والوقت المتبقي للعد التنازلي.

دورة حياة الموفّر

تعرض عناصر Toaster متعددة داخل موفّر واحد الإشعارات نفسها. تنطبق التحديثات والإغلاق على كل نسخة متطابقة، ولكل إشعار عد تنازلي مشترك واحد. يؤدي التحويم أو التركيز داخل أي نسخة متطابقة إلى إيقافه مؤقتًا؛ ويُستأنف بعد أن تحرر جميع النسخ المتطابقة كليهما. لا تؤدي إضافة Toaster آخر إلى إعادة بدء العد التنازلي أو إنشاء دورة حياة أخرى لرد الاتصال. استخدم موفّرين منفصلين للطوابير المستقلة. بالنسبة إلى إشعارات الموفّر، يستدعي انتهاء الصلاحية وزر الإغلاق وcloseToast والإزالة بسبب الحد أحدث onClose مرة واحدة. يكون الإشعار مغلقًا بالفعل عند تشغيل رد الاتصال، لذا لا تأثير للتحديثات وطلبات الإغلاق المتكررة لهذا المعرّف. يبقى onCancel رد اتصال منفصلًا للإجراء ولا يغلق تلقائيًا. تكون الإشعارات المغلقة غير نشطة أثناء حركات الخروج. تُزال إدخالاتها بعد أن تنهي جميع النسخ المتطابقة المعروضة إجراءات خروجها أو تُفكّك. يؤدي فكّ تركيب آخر Toaster إلى مسح الإدخالات المغلقة وتجميد الوقت المتبقي للإشعارات المرئية. يستأنف إعادة تركيب Toaster ذلك الوقت. يؤدي فكّ تركيب الموفّر إلى تجاهل إشعاراته وإلغاء العد التنازلي وإجراءات الخروج دون استدعاء onClose. لا يكون لعمليات enqueueToast وupdateToast وcloseToast الملتقطة من ذلك الموفّر أي تأثير بعد فكّ تركيبه. يكيّف getToastProps محتوى كل إشعار وطريقة عرضه. عيّن duration وprogress في enqueueToast أو updateToast لكي تشترك كل نسخة متطابقة في تهيئة التوقيت نفسها. تظل تجاوزات التوقيت الحالية عبر getToastProps مدعومة عندما تعرض جميع النسخ المتطابقة المدة والتقدم نفسيهما لإشعار ما. يحتفظ الموفّر بالمعرّف ومعالج الإغلاق والعد التنازلي المشترك. يحدد container وجهة البوابة الخاصة بـ Toaster. عند حذفه، يستخدم حاوية النسق المحيطة أو document.body. يُعرض عنصر صريح هناك؛ ويؤجل null العرض. تبقى الإشعارات المرئية في الطابور، مع إيقاف عدّاداتها التنازلية مؤقتًا عندما لا يكون أي Toaster معروضًا. تحتفظ البوابات بالنسق والاتجاه المحيطين. عيّن aria-label على كل Toaster لتوطين اسم منطقته الافتراضي، “الإشعارات”، ومنح المناطق المتطابقة أسماء مناسبة.

تحديث إشعار مباشر

استخدم المعرّف الذي يعيده enqueueToast لتحديث المحتوى أو حالة الملاحظات أو الإجراءات أو دوال الاستدعاء في مكانها. تحافظ التحديثات على معرّف الإشعار وموضعه. لا يكون للمعرّفات غير المعروفة أو المرفوضة أي تأثير، بما في ذلك أثناء تشغيل حركة الرفض. يستهدف كل استدعاء لـ useToast() أقرب موفّر له.
يتطلب ToastUpdate وجود id ويقبل خيارات Toast جزئية. تحتفظ الحقول المحذوفة بقيمها الحالية. يؤدي undefined الصريح إلى مسح حقل اختياري أو استعادة القيمة الافتراضية للمكوّن، مثل progress: undefined أو status: undefined. مرّر null لإزالة موضع محتوى، بما في ذلك description أو icon أو action. يؤدي ضبط cancelLabel: null إلى إخفاء عنصر التحكم بالإلغاء مع الحفاظ على دالة الاستدعاء الخاصة به. تسري تغييرات دالة الاستدعاء على الإشعار الحالي. ينتمي dedupeKey إلى الإدراج في قائمة الانتظار ولا يمكن تحديثه.

توقيت الإخفاء

يكون العد التنازلي مضبوطًا افتراضيًا على 6,000 مللي ثانية. يتوقف مؤقتًا عندما يكون المؤشر فوق الإشعار المنبثق أو يكون تركيز لوحة المفاتيح داخله، ولا يُستأنف إلا بعد مغادرتهما معًا. مع وجود عناصر Toaster متعددة، تكون حالة الإيقاف المؤقت مشتركة بين نسخها المتطابقة. يتبع العد التنازلي المرئي الوقت المتبقي للإخفاء. يعمل الإخفاء التلقائي أيضًا عندما تؤدي الحركة المخففة إلى تعطيل الرسوم المتحركة. على سبيل المثال، يحافظ updateToast({ id, children: 'Still saving' }) على الوقت المتبقي، بينما يمنح updateToast({ id, duration: 6000 }) القارئ ست ثوانٍ إضافية. تنطبق هذه القواعد على الإشعار الحالي دون تغيير معرّفه أو موضعه.

إشعار قابل للرفض

يتم استدعاء onClose مرة واحدة بواسطة زر الإغلاق أو عند اكتمال العد التنازلي. أزل الإشعار المنبثق في دالة الاستدعاء هذه. استخدم duration={0} لإشعار يبقى مفتوحًا حتى رفضه.

التقدم والإلغاء

يؤدي تمرير progress إلى توفير نسبة مئوية وتعطيل العد التنازلي. أزله بعد انتهاء العملية لبدء مدة جديدة. يستدعي الإلغاء onCancel؛ ويتولى العنصر الأب الإلغاء والإزالة. يقبل cancelLabel عقدة React لمحتوى الزر. تقبل Children وdescription وicon وaction أيضًا عقد React يملكها المستدعي. استخدم عناصر التحكم في واجهة مستخدم Twenty للإجراءات التفاعلية وقدّم أسماءها المتاحة.

المظهر والإعلانات

يقبل status القيم neutral أو info أو success أو warning أو error، وتكون قيمته الافتراضية neutral. يعبّر عن معنى الملاحظات ويختار الأيقونة ولوحة ألوان النسق. لدى Toast مظهر واحد مدعوم، لذا لا يوفّر خيار variant للمظهر أو خيار color للوحة الألوان. استخدم icon لاستبدال الأيقونة، وicon={null} لحذفها، وiconLabel عندما تحتاج الأيقونة الافتراضية إلى اسم متاح خاص بها. الدور الافتراضي هو status مع إعلانات غير ملحّة. استخدم role="alert" للملاحظات العاجلة. عيّن cancelLabel وcloseLabel لترجمة عناصر التحكم، وأتِح وقتًا كافيًا لقراءة المحتوى أو التفاعل مع إجراءاته.

الإزاحة

يتم إنشاء المرجع من أنواع المكوّنات العامة. تستهدف السمات الأصلية والأنماط وأسماء الفئات ومعالجات الأحداث والمراجع العنصر الجذر. استخدم render لتكوين عنصر أو مكوّن آخر مع الاحتفاظ بهذه الخصائص والمرجع. ترث بوابات Toaster النسق المحيط واتجاه النص.
ReactNode
Optional footer node, such as a Button with a caller-owned action.
ReactNode
افتراضي:"Cancel"
Cancel button content node. Defaults to Cancel. Pass null to hide the control.
ReactNode
Main message node. Callers own its content and accessible text.
string
Additional class names merged onto the root.
string
افتراضي:"Close"
Accessible name of the close button. Defaults to Close.
ReactNode
Optional supporting content node rendered below the message.
number
افتراضي:"6000"
Milliseconds before onClose is called, defaulting to 6000. Zero keeps the toast open. Changes restart the countdown; live updateToast duration patches restart it even when unchanged. Hover and keyboard focus pause it until both leave.
ReactNode
Leading icon node. Defaults to the status icon. Pass null to omit it.
string
Accessible name of the default icon. Without it, the icon is decorative.
(() => void)
Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button.
(() => void)
For standalone Toast, called once per mount by the close button or expiry. For provider notifications, called once on close, expiry, closeToast, or limit eviction, after dismissal and before exit cleanup. Provider teardown does not call it.
number
Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration.
Ref<HTMLDivElement>
Ref to the root div, or the element supplied through render.
RenderProp<Record<string, unknown>>
Element or callback composition for the root. Native props and the ref target the rendered element.
"error" | "info" | "neutral" | "success" | "warning"
افتراضي:"neutral"
Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette.
CSSProperties
Inline styles forwarded to the root.

ToastProvider

ReactNode
Application content and any Toasters sharing this provider’s independent notification store and lifecycle.
number
افتراضي:"3"
Reactive maximum number of visible toasts, defaulting to three. Must be a positive integer. Lowering it or adding above it dismisses the oldest visible notifications and calls their onClose once. Surviving IDs, order, and countdowns are preserved.

Toaster

تستهدف سمات div الأصلية والأنماط وأسماء الفئات والمراجع منطقة الإشعارات.
HTMLElement | null
Portal destination. Omit to use the theme container or document.body; null defers rendering. The provider retains visible notifications and pauses their countdowns while no Toaster is rendered.
((toast: ToastNotification) => Partial<Omit<ToastProps, "ref" | "id" | "onClose">>)
Adapts notification content and presentation. The provider owns id, dismissal, and the shared countdown. Set timing through enqueueToast or updateToast; duration and progress overrides must match across Toasters sharing a provider.
RenderProp<Record<string, unknown>>
Custom root element composed through Base UI.