AlertDialog

نظرة عامة

استخدم AlertDialog لقرار يقطع سير العمل الحالي، مثل تأكيد الحذف. يوفّر دلالات alertdialog، وإدارة التركيز، وتأكيدًا أو إلغاءً صريحًا. هذا المكوّن الأساسي مخصّص لواجهات Twenty UI المستقلة والواجهات التي يملكها المضيف. يجب على مكوّنات الواجهة طلب تأكيد عبر واجهة برمجة تطبيقات مربع حوار المضيف SDK. يُحظر استخدام Dialog وAlertDialog ومربعات حوار المتصفح الأصلية مباشرةً داخل عارض المكوّن الأمامي.

استخدام

حالة غير متحكم بها

استخدم defaultOpen لتعيين مستوى الظهور الأولي. يتولى مربع الحوار التغييرات اللاحقة من المشغّل وعناصر التحكم في الإغلاق وتفاعلات الرفض.

import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root defaultOpen={false}>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);

القيمة الافتراضية لـ defaultOpen هي false، لذا يمكن حذفه. يستخدم هذا المثال دالة رد اتصال تأكيد متزامنة ويُغلق بعد تنفيذ الإجراء.

البنية التشريحية

أبقِ الأجزاء ذات الصلة داخل AlertDialog.Root، أو صِل المشغّلات المنفصلة عبر مقبض. أنشئ البوابة والخلفية ومنفذ العرض والنافذة المنبثقة بصورة منفصلة.

AlertDialog.Root
├── AlertDialog.Trigger
└── AlertDialog.Portal
    ├── AlertDialog.Backdrop
    └── AlertDialog.Viewport
        └── AlertDialog.Popup
            ├── AlertDialog.Header
            │   ├── AlertDialog.Title
            │   └── AlertDialog.Description
            ├── AlertDialog.Body
            └── AlertDialog.Footer
                ├── AlertDialog.Close
                └── Confirmation action

الجزء	المتطلبة	الغرض
`Root`	مطلوب	ينسق حالة الفتح وسلوك النافذة المشروطة.
`المشغّل`	اختياري لمربع حوار يُفتح برمجيًا	يفتح مربع الحوار ويوفر هدفًا لإعادة التركيز.
`Portal`	مُوصى به	ينقل التراكب إلى حاويته ويتحكم في تركيبه.
`Backdrop`	اختياري	يفصل التنبيه بصريًا عن الصفحة المحيطة.
`Viewport`	مُوصى به	يحدّد موضع النافذة المنبثقة ويوفر المنطقة المحيطة القابلة للتمرير الخاصة بها.
`Popup`	مطلوب	يعرض محتوى التنبيه مع إدارة التركيز.
`العنوان`	مُوصى به	يوفّر الاسم المرئي للتنبيه. الاسم المتاح مطلوب دائمًا.
`Description`	موصى به للتأكيد	يشرح القرار وعواقبه.
`Header`، `Body`، `Footer`	أجزاء تخطيط اختيارية	رتّب العناوين والمحتوى الإضافي والإجراءات.
`إغلاق`	موصى به للإلغاء	يوفر إجراء إغلاق صريحًا.

عيّن container وkeepMounted على Portal، وسمات الخلفية على Backdrop، وسمات التخطيط على Viewport، وخصائص size والتركيز على Popup. يقبل كل جزء من العنصر سماته الأصلية ومعالجاته ومرجعه وتركيب render الخاص به. يشير Popup.ref إلى عنصر محتوى التنبيه. ينشئ Title وDescription العلاقات المتاحة؛ وفّر aria-label على Popup عند حذف العنوان. إجراء التأكيد هو محتوى للتطبيق، وليس جزءًا مُصدّرًا. استخدم Close مع معالج متزامن أو Button مع حالة فتح خاضعة للتحكم للتأكيد غير المتزامن.

حالة متحكم بها

مرر open وحدّثه باستخدام onOpenChange للتحكم في ظهور مربع الحوار نفسه ضمن حالة React. تتلقى دالة الاستدعاء القيمة المنطقية المطلوبة وتفاصيل الحدث المصدر، بما في ذلك reason وevent وcancel(). استدعِ eventDetails.cancel() لرفض تغيير مطلوب. يُشغَّل onOpenChangeComplete بعد انتهاء انتقالات الفتح أو الإغلاق.

import { useState } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => {
  const [open, setOpen] = useState(false);

  return (
    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Trigger
        render={<Button variant="solid">Delete record</Button>}
      />
      <AlertDialog.Portal>
        <AlertDialog.Backdrop />
        <AlertDialog.Viewport>
          <AlertDialog.Popup>
            <AlertDialog.Header>
              <AlertDialog.Title>Delete this record?</AlertDialog.Title>
              <AlertDialog.Description>
                This record will be permanently deleted. This action cannot be
                undone.
              </AlertDialog.Description>
            </AlertDialog.Header>
            <AlertDialog.Footer>
              <AlertDialog.Close render={<Button>Cancel</Button>} />
              <AlertDialog.Close
                onClick={onDelete}
                render={<Button color="danger">Delete</Button>}
              />
            </AlertDialog.Footer>
          </AlertDialog.Popup>
        </AlertDialog.Viewport>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
};

للتأكيد غير المتزامن، استخدم Button مع معالج الإجراء بدلاً من AlertDialog.Close. أبقِ open بالقيمة true أثناء انتظار الإجراء، واستدعِ setOpen(false) بعد نجاحه، واعرض خطأً داخل مربع الحوار إذا فشل.

التركيب باستخدام الأزرار

استخدم render لمنح عناصر التحكم في التشغيل والإغلاق تنسيق أزرار Twenty UI. توفر أجزاء مربع الحوار معالجات التفاعل وrefs الخاصة بها للأزرار.

import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);

أبقِ كل إجراء كعنصر تحكم تفاعلي واحد. إذا غلّفت Button في مكوّنك الخاص، مرّر props وref المقدّمين.

المشغّلات المنفصلة والإجراءات الحتمية

أنشئ مقبضًا مرة واحدة باستخدام AlertDialog.createHandle\<Payload>() ومرّره إلى handle على Root وكل Trigger منفصل. تكون payload المكتوبة للمشغّل متاحة لدالة عرض الطفل الخاصة بالجذر. يدعم المقبض أيضًا open(triggerId) وopenWithPayload(payload) وclose() والخاصية الجالبة isOpen أثناء تركيب جذره. مرّر معرّف مشغّل مطابقًا إلى open، أو null للفتح دون مشغّل. استدعِ الأساليب الحتمية من معالجات الأحداث أو التأثيرات. يكشف Root.actionsRef عن close() وunmount(). للحصول على حركة إغلاق متحكَّم بها خارجيًا، استدعِ eventDetails.preventUnmountOnClose() في onOpenChange، ثم استدعِ actionsRef.current?.unmount() بعد انتهاء الحركة. تدير الأجزاء المنسقة العادية انتقالاتها الخاصة دون هذه الإجراءات الحتمية.

التحجيم والبوابات

يقبل Popup.size القيم sm وmd وlg وxl وfullscreen، وتكون قيمته الافتراضية md. ينتمي الحجم والمظهر إلى سطح AlertDialog ولا يلزم أن يطابقا إعدادات Dialog المسبقة. تكون القيمة الافتراضية لـ Portal.container هي حاوية البوابة لأقرب سمة. من دون واحدة، يستخدم Base UI وجهة البوابة الافتراضية الخاصة به، وهي عادةً document.body. يتجاوز عنصر صريح أو جذر ظل أو مرجع تلك الوجهة. يؤجّل null صريح التركيب إلى أن تصبح الحاوية متاحة. يعالج Base UI مرجعًا تكون current فيه null باستخدام وجهته الافتراضية؛ استخدم container={null} عندما يجب أن ينتظر التركيب. يحتفظ المحتوى المُمرَّر عبر البوابة بسياق السمة. يرث Portal وViewport اتجاه النص المقدَّم ما لم تعيّن dir صراحةً. عيّن Portal.keepMounted للاحتفاظ بالمحتوى المركّب وحالة النموذج أثناء الإغلاق.

التركيز والإغلاق

يحصر التنبيه التركيز، ويحظر التفاعل الخارجي، ويقفل تمرير الصفحة أثناء الفتح. يطلب مفتاح Escape الإغلاق؛ أما النقر خارجًا فلا يفعل ذلك. لمنع الإغلاق بمفتاح Escape، ألغِ تغيير escape-key في onOpenChange. وفّر دائمًا إجراءً مرئيًا للإلغاء أو الإغلاق. افتراضيًا، ينتقل التركيز إلى أول عنصر تحكم قابل للتبويب، أو إلى النافذة المنبثقة عند الفتح باللمس. ضع الإجراء الأقل تدميرًا أولًا، أو استخدم Popup.initialFocus لتحديده. يعود التركيز إلى المشغّل أو العنصر الذي كان عليه التركيز سابقًا عند إغلاق التنبيه. استخدم Popup.finalFocus عندما يزيل إجراء ناجح ذلك الهدف. تقبل كلتا خاصيتي التركيز قيمة منطقية أو مرجع عنصر أو دالة استدعاء لنوع التفاعل وفقًا للعقد المصدر.

الإزاحة

يُنشأ المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء المتاحة ومعالجات الأحداث، في الأجزاء التي تعرض عناصر.

AlertDialog.Root

RefObject<DialogRootActions | null>

A ref to imperative actions.

unmount: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes. Call preventUnmountOnClose() in onOpenChange first, otherwise the alert dialog completes closing on its own. Whether it leaves the DOM is decided by keepMounted on the portal.
close: Closes the alert dialog imperatively when called.

ReactNode | PayloadChildRenderFunction<Payload>

The content of the dialog. This can be a regular React node or a render function that receives the payload of the active trigger.

boolean

افتراضي:"false"

Whether the dialog is initially open.To render a controlled dialog, use the open prop instead.

string | null

ID of the trigger that the dialog is associated with. This is useful in conjunction with the defaultOpen prop to create an initially open dialog.

AlertDialogHandle<Payload>

A handle to associate the alert dialog with a trigger. If specified, allows external triggers to control the alert dialog’s open state. Can be created with the AlertDialog.createHandle() method.

((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) => void)

Event handler called when the alert dialog is opened or closed.

((open: boolean) => void)

Event handler called after any animations complete when the dialog is opened or closed.

boolean

Whether the dialog is currently open.

string | null

ID of the trigger that the dialog is associated with. This is useful in conjunction with the open prop to create a controlled dialog. There’s no need to specify this prop when the dialog is uncontrolled (that is, when the open prop is not set).

AlertDialog.Trigger

string | ((state: DialogTriggerState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

AlertDialogHandle<Payload>

A handle to associate the trigger with an alert dialog. Can be created with the AlertDialog.createHandle() method.

string

ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot triggerId prop).

boolean

افتراضي:"true"

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

Payload

A payload to pass to the dialog when it is opened.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTriggerState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogTriggerState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Portal

string | ((state: DialogPortalState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

Portal destination. Omission uses the theme container or Base UI default; explicit null defers mounting. A ref with a null current value uses the Base UI default destination.

boolean

افتراضي:"false"

Keeps content mounted while the alert is closed.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogPortalState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogPortalState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Backdrop

string | ((state: DialogBackdropState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"false"

Whether the backdrop is forced to render even when nested.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogBackdropState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogBackdropState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Viewport

string | ((state: DialogViewportState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogViewportState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogViewportState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

CSS class applied to the element, or a function that returns a class based on the component’s state.

Determines the element to focus when the dialog is closed.

false: Do not move focus.
true: Move focus based on the default behavior (trigger or previously focused element).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.

Determines the element to focus when the dialog is opened. By default, focus moves to the first tabbable element inside the popup, except when the dialog is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.

false: Do not move focus.
true: Move focus based on the default behavior (first tabbable element or popup).
RefObject: Move focus to the ref element.
function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, null to fall back to the default behavior, or false/undefined to do nothing.

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

Width of the alert, or fullscreen to fill the viewport.

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Title

string | ((state: DialogTitleState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogTitleState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogTitleState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Description

string | ((state: DialogDescriptionState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogDescriptionState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogDescriptionState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Close

string | ((state: DialogCloseState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"true"

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (for example, <div>).

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DialogCloseState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

CSSProperties | ((state: DialogCloseState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

AlertDialog.Header

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

AlertDialog.Body

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

المطورون

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

مكتبة واجهة المستخدم

نظرة عامة

استخدام

حالة غير متحكم بها

البنية التشريحية

حالة متحكم بها

التركيب باستخدام الأزرار

المشغّلات المنفصلة والإجراءات الحتمية

التحجيم والبوابات

التركيز والإغلاق

الإزاحة

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Portal

AlertDialog.Backdrop

AlertDialog.Viewport

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer

​نظرة عامة

​استخدام

​حالة غير متحكم بها

​البنية التشريحية

​حالة متحكم بها

​التركيب باستخدام الأزرار

​المشغّلات المنفصلة والإجراءات الحتمية

​التحجيم والبوابات

​التركيز والإغلاق

​الإزاحة

​AlertDialog.Root

​AlertDialog.Trigger

​AlertDialog.Portal

​AlertDialog.Backdrop

​AlertDialog.Viewport

​AlertDialog.Popup

​AlertDialog.Title

​AlertDialog.Description

​AlertDialog.Close

​AlertDialog.Header

​AlertDialog.Body

​AlertDialog.Footer

نظرة عامة

استخدام

حالة غير متحكم بها

البنية التشريحية

حالة متحكم بها

التركيب باستخدام الأزرار

المشغّلات المنفصلة والإجراءات الحتمية

التحجيم والبوابات

التركيز والإغلاق

الإزاحة

AlertDialog.Root

AlertDialog.Trigger

AlertDialog.Portal

AlertDialog.Backdrop

AlertDialog.Viewport

AlertDialog.Popup

AlertDialog.Title

AlertDialog.Description

AlertDialog.Close

AlertDialog.Header

AlertDialog.Body

AlertDialog.Footer