مربع الحوار

نظرة عامة

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

استخدام

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

يتولى Root الظهور افتراضيًا. عيّن defaultOpen لحالته الأولية. تؤدي المشغلات وعناصر تحكم الإغلاق ومفتاح Escape والنقرات الخارجية إلى تحديث تلك الحالة.

import { Button, Field, Input } from 'twenty-ui/primitives/input';
import { Dialog } from 'twenty-ui/primitives/surfaces';

export const AccountDialog = () => (
  <Dialog.Root defaultOpen={false}>
    <Dialog.Trigger render={<Button>Edit account</Button>} />
    <Dialog.Portal>
      <Dialog.Backdrop />
      <Dialog.Viewport>
        <Dialog.Popup>
          <Dialog.Header>
            <Dialog.Title>Edit account</Dialog.Title>
            <Dialog.Description>Update the account details.</Dialog.Description>
          </Dialog.Header>
          <Dialog.Body>
            <Field.Root name="company">
              <Field.Label>Company name</Field.Label>
              <Input defaultValue="Acme" />
            </Field.Root>
          </Dialog.Body>
          <Dialog.Footer>
            <Dialog.Close render={<Button variant="outline">Close</Button>} />
            <Dialog.Close render={<Button>Save</Button>} />
          </Dialog.Footer>
        </Dialog.Popup>
      </Dialog.Viewport>
    </Dialog.Portal>
  </Dialog.Root>
);

البنية

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

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

جمّع Portal وBackdrop وViewport وPopup صراحةً. يقبل كل جزء من DOM سماته الأصلية ومعالجاته وclassName وstyle وref وتركيب render الخاصة به. يستهدف ref العنصر المعروض لذلك الجزء. لا ينشئ Popup بوابة أو خلفية أو منفذ عرض.

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

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

import { useState } from 'react';
import { Button, Field, Input } from 'twenty-ui/primitives/input';
import { Dialog } from 'twenty-ui/primitives/surfaces';

export const AccountDialog = () => {
  const [open, setOpen] = useState(false);

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger render={<Button>Edit account</Button>} />
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Viewport>
          <Dialog.Popup>
            <Dialog.Header>
              <Dialog.Title>Edit account</Dialog.Title>
              <Dialog.Description>
                Update the account details.
              </Dialog.Description>
            </Dialog.Header>
            <Dialog.Body>
              <Field.Root name="company">
                <Field.Label>Company name</Field.Label>
                <Input defaultValue="Acme" />
              </Field.Root>
            </Dialog.Body>
            <Dialog.Footer>
              <Dialog.Close render={<Button variant="outline">Close</Button>} />
              <Dialog.Close render={<Button>Save</Button>} />
            </Dialog.Footer>
          </Dialog.Popup>
        </Dialog.Viewport>
      </Dialog.Portal>
    </Dialog.Root>
  );
};

بالنسبة إلى نموذج غير متزامن، أبقِ مربع الحوار مفتوحًا أثناء الإرسال. أغلقه بعد النجاح واعرض حالات الفشل داخل مربع الحوار.

التركيب

يقبل Trigger وClose ‎render للتركيب مع Button، كما هو موضح أعلاه. يجب أن تقوم الأغلفة المخصصة بتمرير الخصائص والمراجع الموفرة. تحافظ أجزاء DOM على أسماء الفئات والأنماط وعقود render للاستدعاء الواعية بالحالة في Base UI. يحتفظ Header وBody وFooter بتخطيطها المنسق وتركيب div الأصلي. ضمّن Dialog.Root آخر داخل نافذة منبثقة لفتح مربع حوار ثانٍ. تؤدي إغلاق مربع الحوار المتداخل إلى إعادة التركيز إلى مشغله في الأصل. لفتح مربع حوار واحد من مشغلات خارج Root، أنشئ مقبضًا مرة واحدة باستخدام Dialog.createHandle\<TPayload>() ومرّره إلى handle في كلٍّ من Root وTrigger. تتوفر قيم payload الخاصة بـ Trigger في دالة العرض الخاصة بـ Root. يكشف Dialog.Handle والنوع العام DialogHandle عن عقد المقبض المثبت:

العضو	الغرض
`open(triggerId)`	يفتح مع مشغل مطابق بوصفه المشغل النشط.
`open(null)`	يفتح دون إقران مشغل.
`openWithPayload(payload)`	يفتح بحمولة محددة النوع ومن دون مشغل مقترن.
`close()`	يطلب الإغلاق.
`isOpen`	يقرأ ما إذا كان مربع الحوار المقترن مفتوحًا.

لا تسري الإجراءات الأمرية إلا أثناء تركيب Root المقترن. يكشف actionsRef الخاص بـ Root أيضًا عن close() وunmount() للتحكم الصريح في الانتقال. للتحكم في حركة إغلاق خارجية، استدعِ eventDetails.preventUnmountOnClose() في onOpenChange، ثم استدعِ إجراء unmount() عند انتهاء الحركة. يستخدم Title ‏Heading ويكون افتراضيًا h2 بخط كبير ولون نص أساسي ومحاذاة مركزية وتباعد-4 أسفله. استخدم level لتغيير مستوى العنوان بصورة مستقلة عن size، أو color لتغيير لون نصه. تُمرر className وstyle والمراجع وrender الأصلية إلى العنوان. أبقِ عنصر عنوان عند استخدام render. يكون Description في المنتصف مثل Title؛ بينما يُبقي AlertDialog كليهما بمحاذاة إلى اليسار. لا يحتوي Popup على حشوة. يوفر Header وBody وFooter المسافة البادئة، لذا يكون المحتوى الموضوع مباشرةً في Popup ملاصقًا لحوافه.

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

يتحكم Root.modal في حدود التفاعل:

القيمة	تركيز	تمرير الصفحة والتفاعل الخارجي
`true` (افتراضي)	محصور داخل مربع الحوار	يُحظر تمرير الصفحة والتفاعل الخارجي.
`"trap-focus"`	محصور داخل مربع الحوار	يبقى تمرير الصفحة والتفاعل خارجها متاحين.
`خاطئ`	يمكنه مغادرة مربع الحوار	يبقى تمرير الصفحة والتفاعل الخارجي متاحين.

احذف Backdrop عند عدم الحاجة إلى خلفية مرئية. لمربع حوار غير نمطي ينبغي أن يمرر منفذ عرضه أحداث المؤشر إلى الصفحة، استخدم \<Dialog.Viewport data-backdrop-hidden="true">؛ ويبقى Popup تفاعليًا. لا يؤدي حذف الخلفية المرئية وحده إلى تغيير Root.modal. عيّن Popup.initialFocus أو Popup.finalFocus إلى مرجع أو دالة استدعاء لاختيار أهداف التركيز؛ يعطّل false نقل التركيز التلقائي هذا. تتلقى ردود اتصال التركيز نوع التفاعل وتحتفظ بسلوك الإرجاع المنطقي والعنصر وnull وundefined الخاص بـ Base UI. يؤدي الإغلاق عادةً إلى استعادة التركيز إلى المشغل أو العنصر الذي كان مُركزًا عليه سابقًا. يمنع Root.disablePointerDismissal النقرات الخارجية من طلب الإغلاق. لمنع الإغلاق باستخدام Escape، ألغِ تغيير escape-key في onOpenChange. وفّر دائمًا طريقة مرئية لإغلاق مربع حوار نمطي.

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

يقبل Popup.size القيم sm وcompact وmd وlg وxl وfullscreen، وتكون قيمته الافتراضية md. يُمرّر المحتوى الطويل داخل النافذة المنبثقة. يُقيَّد العرض بمنفذ العرض. عيّن Portal.container لاختيار وجهة:

القيمة	الدقة
محذوف أو `undefined`	يستخدم أقرب حاوية نسق ذات نطاق. عند عدم وجود واحدة، يستخدم Base UI البوابة الأصل أو جسم المستند.
عنصر أو `ShadowRoot`	يستخدم تلك الوجهة الصريحة بدلًا من نطاق النسق.
Ref	يحلّ Base UI عنصره الحالي. يعود ref الذي تكون قيمته الحالية null إلى البوابة الأصل أو جسم المستند.
`null`	ينتظر دون تركيب. وفّر وجهة في عرض لاحق للتركيب.

يحتفظ Portal.keepMounted بالمحتوى وحالة النموذج أثناء الإغلاق. يحمل Viewport وPopup اتجاه النص المقدّم إلى حاوية خارجية؛ وتكون لخصائص dir الصريحة الخاصة بهما الأولوية. من دون موفر اتجاه أو dir صريح، يرثان الاتجاه من الوجهة. راجع إعداد النسق وDirectionProvider. خصّص Backdrop وViewport عبر خصائصهما الخاصة. تُطبّق سماتهما الأصلية ومعالجاتهما وrefs وrender على تلك العناصر بصورة مستقلة عن Popup. يبقي forceRender الخاص بـ Backdrop خلفية مربع الحوار المتداخل مرئية عند الحاجة. تبقى حالة الفتح والانتقال في Base UI متاحة للأنماط الواعية بالحالة وردود اتصال العرض.

الترحيل

غلّف محتوى Dialog.Popup الحالي داخل Dialog.Portal وDialog.Viewport، وأضف Dialog.Backdrop شقيقًا داخل Portal. انقل container وkeepMounted من Popup إلى Portal. انقل خصائص backdrop السابقة إلى Backdrop؛ واستبدل backdrop={false} بحذف Backdrop. انقل viewportProps إلى Viewport، مع الاحتفاظ بـ data-backdrop-hidden="true" عندما يجب على منفذ العرض تمرير أحداث المؤشر الخارجية. أبقِ size وinitialFocus وfinalFocus وسمات النافذة المنبثقة الأصلية وrefs النافذة المنبثقة على Popup. تُزال خصائص تجميع Popup الموحّدة. يحتفظ Root وTrigger وClose وTitle وDescription وHeader وBody وFooter والمقابض الحالية بأدوارها. تُصدَّر خصائص الأجزاء العامة والحالة والإجراءات وأنواع تفاصيل الأحداث من twenty-ui/primitives/surfaces.

الإزاحة

Dialog.Root

RefObject<DialogRootActions | null>

A ref to imperative actions.

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

ReactNode | PayloadChildRenderFunction<Payload>

Parts or a render function receiving the active trigger payload. Root renders no DOM node.

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.

boolean

افتراضي:"false"

Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it.

DialogHandle<Payload>

Connects detached triggers and imperative dialog actions.

Determines if the dialog enters a modal state when open.

true: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.
false: user interaction with the rest of the document is allowed.
'trap-focus': focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled.

When modal is true or 'trap-focus', render <Dialog.Close> inside <Dialog.Popup> so touch screen readers can escape the popup.

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

Receives the requested state and Base UI event details, including reason, event, trigger and cancel().

((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).

Dialog.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.

DialogHandle<Payload>

A handle to associate the trigger with a dialog. Can be created with the Dialog.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.

Ref to the trigger button, or the element supplied through render.

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.

Dialog.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. Omit to use the nearest theme scope, then the parent portal or document body. Explicit null defers mounting; an element, ShadowRoot or ref keeps Base UI resolution.

boolean

افتراضي:"false"

Keeps the portal and its content mounted while closed.

Ref<HTMLDivElement>

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

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

Composes the portal element. Native props and handlers target it.

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

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

Dialog.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"

Renders the backdrop even when this dialog is nested.

Ref<HTMLDivElement>

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

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.

Dialog.Viewport

ReactNode

Popup and any other content within the positioning 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.

Ref<HTMLDivElement>

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

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.

Dialog content. Compose inside Viewport and Portal; Popup does not create those parts or a Backdrop.

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

Controls focus restoration on closing. Accepts a boolean, element ref or callback receiving the interaction type.

Controls focus on opening. Accepts a boolean, element ref or callback receiving the interaction type.

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

Composes the popup element while retaining native props, handlers, dialog semantics and focus behavior.

Width of the dialog, 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.

Dialog.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.

"primary" | "secondary" | "tertiary"

افتراضي:"primary"

Theme font color. Defaults to primary.

1 | 2 | 3 | 4 | 5 | 6

افتراضي:"2"

Semantic heading level, from h1 through h6. Does not change the visual size. Defaults to 2.

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.

"lg" | "md" | "sm" | "xl" | "xs" | "xxl"

افتراضي:"lg"

Visual font size, independent of the heading level. Defaults to lg.

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

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

Dialog.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.

Ref<HTMLParagraphElement>

Ref to the description paragraph, or the element supplied through render.

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.

Dialog.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>).

Ref<HTMLButtonElement>

Ref to the close button, or the element supplied through render.

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.

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.

Dialog.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.

المطورون

التطبيقات

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

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

المساهمة

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

نظرة عامة

استخدام

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

البنية

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

التركيب

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

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

الترحيل

الإزاحة

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer

​نظرة عامة

​استخدام

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

​البنية

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

​التركيب

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

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

​الترحيل

​الإزاحة

​Dialog.Root

​Dialog.Trigger

​Dialog.Portal

​Dialog.Backdrop

​Dialog.Viewport

​Dialog.Popup

​Dialog.Title

​Dialog.Description

​Dialog.Close

​Dialog.Header

​Dialog.Body

​Dialog.Footer

نظرة عامة

استخدام

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

البنية

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

التركيب

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

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

الترحيل

الإزاحة

Dialog.Root

Dialog.Trigger

Dialog.Portal

Dialog.Backdrop

Dialog.Viewport

Dialog.Popup

Dialog.Title

Dialog.Description

Dialog.Close

Dialog.Header

Dialog.Body

Dialog.Footer