دیالوگ — Dialog

یک پنجرهٔ مودال مرکزی است که توجه کاربر را برای یک فرم کوتاه یا یک اطلاعات متمرکز می‌گیرد. از React Aria برای دام فوکوس، Escape، قفل اسکرول صفحهٔ زیرین، پیرامون و بازگرداندن فوکوس به محرک استفاده می‌کند. این رفتارها ثابت‌اند و هیچ تم یا پراپی آن‌ها را غیرفعال نمی‌کند. برای تأیید کنش مخرب از ، برای تغییر خودکار بین نمای مودال و کشو در موبایل از استفاده کنید.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Dialog } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

پایه: محرک، عنوان، توضیح و کنش‌ها

TSX

import { Dialog, Button } from '@tokapps/tuk';export function IdeaDialog() {  return (    <Dialog      trigger={<Button>ثبت ایده</Button>}      title="ثبت ایدهٔ جدید"      description="ایده‌ات را کوتاه و روشن بنویس تا جامعه بتواند ارزیابی‌اش کند."      footer={({ close }) => (        <>          <Button variant="ghost" onClick={close}>بعداً</Button>          <Button onClick={close}>ثبت ایده</Button>        </>      )}    >      <p>پس از ثبت، ایده در بخش «در حال بررسی» نمایش داده می‌شود.</p>    </Dialog>  );}

پیشرفته: کنترل‌شده، اندازهٔ بزرگ، بدون بستن با پس‌زمینه و کنش ناهمگام

TSX

import { useState } from 'react';import { Dialog, Button } from '@tokapps/tuk';import { submitIdea } from './api'; // تابع ارسال خود اپexport function SubmitIdeaDialog() {  const [open, setOpen] = useState(false);  return (    <>      <Button variant="secondary" onClick={() => setOpen(true)}>باز کردن فرم</Button>      <Dialog        open={open}        onOpenChange={setOpen}        size="lg"        dismissable={false}        title="ثبت ایدهٔ جدید"        description="کلیک روی پس‌زمینه این پنجره را نمی‌بندد؛ از دکمه‌ها یا Escape استفاده کنید."        footer={({ close }) => (          <>            <Button variant="ghost" onClick={close}>انصراف</Button>            <Button              action={async () => {                await submitIdea();                close();              }}            >              ثبت ایده            </Button>          </>        )}      >        <p>متن ایده را در فیلدهای زیر وارد کنید.</p>      </Dialog>    </>  );}

حالت محدود: بدون دکمهٔ بستن، با چاپ قابل نمایش

TSX

import { Dialog, Button } from '@tokapps/tuk';export function ProcessNotice() {  return (    <Dialog      size="sm"      showClose={false}      print="show"      trigger={<Button variant="secondary">وضعیت پردازش</Button>}      title="در حال بررسی"      footer={({ close }) => <Button onClick={close}>متوجه شدم</Button>}    >      <p>ایده‌ات تا ۲۴ ساعت آینده بررسی می‌شود. این پنجره با «متوجه شدم» یا کلید Escape بسته می‌شود.</p>    </Dialog>  );}

امتداد است: همهٔ کانفیگ‌های Modal را می‌پذیرد و با رفتار کاربر را تعیین می‌کند. هر نوع یک نمونهٔ زنده و یک بلوک کد قابل‌کپی دارد.

تأیید: انصراف و تأیید

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', onConfirm: () => undefined, onCancel: () => undefined, confirmLabel: 'ذخیره', cancelLabel: 'انصراف' }}      trigger={<Button>ذخیرهٔ تغییرات</Button>}      title="ذخیرهٔ تغییرات؟"      description="تغییرات این صفحه ذخیره شود."    />  );}

تأیید خطرناک: alertdialog بدون بستن با پس‌زمینه

TSX

import { Button, Dialog } from '@tokapps/tuk';export function DangerConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', tone: 'danger', confirmLabel: 'حذف ایده', onConfirm: () => undefined }}      trigger={<Button variant="secondary">حذف ایده</Button>}      title="این ایده حذف شود؟"      description="این کار بازگشت‌پذیر نیست. پوشش با پس‌زمینه بسته نمی‌شود و نقش alertdialog دارد."    />  );}

تأیید ناهمزمان: دکمه‌ها تا پایان کنش غیرفعال

TSX

import { Button, Dialog } from '@tokapps/tuk';const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));export function AsyncConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', confirmLabel: 'ارسال', onConfirm: () => wait(1200) }}      trigger={<Button>ارسال با انتظار</Button>}      title="ارسال درخواست؟"      description="تا پایان ارسال، دکمه‌ها غیرفعال می‌مانند و پوشش بعد از موفقیت بسته می‌شود."    />  );}

فرم: FormData و ارسال با Enter

TSX

import { Button, Dialog } from '@tokapps/tuk';export function FormDialog() {  return (    <Dialog      interaction={{ kind: 'form', submitLabel: 'ثبت ایده', onSubmit: (data) => console.info(data.get('title')) }}      trigger={<Button>فرم ثبت ایده</Button>}      title="ثبت ایدهٔ جدید"      description="عنوان را وارد کن؛ Enter هم فرم را ارسال می‌کند."    >      <label style={{ display: 'grid', gap: 'var(--tds-space-1)' }}>        عنوان        <input name="title" required />      </label>    </Dialog>  );}

فرم بدون بستن پس از ارسال

TSX

import { Button, Dialog } from '@tokapps/tuk';const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));export function KeepOpenFormDialog() {  return (    <Dialog      interaction={{ kind: 'form', closeOnSubmit: false, submitLabel: 'ذخیره و ادامه', onSubmit: () => wait(600) }}      trigger={<Button variant="secondary">فرم بدون بستن</Button>}      title="ویرایش سریع"    >      <label style={{ display: 'grid', gap: 'var(--tds-space-1)' }}>        یادداشت        <input name="note" />      </label>    </Dialog>  );}

انتخاب از فهرست: هر گزینه یک تصمیم

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ChoiceDialog() {  return (    <Dialog      interaction={{        kind: 'choice',        onChoose: () => undefined,        options: [          { value: 'publish', label: 'انتشار عمومی', description: 'همه می‌توانند ببینند.' },          { value: 'draft', label: 'ذخیره به‌صورت پیش‌نویس', description: 'فقط برای تو قابل‌دیدن است.' },          { value: 'discard', label: 'حذف پیش‌نویس', tone: 'danger' },        ],      }}      trigger={<Button>انتخاب وضعیت</Button>}      title="این ایده چه وضعیتی داشته باشد؟"    />  );}

ویزارد چندمرحله‌ای

TSX

import { Button, Dialog } from '@tokapps/tuk';export function WizardDialog() {  return (    <Dialog      interaction={{        kind: 'wizard',        onFinish: () => undefined,        steps: [          { id: 'title', title: 'عنوان', content: <input aria-label="عنوان" name="title" /> },          { id: 'body', title: 'شرح', content: <textarea aria-label="شرح" name="body" /> },          { id: 'review', title: 'بازبینی', content: 'همه‌چیز آماده است؛ پایان را بزن.' },        ],      }}      trigger={<Button>راهنمای ثبت</Button>}      title="ثبت ایده در سه مرحله"    />  );}

کانفیگ‌های Modal روی Dialog (ارث‌بری)

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ModalConfigsDialog() {  return (    <Dialog      glow="ambient"      border="rainbow"      dock="visible"      scrim="dim"      placement="top"      sound={{ open: 'notify', close: 'tap' }}      swipeToDismiss      trigger={<Button>همهٔ کانفیگ‌های Modal</Button>}      title="دیالوگ با حالت‌های Modal"      footer={({ close }) => <Button onClick={close}>فهمیدم</Button>}    >      هر کانفیگ Modal (glow، border، dock، scrim، placement، motion، sound، swipeToDismiss) روی Dialog هم کار می‌کند.    </Dialog>  );}

همهٔ پیکربندی‌ها

همهٔ پراپ‌های () را می‌گیرد و فقط را اضافه می‌کند (). پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

پراپ	نوع	پیش‌فرض	توضیح
		—	محرک باز کردن؛ با به رویداد press وصل می‌شود. بدون آن با کنترل کنید.
		—	حالت کنترل‌شده.
		—	حالت کنترل‌نشدهٔ اولیه.
		—	با هر تغییر باز یا بسته صدا می‌خورد؛ قبل از آن صدای متناظر (در صورت وجود) پخش می‌شود.
		بدون پیش‌فرض (الزامی)	عنوان؛ نام دسترسی پنجره از آن گرفته می‌شود.
		—	توضیح زیر عنوان؛ به‌صورت وصل می‌شود.
		—	ناحیهٔ کنش‌ها؛ با تابع می‌توان را گرفت. برای ، و نادیده گرفته می‌شود.
			نوع تعامل: · (با ، ، ) · (با ) · (با ، ) · (با ، ).
· · · · · · · · · ·	—	—	همان کانفیگ‌های Modal؛ جدول کامل در .
		—	بدنهٔ اسکرول‌پذیر؛ با تابع می‌توان را گرفت.
			عرض پنل از ؛ تمام‌صفحه بدون گوشهٔ گرد و بدون حاشیه (موبایل کوچک).
			نقش ARIA. تأیید با خودکار می‌شود؛ هم همان قرارداد را دارد.
		( برای تأیید خطرناک)	یعنی کلیک روی پرده نمی‌بندد؛ فقط دکمه‌ها و Escape.
			نمایش دکمهٔ بستن مرئی در گوشهٔ انتهایی.
			برچسب دسترس‌پذیر دکمهٔ بستن.
		—	مقدار روی ریشه؛ برای نشانه‌گذاری نمای ResponsiveDialog.
		—	نام دسترسی وقتی عنوان مرئی ندارید.
		—	مقصد اختصاصی صدا (opt-in).
			رفتار چاپ؛ پنل را ایستا چاپ می‌کند.
		از	جهت صریح؛ پیش‌فرض RTL است.
		—	کلاس اضافه روی ریشهٔ پوشش ().

ساختار و اسلات‌ها

ترتیب DOM و ثابت‌اند؛ ، توکن‌ها و استایل‌های هویتی فقط ظاهر را تغییر می‌دهند.

code

ModalOverlay  [data-tds="dialog"][data-overlay="modal"][data-size][data-print]└── Modal  [data-part="panel"]    └── RacDialog  [data-part="dialog"][role]        ├── button  [data-part="close"]        (فقط وقتی showClose)        ├── header  [data-part="header"]        │   └── div  [data-part="heading"]        │       ├── Heading  [data-part="title"]        (slot=title)        │       └── p  [data-part="description"]        (فقط وقتی description)        ├── div  [data-part="body"]            (فقط وقتی children)        └── footer  [data-part="footer"]       (فقط وقتی footer)

بنیان ثابت: ترتیب بالا، ها، ، ارتباط و ، و جای دکمهٔ بستن در انتهای خط.
قابل تغییر: روی ریشه، متغیرهای ، و محتوای ، .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	پوشش در DOM نیست	—
در حال ورود	روی و (از React Aria)	پرده با fade و پنل با ، مدت
باز (open)		پرده و پنل؛ بقیهٔ صفحه
در حال خروج		fade-out و pop-out
پیش‌فرض (دکمهٔ بستن)	—	شفاف، رنگ
hover (دکمهٔ بستن)		پس‌زمینه ، رنگ
pressed (دکمهٔ بستن)		پس‌زمینه
focus-visible	روی دکمهٔ بستن و کنترل‌های داخل پنل (نه خود )	حلقهٔ
	در React Aria	کلیک پرده نمی‌بندد
		تمام‌صفحه، بدون حاشیه و گوشهٔ گرد
چاپ		پنل ایستا با حاشیه؛ دکمهٔ بستن پنهان
در حال انجام کنش (pending)	روی دکمهٔ کنش، روی دکمه‌ها	در ، و تا پایان Promise کنش؛ موفقیت = بستن، خطا = باز ماندن

رفتار پوشش (از قرارداد در )

دام فوکوس: فوکوس درون پنل حبس می‌شود. با باز شدن به پنل می‌رود و با بسته شدن به محرک برمی‌گردد.
Escape: بالاترین پوشش را می‌بندد و صدا می‌خورد.
پس‌زمینه: کلیک روی پرده می‌بندد؛ با فقط دکمه‌ها و Escape می‌بندند.
قفل اسکرول: اسکرول صفحهٔ زیرین قفل می‌شود؛ فقط بدنهٔ پنل اسکرول می‌خورد ().
تودرتو: پوشش‌های تودرتو با ترتیب DOM روی هم می‌نشینند؛ Escape یکی‌یکی از بالا می‌بندد.
کشیدن برای بستن: اختیاری با (از Modal)؛ معادل غیرکشیدنی دکمهٔ بستن مرئی و Escape است.

تغییرات مجاز برای توسعه‌دهنده

اندازه (): ، (پیش‌فرض)، ، .
تعامل (): (پیش‌فرض)، (با برای کنش مخرب)، ، ، . هر کدام نمونهٔ کد قابل‌کپی در بخش «تعامل‌ها» دارد.
کانفیگ‌های Modal: همهٔ آن‌ها (، ، ، ، ، ، ، ) روی Dialog هم کار می‌کنند.
نقش (): (پیش‌فرض) یا ؛ برای تأیید خطرناک خودکار تنظیم می‌شود.
جهت (): یا . این پراپ locale کلیدهای جهت‌دار React Aria را تنظیم می‌کند؛ چیدمان پنل از جهت سند () می‌آید.
چاپ (): یا .
دکمهٔ بستن: نمایش () و برچسب () قابل ترجمه.
پس‌زمینه (): بستن با کلیک روی پرده یا غیرفعال.
محتوا: ، ، و با گره یا تابع .
کنترل حالت: و ، یا و .
نقاط توسعه: روی ریشه، ()، متغیرهای در سطح پوشش (فهرست در بخش توکن‌ها)، ، و پیام‌های قابل ترجمه (، ، و متن کنش‌ها).

تغییرات ممنوع (بنیان ثابت)

تغییر ترتیب DOM یا حذف های ، ، ، ، .
دور زدن دام فوکوس یا Escape و حذف رفتار پوشش.
تأیید خطرناک () با بستن از پس‌زمینه یا بدون نقش .
حذف (پراپ الزامی؛ نام دسترسی پوشش است).
کوچک‌تر از ۴۴px کردن دکمهٔ بستن: اندازه از و آن از می‌آید.
استایل خام (hex، rgb، gradient) برای پس‌زمینه یا حاشیه. فقط توکن‌های معنایی و .
وابستگی به مسیر asset یا آیکون خارج از .

RTL، کیبورد و صفحه‌خوان

RTL: جهت پیش‌فرض RTL است. در رندر اول فرض می‌شود و در effect از خوانده می‌شود (). ویژگی‌های منطقی (/) استفاده شده‌اند؛ دکمهٔ بستن در است و در RTL به سمت چپ می‌رود.
کلیدها: و فوکوس را درون پنل می‌چرخانند؛ می‌بندد؛ کنترل فوکوس‌دار را فعال می‌کند. کلیدهای جهت‌دار با locale همان جهت ( برای RTL) رفتار می‌کنند.
صفحه‌خوان: نام پنل از عنوان () و توضیح از () می‌آید؛ باز شدن با انتقال فوکوس اعلام می‌شود.
هدف لمسی: دکمهٔ بستن حداقل ۴۴px است.
کنتراست: روشن، تیره و کنتراست بالا با بررسی می‌شوند.

صدا، حرکت، چاپ و کاهش حرکت

صدا: پیش‌فرض بی‌صداست (opt-in). با یا مقصد سراسری ( در ) فعال می‌شود. باز شدن و بسته شدن هر دو هستند؛ هیچ صدایی روی hover پخش نمی‌شود. معادل بصری: ظاهر شدن پنل و انتقال فوکوس. صدا فقط با تعامل صریح کاربر پخش می‌شود.
حرکت: نام معنایی (opacity و scale) برای پنل و (opacity) برای پرده در . زمان و منحنی از و می‌آید.
کاهش حرکت: با یا (وقتی نباشد) انیمیشن و transition حذف می‌شود و پوشش فوری ظاهر و پنهان می‌شود.
چاپ: پیش‌فرض (پوشش در چاپ پنهان است). با پنل ایستا، تک‌رنگ و با حاشیه چاپ می‌شود و دکمهٔ بستن پنهان است.

توکن‌ها

فایل توکن‌های مصرفی: . مقدار مرجع همهٔ در فایل مشترک است.

معنایی: ، ، ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .
تایپوگرافی، کنترل و مقیاس: ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

آیکون دکمهٔ بستن فقط با و نام معنایی است؛ مسیر asset در کد وجود ندارد.
تم فقط حرکت (، ) و توکن‌ها را تغییر می‌دهد؛ ساختار و رفتار پوشش ثابت است.
این کامپوننت gesture ندارد؛ کشیدن برای بستن عمداً تعریف نشده است.

نکات

برای تأیید کنش مخرب یا بازگشت‌ناپذیر: دیالوگ تأیید — AlertDialog.
برای تغییر خودکار مودال به کشو در موبایل: ResponsiveDialog.
برای محتوای کوچک کنار محرک بدون پرده: Popover. برای پنل کناری: Drawer.

دیالوگ — Dialog

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Dialog } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

پایه: محرک، عنوان، توضیح و کنش‌ها

TSX

import { Dialog, Button } from '@tokapps/tuk';export function IdeaDialog() {  return (    <Dialog      trigger={<Button>ثبت ایده</Button>}      title="ثبت ایدهٔ جدید"      description="ایده‌ات را کوتاه و روشن بنویس تا جامعه بتواند ارزیابی‌اش کند."      footer={({ close }) => (        <>          <Button variant="ghost" onClick={close}>بعداً</Button>          <Button onClick={close}>ثبت ایده</Button>        </>      )}    >      <p>پس از ثبت، ایده در بخش «در حال بررسی» نمایش داده می‌شود.</p>    </Dialog>  );}

پیشرفته: کنترل‌شده، اندازهٔ بزرگ، بدون بستن با پس‌زمینه و کنش ناهمگام

TSX

import { useState } from 'react';import { Dialog, Button } from '@tokapps/tuk';import { submitIdea } from './api'; // تابع ارسال خود اپexport function SubmitIdeaDialog() {  const [open, setOpen] = useState(false);  return (    <>      <Button variant="secondary" onClick={() => setOpen(true)}>باز کردن فرم</Button>      <Dialog        open={open}        onOpenChange={setOpen}        size="lg"        dismissable={false}        title="ثبت ایدهٔ جدید"        description="کلیک روی پس‌زمینه این پنجره را نمی‌بندد؛ از دکمه‌ها یا Escape استفاده کنید."        footer={({ close }) => (          <>            <Button variant="ghost" onClick={close}>انصراف</Button>            <Button              action={async () => {                await submitIdea();                close();              }}            >              ثبت ایده            </Button>          </>        )}      >        <p>متن ایده را در فیلدهای زیر وارد کنید.</p>      </Dialog>    </>  );}

حالت محدود: بدون دکمهٔ بستن، با چاپ قابل نمایش

TSX

import { Dialog, Button } from '@tokapps/tuk';export function ProcessNotice() {  return (    <Dialog      size="sm"      showClose={false}      print="show"      trigger={<Button variant="secondary">وضعیت پردازش</Button>}      title="در حال بررسی"      footer={({ close }) => <Button onClick={close}>متوجه شدم</Button>}    >      <p>ایده‌ات تا ۲۴ ساعت آینده بررسی می‌شود. این پنجره با «متوجه شدم» یا کلید Escape بسته می‌شود.</p>    </Dialog>  );}

تأیید: انصراف و تأیید

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', onConfirm: () => undefined, onCancel: () => undefined, confirmLabel: 'ذخیره', cancelLabel: 'انصراف' }}      trigger={<Button>ذخیرهٔ تغییرات</Button>}      title="ذخیرهٔ تغییرات؟"      description="تغییرات این صفحه ذخیره شود."    />  );}

تأیید خطرناک: alertdialog بدون بستن با پس‌زمینه

TSX

import { Button, Dialog } from '@tokapps/tuk';export function DangerConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', tone: 'danger', confirmLabel: 'حذف ایده', onConfirm: () => undefined }}      trigger={<Button variant="secondary">حذف ایده</Button>}      title="این ایده حذف شود؟"      description="این کار بازگشت‌پذیر نیست. پوشش با پس‌زمینه بسته نمی‌شود و نقش alertdialog دارد."    />  );}

تأیید ناهمزمان: دکمه‌ها تا پایان کنش غیرفعال

TSX

import { Button, Dialog } from '@tokapps/tuk';const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));export function AsyncConfirmDialog() {  return (    <Dialog      interaction={{ kind: 'confirm', confirmLabel: 'ارسال', onConfirm: () => wait(1200) }}      trigger={<Button>ارسال با انتظار</Button>}      title="ارسال درخواست؟"      description="تا پایان ارسال، دکمه‌ها غیرفعال می‌مانند و پوشش بعد از موفقیت بسته می‌شود."    />  );}

فرم: FormData و ارسال با Enter

TSX

import { Button, Dialog } from '@tokapps/tuk';export function FormDialog() {  return (    <Dialog      interaction={{ kind: 'form', submitLabel: 'ثبت ایده', onSubmit: (data) => console.info(data.get('title')) }}      trigger={<Button>فرم ثبت ایده</Button>}      title="ثبت ایدهٔ جدید"      description="عنوان را وارد کن؛ Enter هم فرم را ارسال می‌کند."    >      <label style={{ display: 'grid', gap: 'var(--tds-space-1)' }}>        عنوان        <input name="title" required />      </label>    </Dialog>  );}

فرم بدون بستن پس از ارسال

TSX

import { Button, Dialog } from '@tokapps/tuk';const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));export function KeepOpenFormDialog() {  return (    <Dialog      interaction={{ kind: 'form', closeOnSubmit: false, submitLabel: 'ذخیره و ادامه', onSubmit: () => wait(600) }}      trigger={<Button variant="secondary">فرم بدون بستن</Button>}      title="ویرایش سریع"    >      <label style={{ display: 'grid', gap: 'var(--tds-space-1)' }}>        یادداشت        <input name="note" />      </label>    </Dialog>  );}

انتخاب از فهرست: هر گزینه یک تصمیم

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ChoiceDialog() {  return (    <Dialog      interaction={{        kind: 'choice',        onChoose: () => undefined,        options: [          { value: 'publish', label: 'انتشار عمومی', description: 'همه می‌توانند ببینند.' },          { value: 'draft', label: 'ذخیره به‌صورت پیش‌نویس', description: 'فقط برای تو قابل‌دیدن است.' },          { value: 'discard', label: 'حذف پیش‌نویس', tone: 'danger' },        ],      }}      trigger={<Button>انتخاب وضعیت</Button>}      title="این ایده چه وضعیتی داشته باشد؟"    />  );}

ویزارد چندمرحله‌ای

TSX

import { Button, Dialog } from '@tokapps/tuk';export function WizardDialog() {  return (    <Dialog      interaction={{        kind: 'wizard',        onFinish: () => undefined,        steps: [          { id: 'title', title: 'عنوان', content: <input aria-label="عنوان" name="title" /> },          { id: 'body', title: 'شرح', content: <textarea aria-label="شرح" name="body" /> },          { id: 'review', title: 'بازبینی', content: 'همه‌چیز آماده است؛ پایان را بزن.' },        ],      }}      trigger={<Button>راهنمای ثبت</Button>}      title="ثبت ایده در سه مرحله"    />  );}

کانفیگ‌های Modal روی Dialog (ارث‌بری)

TSX

import { Button, Dialog } from '@tokapps/tuk';export function ModalConfigsDialog() {  return (    <Dialog      glow="ambient"      border="rainbow"      dock="visible"      scrim="dim"      placement="top"      sound={{ open: 'notify', close: 'tap' }}      swipeToDismiss      trigger={<Button>همهٔ کانفیگ‌های Modal</Button>}      title="دیالوگ با حالت‌های Modal"      footer={({ close }) => <Button onClick={close}>فهمیدم</Button>}    >      هر کانفیگ Modal (glow، border، dock، scrim، placement، motion، sound، swipeToDismiss) روی Dialog هم کار می‌کند.    </Dialog>  );}

همهٔ پیکربندی‌ها

همهٔ پراپ‌های () را می‌گیرد و فقط را اضافه می‌کند (). پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

پراپ	نوع	پیش‌فرض	توضیح
		—	محرک باز کردن؛ با به رویداد press وصل می‌شود. بدون آن با کنترل کنید.
		—	حالت کنترل‌شده.
		—	حالت کنترل‌نشدهٔ اولیه.
		—	با هر تغییر باز یا بسته صدا می‌خورد؛ قبل از آن صدای متناظر (در صورت وجود) پخش می‌شود.
		بدون پیش‌فرض (الزامی)	عنوان؛ نام دسترسی پنجره از آن گرفته می‌شود.
		—	توضیح زیر عنوان؛ به‌صورت وصل می‌شود.
		—	ناحیهٔ کنش‌ها؛ با تابع می‌توان را گرفت. برای ، و نادیده گرفته می‌شود.
			نوع تعامل: · (با ، ، ) · (با ) · (با ، ) · (با ، ).
· · · · · · · · · ·	—	—	همان کانفیگ‌های Modal؛ جدول کامل در .
		—	بدنهٔ اسکرول‌پذیر؛ با تابع می‌توان را گرفت.
			عرض پنل از ؛ تمام‌صفحه بدون گوشهٔ گرد و بدون حاشیه (موبایل کوچک).
			نقش ARIA. تأیید با خودکار می‌شود؛ هم همان قرارداد را دارد.
		( برای تأیید خطرناک)	یعنی کلیک روی پرده نمی‌بندد؛ فقط دکمه‌ها و Escape.
			نمایش دکمهٔ بستن مرئی در گوشهٔ انتهایی.
			برچسب دسترس‌پذیر دکمهٔ بستن.
		—	مقدار روی ریشه؛ برای نشانه‌گذاری نمای ResponsiveDialog.
		—	نام دسترسی وقتی عنوان مرئی ندارید.
		—	مقصد اختصاصی صدا (opt-in).
			رفتار چاپ؛ پنل را ایستا چاپ می‌کند.
		از	جهت صریح؛ پیش‌فرض RTL است.
		—	کلاس اضافه روی ریشهٔ پوشش ().

ساختار و اسلات‌ها

ترتیب DOM و ثابت‌اند؛ ، توکن‌ها و استایل‌های هویتی فقط ظاهر را تغییر می‌دهند.

code

ModalOverlay  [data-tds="dialog"][data-overlay="modal"][data-size][data-print]└── Modal  [data-part="panel"]    └── RacDialog  [data-part="dialog"][role]        ├── button  [data-part="close"]        (فقط وقتی showClose)        ├── header  [data-part="header"]        │   └── div  [data-part="heading"]        │       ├── Heading  [data-part="title"]        (slot=title)        │       └── p  [data-part="description"]        (فقط وقتی description)        ├── div  [data-part="body"]            (فقط وقتی children)        └── footer  [data-part="footer"]       (فقط وقتی footer)

بنیان ثابت: ترتیب بالا، ها، ، ارتباط و ، و جای دکمهٔ بستن در انتهای خط.
قابل تغییر: روی ریشه، متغیرهای ، و محتوای ، .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	پوشش در DOM نیست	—
در حال ورود	روی و (از React Aria)	پرده با fade و پنل با ، مدت
باز (open)		پرده و پنل؛ بقیهٔ صفحه
در حال خروج		fade-out و pop-out
پیش‌فرض (دکمهٔ بستن)	—	شفاف، رنگ
hover (دکمهٔ بستن)		پس‌زمینه ، رنگ
pressed (دکمهٔ بستن)		پس‌زمینه
focus-visible	روی دکمهٔ بستن و کنترل‌های داخل پنل (نه خود )	حلقهٔ
	در React Aria	کلیک پرده نمی‌بندد
		تمام‌صفحه، بدون حاشیه و گوشهٔ گرد
چاپ		پنل ایستا با حاشیه؛ دکمهٔ بستن پنهان
در حال انجام کنش (pending)	روی دکمهٔ کنش، روی دکمه‌ها	در ، و تا پایان Promise کنش؛ موفقیت = بستن، خطا = باز ماندن

رفتار پوشش (از قرارداد در )

دام فوکوس: فوکوس درون پنل حبس می‌شود. با باز شدن به پنل می‌رود و با بسته شدن به محرک برمی‌گردد.
Escape: بالاترین پوشش را می‌بندد و صدا می‌خورد.
پس‌زمینه: کلیک روی پرده می‌بندد؛ با فقط دکمه‌ها و Escape می‌بندند.
قفل اسکرول: اسکرول صفحهٔ زیرین قفل می‌شود؛ فقط بدنهٔ پنل اسکرول می‌خورد ().
تودرتو: پوشش‌های تودرتو با ترتیب DOM روی هم می‌نشینند؛ Escape یکی‌یکی از بالا می‌بندد.
کشیدن برای بستن: اختیاری با (از Modal)؛ معادل غیرکشیدنی دکمهٔ بستن مرئی و Escape است.

تغییرات مجاز برای توسعه‌دهنده

اندازه (): ، (پیش‌فرض)، ، .
تعامل (): (پیش‌فرض)، (با برای کنش مخرب)، ، ، . هر کدام نمونهٔ کد قابل‌کپی در بخش «تعامل‌ها» دارد.
کانفیگ‌های Modal: همهٔ آن‌ها (، ، ، ، ، ، ، ) روی Dialog هم کار می‌کنند.
نقش (): (پیش‌فرض) یا ؛ برای تأیید خطرناک خودکار تنظیم می‌شود.
جهت (): یا . این پراپ locale کلیدهای جهت‌دار React Aria را تنظیم می‌کند؛ چیدمان پنل از جهت سند () می‌آید.
چاپ (): یا .
دکمهٔ بستن: نمایش () و برچسب () قابل ترجمه.
پس‌زمینه (): بستن با کلیک روی پرده یا غیرفعال.
محتوا: ، ، و با گره یا تابع .
کنترل حالت: و ، یا و .
نقاط توسعه: روی ریشه، ()، متغیرهای در سطح پوشش (فهرست در بخش توکن‌ها)، ، و پیام‌های قابل ترجمه (، ، و متن کنش‌ها).

تغییرات ممنوع (بنیان ثابت)

تغییر ترتیب DOM یا حذف های ، ، ، ، .
دور زدن دام فوکوس یا Escape و حذف رفتار پوشش.
تأیید خطرناک () با بستن از پس‌زمینه یا بدون نقش .
حذف (پراپ الزامی؛ نام دسترسی پوشش است).
کوچک‌تر از ۴۴px کردن دکمهٔ بستن: اندازه از و آن از می‌آید.
استایل خام (hex، rgb، gradient) برای پس‌زمینه یا حاشیه. فقط توکن‌های معنایی و .
وابستگی به مسیر asset یا آیکون خارج از .

RTL، کیبورد و صفحه‌خوان

RTL: جهت پیش‌فرض RTL است. در رندر اول فرض می‌شود و در effect از خوانده می‌شود (). ویژگی‌های منطقی (/) استفاده شده‌اند؛ دکمهٔ بستن در است و در RTL به سمت چپ می‌رود.
کلیدها: و فوکوس را درون پنل می‌چرخانند؛ می‌بندد؛ کنترل فوکوس‌دار را فعال می‌کند. کلیدهای جهت‌دار با locale همان جهت ( برای RTL) رفتار می‌کنند.
صفحه‌خوان: نام پنل از عنوان () و توضیح از () می‌آید؛ باز شدن با انتقال فوکوس اعلام می‌شود.
هدف لمسی: دکمهٔ بستن حداقل ۴۴px است.
کنتراست: روشن، تیره و کنتراست بالا با بررسی می‌شوند.

صدا، حرکت، چاپ و کاهش حرکت

صدا: پیش‌فرض بی‌صداست (opt-in). با یا مقصد سراسری ( در ) فعال می‌شود. باز شدن و بسته شدن هر دو هستند؛ هیچ صدایی روی hover پخش نمی‌شود. معادل بصری: ظاهر شدن پنل و انتقال فوکوس. صدا فقط با تعامل صریح کاربر پخش می‌شود.
حرکت: نام معنایی (opacity و scale) برای پنل و (opacity) برای پرده در . زمان و منحنی از و می‌آید.
کاهش حرکت: با یا (وقتی نباشد) انیمیشن و transition حذف می‌شود و پوشش فوری ظاهر و پنهان می‌شود.
چاپ: پیش‌فرض (پوشش در چاپ پنهان است). با پنل ایستا، تک‌رنگ و با حاشیه چاپ می‌شود و دکمهٔ بستن پنهان است.

توکن‌ها

فایل توکن‌های مصرفی: . مقدار مرجع همهٔ در فایل مشترک است.

معنایی: ، ، ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .
تایپوگرافی، کنترل و مقیاس: ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

آیکون دکمهٔ بستن فقط با و نام معنایی است؛ مسیر asset در کد وجود ندارد.
تم فقط حرکت (، ) و توکن‌ها را تغییر می‌دهد؛ ساختار و رفتار پوشش ثابت است.
این کامپوننت gesture ندارد؛ کشیدن برای بستن عمداً تعریف نشده است.

نکات

برای تأیید کنش مخرب یا بازگشت‌ناپذیر: دیالوگ تأیید — AlertDialog.
برای تغییر خودکار مودال به کشو در موبایل: ResponsiveDialog.
برای محتوای کوچک کنار محرک بدون پرده: Popover. برای پنل کناری: Drawer.

دیالوگ — Dialog

نمونهٔ زنده

کد قابل کپی

پایه: محرک، عنوان، توضیح و کنش‌ها

پیشرفته: کنترل‌شده، اندازهٔ بزرگ، بدون بستن با پس‌زمینه و کنش ناهمگام

حالت محدود: بدون دکمهٔ بستن، با چاپ قابل نمایش

تعامل‌ها (Dialog = Modal + interaction)

تأیید: انصراف و تأیید

تأیید خطرناک: alertdialog بدون بستن با پس‌زمینه

تأیید ناهمزمان: دکمه‌ها تا پایان کنش غیرفعال

فرم: FormData و ارسال با Enter

فرم بدون بستن پس از ارسال

انتخاب از فهرست: هر گزینه یک تصمیم

ویزارد چندمرحله‌ای

کانفیگ‌های Modal روی Dialog (ارث‌بری)

همهٔ پیکربندی‌ها

ساختار و اسلات‌ها

همهٔ حالت‌ها

رفتار پوشش (از قرارداد modalBaseکپی کدکپی کد در _shared/contract.tsکپی کدکپی کد)

تغییرات مجاز برای توسعه‌دهنده

تغییرات ممنوع (بنیان ثابت)

RTL، کیبورد و صفحه‌خوان

صدا، حرکت، چاپ و کاهش حرکت

توکن‌ها

قرارداد ARCH

نکات

دیالوگ — Dialog

نمونهٔ زنده

کد قابل کپی

پایه: محرک، عنوان، توضیح و کنش‌ها

پیشرفته: کنترل‌شده، اندازهٔ بزرگ، بدون بستن با پس‌زمینه و کنش ناهمگام

حالت محدود: بدون دکمهٔ بستن، با چاپ قابل نمایش

تعامل‌ها (Dialog = Modal + interaction)

تأیید: انصراف و تأیید

تأیید خطرناک: alertdialog بدون بستن با پس‌زمینه

تأیید ناهمزمان: دکمه‌ها تا پایان کنش غیرفعال

فرم: FormData و ارسال با Enter

فرم بدون بستن پس از ارسال

انتخاب از فهرست: هر گزینه یک تصمیم

ویزارد چندمرحله‌ای

کانفیگ‌های Modal روی Dialog (ارث‌بری)

همهٔ پیکربندی‌ها

ساختار و اسلات‌ها

همهٔ حالت‌ها

رفتار پوشش (از قرارداد modalBaseکپی کدکپی کد در _shared/contract.tsکپی کدکپی کد)

تغییرات مجاز برای توسعه‌دهنده

تغییرات ممنوع (بنیان ثابت)

RTL، کیبورد و صفحه‌خوان

صدا، حرکت، چاپ و کاهش حرکت

توکن‌ها

قرارداد ARCH

نکات

رفتار پوشش (از قرارداد در )

رفتار پوشش (از قرارداد در )