> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# إشعار منبثق

> اعرض رسائل الحالة مع تفاصيل وإجراءات وتقدم اختيارية.

## نظرة عامة

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

**Light**

[مثال على الإشعار المنبثق (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toast--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على الإشعار المنبثق (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toast--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toast--display)

## استخدام

```tsx theme={null}
import { useState } from 'react';
import { Toast } from 'twenty-ui/components/feedback';
import { Button } from 'twenty-ui/primitives/input';

export const SavedNotification = () => {
  const [isOpen, setIsOpen] = useState(true);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Show notification</Button>
      {isOpen && (
        <Toast status="success" progress={100} onClose={() => setIsOpen(false)}>
          Changes saved
        </Toast>
      )}
    </>
  );
};
```

## خيارات مرئية

قارن بين التغذية الراجعة المحايدة والناجحة والخاطئة والإعلامية والتحذيرية باستخدام الرسالة نفسها والتقدم نفسه.

**Light**

[حالات التغذية الراجعة للإشعار المنبثق (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toast--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[حالات التغذية الراجعة للإشعار المنبثق (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toast--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toast--catalog)

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

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

```tsx theme={null}
import { useState } from 'react';

import {
  ToastProvider,
  Toaster,
  useToast,
} from 'twenty-ui/components/feedback';
import { Button } from 'twenty-ui/primitives/input';

const SaveNotificationButton = () => {
  const { enqueueToast } = useToast();

  return (
    <Button
      onClick={() =>
        enqueueToast({
          children: 'Record saved',
          status: 'success',
        })
      }
    >
      Add saved notification
    </Button>
  );
};

export const Notifications = () => {
  const [limit, setLimit] = useState(3);

  return (
    <ToastProvider limit={limit}>
      <SaveNotificationButton />
      <Button onClick={() => setLimit(1)}>Keep one notification</Button>
      <Button onClick={() => setLimit(3)}>Keep three notifications</Button>
      <Toaster />
    </ToastProvider>
  );
};
```

يقبل `enqueueToast` خصائص Toast ومفتاح `dedupeKey` اختياريًا، ويعيد معرّف الإشعار. يعيد المفتاح المرئي المطابق المعرّف الحالي دون إضافة إشعار آخر. يُعدّل `updateToast({ id, ...changes })` ذلك الإشعار النشط. يرفض `closeToast(id)` إشعارًا واحدًا؛ ويرفض `closeToast()` جميع الإشعارات المرئية في الموفّر.

يكون الإعداد الافتراضي للموفّر هو ثلاثة إشعارات مرئية. يجب أن يكون `limit` عدداً صحيحاً موجباً، ويمكن أن يتغير أثناء تثبيت الموفّر. يؤدي خفضه أو الإضافة فوقه إلى إغلاق أقدم الإشعارات المرئية أولاً. تؤدي زيادتها إلى إبقاء الإشعارات الحالية دون تغيير ولا تستعيد الإشعارات المغلقة. تحافظ تغييرات التهيئة على المخزن والمُعرّفات الباقية والترتيب والوقت المتبقي للعد التنازلي.

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

**Light**

[دورة حياة الإشعارات المشتركة (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-lifecycle--documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[دورة حياة الإشعارات المشتركة (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-lifecycle--documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toaster-lifecycle--documentation)

تعرض عناصر 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 لتوطين اسم منطقته الافتراضي، "الإشعارات"، ومنح المناطق المتطابقة أسماء مناسبة.

**Light**

[بوابة إشعارات ذات نطاق محدد (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-lifecycle--portal-documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[بوابة إشعارات ذات نطاق محدد (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-lifecycle--portal-documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toaster-lifecycle--portal-documentation)

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

استخدم المعرّف الذي يعيده `enqueueToast` لتحديث المحتوى أو حالة الملاحظات أو الإجراءات أو دوال الاستدعاء في مكانها. تحافظ التحديثات على معرّف الإشعار وموضعه. لا يكون للمعرّفات غير المعروفة أو المرفوضة أي تأثير، بما في ذلك أثناء تشغيل حركة الرفض. يستهدف كل استدعاء لـ `useToast()` أقرب موفّر له.

**Light**

[تحديث إشعار نشط (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster--updates-documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[تحديث إشعار نشط (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster--updates-documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toaster--updates-documentation)

```tsx theme={null}
import { useToast } from 'twenty-ui/components/feedback';
import { Button } from 'twenty-ui/primitives/input';

type SaveButtonProps = {
  saveRecord: () => Promise<void>;
  onViewRecord: () => void;
};

export const SaveButton = ({ saveRecord, onViewRecord }: SaveButtonProps) => {
  const { enqueueToast, updateToast } = useToast();

  const save = async () => {
    const id = enqueueToast({
      children: 'Saving record',
      status: 'info',
      progress: 0,
    });

    try {
      await saveRecord();
      updateToast({
        id,
        children: 'Record saved',
        status: 'success',
        progress: undefined,
        action: <Button onClick={onViewRecord}>View record</Button>,
      });
    } catch {
      updateToast({
        id,
        children: 'Record could not be saved',
        status: 'error',
        progress: undefined,
      });
    }
  };

  return <Button onClick={save}>Save record</Button>;
};
```

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

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

يكون العد التنازلي مضبوطًا افتراضيًا على 6,000 مللي ثانية. يتوقف مؤقتًا عندما يكون المؤشر فوق الإشعار المنبثق أو يكون تركيز لوحة المفاتيح داخله، ولا يُستأنف إلا بعد مغادرتهما معًا. مع وجود عناصر Toaster متعددة، تكون حالة الإيقاف المؤقت مشتركة بين نسخها المتطابقة. يتبع العد التنازلي المرئي الوقت المتبقي للإخفاء. يعمل الإخفاء التلقائي أيضًا عندما تؤدي الحركة المخففة إلى تعطيل الرسوم المتحركة.

**Light**

[عناصر التحكم في توقيت الإشعار (light)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-timing--documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[عناصر التحكم في توقيت الإشعار (dark)](https://storybook.twenty.com/iframe.html?id=ui-feedback-toaster-timing--documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-feedback-toaster-timing--documentation)

| العملية | سلوك العد التنازلي |
| - | - |
| تحديث المحتوى أو الحالة أو الإجراءات أو دوال الاستدعاء | الحفاظ على الوقت المتبقي. لا تؤدي التحديثات المتكررة إلى تمديده. |
| وفّر `duration` إلى `updateToast` | بدء مدة جديدة، بما في ذلك عندما تبقى القيمة دون تغيير. يعيد `duration: undefined` القيمة الافتراضية ويعيد تشغيلها. |
| تغيير الخاصية `duration` لـ `Toast` مستقل | بدء مدة جديدة. تؤدي إعادة عرض القيمة نفسها إلى الاحتفاظ بالوقت المتبقي. |
| عيّن `duration: 0` | أبقِ الإشعار مفتوحًا حتى يتم رفضه. |
| وفّر `progress` | أوقف العد التنازلي مؤقتًا ما دامت قيمة التقدم موجودة. |
| أزل `progress` | ابدأ مدة جديدة، أو أبقه مفتوحًا عندما تكون مدته صفرًا. |
| التحديث أثناء التمرير فوقه أو تركيزه | طبّق القواعد نفسها، مع إبقاء العد التنازلي الناتج متوقفًا مؤقتًا إلى أن يغادر كل من المؤشر والتركيز. |

على سبيل المثال، يحافظ `updateToast({ id, children: 'Still saving' })` على الوقت المتبقي، بينما يمنح `updateToast({ id, duration: 6000 })` القارئ ست ثوانٍ إضافية. تنطبق هذه القواعد على الإشعار الحالي دون تغيير معرّفه أو موضعه.

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

```tsx theme={null}
import { useState } from 'react';
import { Toast } from 'twenty-ui/components/feedback';
import { Button } from 'twenty-ui/primitives/input';

export const SaveNotification = () => {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button onClick={() => setVisible(true)}>Show saved notification</Button>
      {visible && (
        <Toast
          status="success"
          description="Your changes are available to your team."
          duration={6000}
          onClose={() => setVisible(false)}
        >
          Record saved
        </Toast>
      )}
    </>
  );
};
```

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

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

```tsx theme={null}
import { Toast } from 'twenty-ui/components/feedback';

type ImportProgressProps = { progress: number; onCancel: () => void };

export const ImportProgress = ({ progress, onCancel }: ImportProgressProps) => (
  <Toast
    status="info"
    progress={progress}
    description="You can continue working while the import runs."
    onCancel={onCancel}
    cancelLabel="Cancel import"
  >
    Importing records: {progress}%
  </Toast>
);
```

يؤدي تمرير `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 النسق المحيط واتجاه النص.

**action** `ReactNode`

Optional footer node, such as a Button with a caller-owned action.

**cancelLabel** `ReactNode` (default: Cancel)

Cancel button content node. Defaults to Cancel. Pass null to hide the control.

**children** `ReactNode`

Main message node. Callers own its content and accessible text.

**className** `string`

Additional class names merged onto the root.

**closeLabel** `string` (default: Close)

Accessible name of the close button. Defaults to Close.

**description** `ReactNode`

Optional supporting content node rendered below the message.

**duration** `number` (default: 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.

**icon** `ReactNode`

Leading icon node. Defaults to the status icon. Pass null to omit it.

**iconLabel** `string`

Accessible name of the default icon. Without it, the icon is decorative.

**onCancel** `(() =\> void)`

Called when the cancel button is clicked. Providing it and renderable cancelLabel content shows the button.

**onClose** `(() =\> 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.

**progress** `number`

Completion percentage. Providing it disables the countdown. Removing it starts a fresh duration.

**ref** `Ref\<HTMLDivElement\>`

Ref to the root div, or the element supplied through render.

**render** `RenderProp\<Record\<string, unknown\>\>`

Element or callback composition for the root. Native props and the ref target the rendered element.

**status** `"error" | "info" | "neutral" | "success" | "warning"` (default: neutral)

Feedback meaning: neutral, info, success, warning, or error. Defaults to neutral and selects the icon and theme palette.

**style** `CSSProperties`

Inline styles forwarded to the root.

### ToastProvider

**children** `ReactNode`

Application content and any Toasters sharing this provider’s independent notification store and lifecycle.

**limit** `number` (default: 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 الأصلية والأنماط وأسماء الفئات والمراجع منطقة الإشعارات.

**container** `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.

**getToastProps** `((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.

**render** `RenderProp\<Record\<string, unknown\>\>`

Custom root element composed through Base UI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.