دیالوگ تأیید — AlertDialog

برای تأیید یک کنش مهم یا بازگشت‌ناپذیر است، مثل حذف یا ارسال نهایی. نقش آن است و صفحه‌خوان بلافاصله عنوان و توضیح را می‌خواند. کلیک روی پرده آن را نمی‌بندد تا تصمیم آگاهانه باشد؛ Escape معادل انصراف است و فوکوس اولیه روی «انصراف» می‌نشیند، یعنی کم‌خطرترین گزینه. دکمهٔ بستن مرئی ندارد. برای فرم یا محتوای غنی از استفاده کنید.

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه: تأیید ساده

TSX

import { AlertDialog, Button } from '@tokapps/tuk';export function SubmitIdeaConfirm() {  return (    <AlertDialog      trigger={<Button variant="secondary">ارسال برای بررسی</Button>}      title="ارسال ایده برای بررسی؟"      description="پس از ارسال، ویرایش تا پایان بررسی ممکن نیست."      confirmLabel="ارسال"    />  );}

مخرب با تأیید ناهمگام

TSX

import { AlertDialog, Button } from '@tokapps/tuk';import { deleteCampaign } from './api'; // تابع حذف خود اپexport function DeleteCampaignConfirm() {  return (    <AlertDialog      tone="danger"      trigger={<Button variant="ghost">حذف کمپین</Button>}      title="کمپین حذف شود؟"      description="همهٔ حمایت‌ها و نظرها برای همیشه حذف می‌شود."      confirmLabel="حذف کمپین"      cancelLabel="نگه‌داشتن کمپین"      toneLabel="این کنش بازگشت‌پذیر نیست"      onConfirm={() => deleteCampaign()}      onCancel={() => console.log('انصراف')}    />  );}

کنترل‌شده با محتوای اضافه و تأیید ناهمگام

TSX

import { useState } from 'react';import { AlertDialog, Button } from '@tokapps/tuk';export function LeaveWithoutSaving() {  const [open, setOpen] = useState(false);  return (    <>      <Button variant="secondary" onClick={() => setOpen(true)}>خروج از ویرایش</Button>      <AlertDialog        open={open}        onOpenChange={setOpen}        tone="danger"        title="تغییرات ذخیره نشده"        description="اگر خارج شوید، تغییرات این صفحه از بین می‌رود."        confirmLabel="خروج بدون ذخیره"        onConfirm={() => new Promise((resolve) => setTimeout(resolve, 800))}      >        <p>می‌توانید ابتدا ذخیره کنید و سپس خارج شوید.</p>      </AlertDialog>    </>  );}

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

پراپ‌ها را از با حذف ، ، و می‌گیرد (در ). پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

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

در کد تعریف نشده است؛ عرض پنل با CSS ثابت است ().

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

code

ModalOverlay  [data-tds="alert-dialog"][data-overlay="modal"][data-tone][data-print]└── Modal  [data-part="panel"]    └── RacDialog  [data-part="dialog"][role="alertdialog"]        ├── header  [data-part="header"]        │   ├── span  [data-part="icon"][data-tone]    (آیکون status.warning یا status.info)        │   └── div  [data-part="heading"]        │       ├── Heading  [data-part="title"]        │       └── p  [data-part="description"]        └── div  [data-part="body"]            ├── p  [data-part="tone-label"]    (فقط tone="danger")            └── children        └── footer  [data-part="footer"]            ├── Button variant="secondary" (انصراف، autoFocus)            └── Button با data-tone (تأیید)

بنیان ثابت: نبود دکمهٔ بستن مرئی، نقش ، ترتیب فوتر (انصراف سپس تأیید)، و روی انصراف.
قابل تغییر: متن‌ها، ، محتوای ، و . رنگ‌ها فقط از توکن‌های معنایی می‌آیند.

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	پوشش در DOM نیست	—
باز، لحن پیش‌فرض	روی ریشه	آیکون با رنگ
باز، لحن مخرب	روی ریشه و روی آیکون	آیکون ، برچسب متنی لحن، دکمهٔ تأیید با و متن
در حال انتظار تأیید	و روی دکمهٔ تأیید (از )	حلقهٔ پردازش روی دکمه؛ کلیک مجدد نادیده گرفته می‌شود
hover و pressed	، روی دکمه‌ها	از استایل
focus-visible	روی دکمه‌ها	حلقهٔ
کلیک روی پرده		پوشش بسته نمی‌شود
چاپ		پنل بدون فوتر چاپ می‌شود
غیرفعال، خطا، فقط‌خواندنی	در کد تعریف نشده	—

رفتار پوشش (از قرارداد و تنظیمات این کامپوننت)

دام فوکوس: فوکوس درون پنل حبس می‌شود؛ با باز شدن روی «انصراف» و با بسته شدن به محرک برمی‌گردد.
Escape: پوشش را می‌بندد و صدا می‌خورد. در این مسیر صدا زده نمی‌شود.
پس‌زمینه: کلیک روی پرده نمی‌بندد؛ فقط «انصراف»، «تأیید» یا Escape.
قفل اسکرول: اسکرول صفحهٔ زیرین قفل است؛ بدنهٔ پنل اسکرول می‌خورد.
بستن با دکمهٔ بستن: ندارد. عمداً حذف شده و جایگزین آن «انصراف» و Escape است.
کشیدن برای بستن: ندارد.
در حین انتظار تأیید: دکمهٔ انصراف و Escape غیرفعال نمی‌شوند؛ در کد، فقط دکمهٔ تأیید وضعیت انتظار دارد.

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

لحن (): یا .
برچسب‌ها: ، ، (قابل ترجمه).
تأیید: همگام یا Promise؛ Promise باعث حالت انتظار و سپس بسته شدن می‌شود.
انصراف: برای اقدام جانبی دکمهٔ انصراف.
کنترل حالت: و ، یا و .
محتوا: ، و .
نقاط توسعه: روی ریشه، ، ، ، و متغیرهای در سطح پوشش.

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

افزودن دکمهٔ بستن مرئی یا بستن با کلیک روی پرده. این رفتار بخشی از قرارداد است.
تغییر نقش به یا حذف وقتی توضیح هست.
حذف از «انصراف» یا قرار دادن فوکوس اولیه روی تأیید.
حذف برچسب متنی لحن مخرب. رنگ تنها نشانه نیست؛ آیکون و برچسب متنی همیشه باید باشند.
کوچک‌تر از ۴۴px کردن دکمه‌ها (دکمه‌ها از می‌آیند).

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

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

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

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

توکن‌ها

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

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

قرارداد ARCH

آیکون‌های هشدار و اطلاع فقط با و (نام معنایی) هستند؛ مسیر asset در کد وجود ندارد.
تم فقط حرکت و توکن را تغییر می‌دهد؛ نقش، ترتیب DOM و رفتار انصراف ثابت‌اند.
این کامپوننت gesture ندارد؛ معادل کیبوردی تأیید و انصراف دکمه‌ها و Escape هستند.

نکات

برای فرم یا محتوای غنی: Dialog.
برای اطلاع‌رسانی غیرمسدودکننده: Toast.
برای هشدار درون صفحه بدون تعامل: Toast.
برای پیام‌های خروج یا حذف با نمای موبایل: ResponsiveDialog.

دیالوگ تأیید — AlertDialog

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه: تأیید ساده

TSX

import { AlertDialog, Button } from '@tokapps/tuk';export function SubmitIdeaConfirm() {  return (    <AlertDialog      trigger={<Button variant="secondary">ارسال برای بررسی</Button>}      title="ارسال ایده برای بررسی؟"      description="پس از ارسال، ویرایش تا پایان بررسی ممکن نیست."      confirmLabel="ارسال"    />  );}

مخرب با تأیید ناهمگام

TSX

import { AlertDialog, Button } from '@tokapps/tuk';import { deleteCampaign } from './api'; // تابع حذف خود اپexport function DeleteCampaignConfirm() {  return (    <AlertDialog      tone="danger"      trigger={<Button variant="ghost">حذف کمپین</Button>}      title="کمپین حذف شود؟"      description="همهٔ حمایت‌ها و نظرها برای همیشه حذف می‌شود."      confirmLabel="حذف کمپین"      cancelLabel="نگه‌داشتن کمپین"      toneLabel="این کنش بازگشت‌پذیر نیست"      onConfirm={() => deleteCampaign()}      onCancel={() => console.log('انصراف')}    />  );}

کنترل‌شده با محتوای اضافه و تأیید ناهمگام

TSX

import { useState } from 'react';import { AlertDialog, Button } from '@tokapps/tuk';export function LeaveWithoutSaving() {  const [open, setOpen] = useState(false);  return (    <>      <Button variant="secondary" onClick={() => setOpen(true)}>خروج از ویرایش</Button>      <AlertDialog        open={open}        onOpenChange={setOpen}        tone="danger"        title="تغییرات ذخیره نشده"        description="اگر خارج شوید، تغییرات این صفحه از بین می‌رود."        confirmLabel="خروج بدون ذخیره"        onConfirm={() => new Promise((resolve) => setTimeout(resolve, 800))}      >        <p>می‌توانید ابتدا ذخیره کنید و سپس خارج شوید.</p>      </AlertDialog>    </>  );}

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

پراپ‌ها را از با حذف ، ، و می‌گیرد (در ). پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

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

در کد تعریف نشده است؛ عرض پنل با CSS ثابت است ().

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

code

ModalOverlay  [data-tds="alert-dialog"][data-overlay="modal"][data-tone][data-print]└── Modal  [data-part="panel"]    └── RacDialog  [data-part="dialog"][role="alertdialog"]        ├── header  [data-part="header"]        │   ├── span  [data-part="icon"][data-tone]    (آیکون status.warning یا status.info)        │   └── div  [data-part="heading"]        │       ├── Heading  [data-part="title"]        │       └── p  [data-part="description"]        └── div  [data-part="body"]            ├── p  [data-part="tone-label"]    (فقط tone="danger")            └── children        └── footer  [data-part="footer"]            ├── Button variant="secondary" (انصراف، autoFocus)            └── Button با data-tone (تأیید)

بنیان ثابت: نبود دکمهٔ بستن مرئی، نقش ، ترتیب فوتر (انصراف سپس تأیید)، و روی انصراف.
قابل تغییر: متن‌ها، ، محتوای ، و . رنگ‌ها فقط از توکن‌های معنایی می‌آیند.

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	پوشش در DOM نیست	—
باز، لحن پیش‌فرض	روی ریشه	آیکون با رنگ
باز، لحن مخرب	روی ریشه و روی آیکون	آیکون ، برچسب متنی لحن، دکمهٔ تأیید با و متن
در حال انتظار تأیید	و روی دکمهٔ تأیید (از )	حلقهٔ پردازش روی دکمه؛ کلیک مجدد نادیده گرفته می‌شود
hover و pressed	، روی دکمه‌ها	از استایل
focus-visible	روی دکمه‌ها	حلقهٔ
کلیک روی پرده		پوشش بسته نمی‌شود
چاپ		پنل بدون فوتر چاپ می‌شود
غیرفعال، خطا، فقط‌خواندنی	در کد تعریف نشده	—

رفتار پوشش (از قرارداد و تنظیمات این کامپوننت)

دام فوکوس: فوکوس درون پنل حبس می‌شود؛ با باز شدن روی «انصراف» و با بسته شدن به محرک برمی‌گردد.
Escape: پوشش را می‌بندد و صدا می‌خورد. در این مسیر صدا زده نمی‌شود.
پس‌زمینه: کلیک روی پرده نمی‌بندد؛ فقط «انصراف»، «تأیید» یا Escape.
قفل اسکرول: اسکرول صفحهٔ زیرین قفل است؛ بدنهٔ پنل اسکرول می‌خورد.
بستن با دکمهٔ بستن: ندارد. عمداً حذف شده و جایگزین آن «انصراف» و Escape است.
کشیدن برای بستن: ندارد.
در حین انتظار تأیید: دکمهٔ انصراف و Escape غیرفعال نمی‌شوند؛ در کد، فقط دکمهٔ تأیید وضعیت انتظار دارد.

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

لحن (): یا .
برچسب‌ها: ، ، (قابل ترجمه).
تأیید: همگام یا Promise؛ Promise باعث حالت انتظار و سپس بسته شدن می‌شود.
انصراف: برای اقدام جانبی دکمهٔ انصراف.
کنترل حالت: و ، یا و .
محتوا: ، و .
نقاط توسعه: روی ریشه، ، ، ، و متغیرهای در سطح پوشش.

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

افزودن دکمهٔ بستن مرئی یا بستن با کلیک روی پرده. این رفتار بخشی از قرارداد است.
تغییر نقش به یا حذف وقتی توضیح هست.
حذف از «انصراف» یا قرار دادن فوکوس اولیه روی تأیید.
حذف برچسب متنی لحن مخرب. رنگ تنها نشانه نیست؛ آیکون و برچسب متنی همیشه باید باشند.
کوچک‌تر از ۴۴px کردن دکمه‌ها (دکمه‌ها از می‌آیند).

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

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

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

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

توکن‌ها

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

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

قرارداد ARCH

آیکون‌های هشدار و اطلاع فقط با و (نام معنایی) هستند؛ مسیر asset در کد وجود ندارد.
تم فقط حرکت و توکن را تغییر می‌دهد؛ نقش، ترتیب DOM و رفتار انصراف ثابت‌اند.
این کامپوننت gesture ندارد؛ معادل کیبوردی تأیید و انصراف دکمه‌ها و Escape هستند.

نکات

برای فرم یا محتوای غنی: Dialog.
برای اطلاع‌رسانی غیرمسدودکننده: Toast.
برای هشدار درون صفحه بدون تعامل: Toast.
برای پیام‌های خروج یا حذف با نمای موبایل: ResponsiveDialog.

دیالوگ تأیید — AlertDialog

نمونهٔ زنده

کد قابل کپی

پایه: تأیید ساده

مخرب با تأیید ناهمگام

کنترل‌شده با محتوای اضافه و تأیید ناهمگام

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

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

همهٔ حالت‌ها

رفتار پوشش (از قرارداد modalBaseکپی کدکپی کد و تنظیمات این کامپوننت)

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

دیالوگ تأیید — AlertDialog

نمونهٔ زنده

کد قابل کپی

پایه: تأیید ساده

مخرب با تأیید ناهمگام

کنترل‌شده با محتوای اضافه و تأیید ناهمگام

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

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

همهٔ حالت‌ها

رفتار پوشش (از قرارداد modalBaseکپی کدکپی کد و تنظیمات این کامپوننت)

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

رفتار پوشش (از قرارداد و تنظیمات این کامپوننت)

رفتار پوشش (از قرارداد و تنظیمات این کامپوننت)