دیالوگ واکنش‌گرا — ResponsiveDialog

ResponsiveDialog یک API برای محتوای مودال است که بر اساس عرض صفحه نمایش خود را انتخاب می‌کند. در دسکتاپ نمایش داده می‌شود، در تبلت و موبایل یا بر اساس و ، و در عرض ۳۶۰px و کمتر یک دیالوگ تمام‌صفحه. وضعیت باز یا بسته در همین کامپوننت می‌ماند و با تغییر نمایش، محتوای داخلی دوباره سوار می‌شود. این کامپوننت ترکیبی از و است و ظاهر هر نمایش را از همان‌ها می‌گیرد.

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه: فرم در همهٔ اندازه‌ها

TSX

import { Button, ResponsiveDialog } from '@tokapps/tuk';export function NewIdeaDialog({ onSubmit }: { onSubmit: () => void }) {  return (    <ResponsiveDialog      trigger={<Button>ثبت ایده</Button>}      title="ثبت ایدهٔ جدید"      description="روی دسکتاپ دیالوگ، روی موبایل برگهٔ پایینی."      footer={({ close }) => (        <>          <Button variant="secondary" onClick={close}>انصراف</Button>          <Button onClick={() => { onSubmit(); close(); }}>ثبت</Button>        </>      )}    >      <p>محتوای فرم اینجا می‌آید.</p>    </ResponsiveDialog>  );}

حالت پیشرفته: کشو در تبلت و موبایل

TSX

import { Button, ResponsiveDialog } from '@tokapps/tuk';export function IdeaFilters() {  return (    <ResponsiveDialog      mobileMode="drawer"      tabletMode="drawer"      drawerSide="start"      trigger={<Button variant="secondary">فیلترها</Button>}      title="فیلتر ایده‌ها"      description="نتایج با هر تغییر به‌روز می‌شود."    >      <p>گزینه‌های فیلتر اینجا می‌آید.</p>    </ResponsiveDialog>  );}

حالت کنترل‌شده و غیرقابل بستن با پس‌زمینه

TSX

import { Button, ResponsiveDialog } from '@tokapps/tuk';import { useState } from 'react';export function UnsavedChangesDialog({ dirty }: { dirty: boolean }) {  const [open, setOpen] = useState(false);  return (    <ResponsiveDialog      open={open}      onOpenChange={setOpen}      dismissable={false}      title="تغییرات ذخیره نشده"      footer={({ close }) => <Button onClick={close}>متوجه شدم</Button>}    >      {dirty ? <p>تغییراتی ذخیره نشده است.</p> : <p>همه‌چیز ذخیره شده است.</p>}    </ResponsiveDialog>  );}

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

نوع	پیش‌فرض	توضیح
یا		نمایش در موبایل (≤ ۶۴۰px). در ≤ ۳۶۰px همین حالت تمام‌صفحه می‌شود.
یا		نمایش در تبلت (≤ ۱۰۲۴px).
· · ·		اندازهٔ دیالوگ در دسکتاپ و در تبلت وقتی است. در نادیده گرفته می‌شود.
یا		لبهٔ کشو وقتی انتخاب شده است.
· · ·	خودکار	نقطهٔ شکست اجباری برای داستان‌ها و تست. در کد اختیاری است؛ بدون آن از استفاده می‌شود.
	—	محرک باز کردن؛ بدون آن با کنترل کنید.
	—	حالت کنترل‌شده.
		حالت اولیه.
	—	با هر تغییر باز/بسته.
	— (الزامی)	عنوان؛ نام دسترسی دیالوگ از آن گرفته می‌شود.
	—	توضیح زیر عنوان.
یا	—	ناحیهٔ کنش‌ها؛ تابع پوشش را می‌بندد.
یا	—	محتوای بدنه.
		کلیک روی پرده بسته شود؟ یعنی فقط دکمه‌ها و Escape.
		دکمهٔ بستن مرئی.
		برچسب دکمهٔ بستن.
	—	نام دسترسی وقتی عنوان مرئی نیست.
	—	مقصد صدای نمایش جاری؛ بدون آن، مقصد سراسری (در صورت ثبت) استفاده می‌شود.
( یا )		رفتار چاپ (ر.ک. بخش چاپ).
	—	جهت صریح؛ بدون مقدار، جهت از ساختار صفحه می‌آید.
	—	کلاس روی نمایش جاری.

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

ریشهٔ ResponsiveDialog یکی از دو کامپوننت () یا () است؛ روی همان ریشه می‌نشیند. داخل آن ترتیب اجزا: · (شامل با و ) · · .

بنیان ثابت: · · · · · · · · (از ) و .
قابل‌تغییر: ، (در دیالوگ)، (در کشو)، و توکن‌های .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته	پوشش در DOM نمایش داده نمی‌شود	فقط محرک دیده می‌شود.
باز (دیالوگ)	· ·	دیالوگ مرکزی با حرکت .
باز (کشو)	· ·	کشو از لبهٔ با حرکت اسلاید.
تمام‌صفحه (≤ ۳۶۰px)	یا ·	پوشش کل صفحه با فاصلهٔ ناحیهٔ امن.
بستن		پوشش محو می‌شود.
close hover		پس‌زمینهٔ .
close pressed		پس‌زمینهٔ .
close focus-visible		حلقهٔ .
غیرقابل بستن با پرده	prop	فقط دکمه‌ها و Escape می‌بندند.
بدون دکمهٔ بستن	prop	فقط Escape یا کنش‌های footer می‌بندند.
کاهش حرکت	یا	بدون انیمیشن ورود و خروج.

نمایش بر اساس نقطهٔ شکست

عرض		نتیجه
بیش از ۱۰۲۴px		با .
≤ ۱۰۲۴px	یا (طبق )	یا .
≤ ۶۴۰px	یا (طبق )	یا .
≤ ۳۶۰px	یا (طبق )	تمام‌صفحه؛ همیشه .

الگوریتم انتخاب (): دسکتاپ → ؛ تبلت → ؛ موبایل و موبایل کوچک → ، با تمام‌صفحه‌شدن در ≤ ۳۶۰px. ترتیب بررسی: ، ، ، سپس .

قرارداد پوشش (Overlay Contract)

دام فوکوس: فوکوس درون پوشش حبس می‌شود (FocusScope با contain)؛ با باز شدن به پوشش می‌رود و با بسته شدن به محرک برمی‌گردد.
Escape: پوشش بالایی را می‌بندد و صدا زده می‌شود.
پس‌زمینه (backdrop): کلیک روی پرده می‌بندد (پیش‌فرض)؛ با فقط دکمه‌ها و Escape می‌بندند.
قفل اسکرول: اسکرول صفحهٔ زیرین قفل می‌شود (usePreventScroll)؛ فقط بدنهٔ پوشش اسکرول می‌خورد و دارد.
کشیدن برای بستن: ندارد؛ بستن همیشه با دکمهٔ بستن مرئی، Escape یا کنش‌های footer ممکن است.
تودرتو: پوشش تودرتو پشتیبانی می‌شود؛ فقط بالاترین پوشش تعاملی است و بقیه می‌شوند.

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

variant: (با یا ) یا (با همان پراپ‌ها).
size: ، ، و در دیالوگ (در فقط یا به‌کار می‌رود).
لبهٔ کشو: با یا ، منطقی و در RTL خودکار برمی‌گردد.
نقطهٔ شکست: برای داستان‌ها و تست.
نقاط توسعه: ، ، ، و با تابع ، ، ، ، ، ، و توکن‌های .

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

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

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

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

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

صدا: opt-in است. رویدادهای و () به‌عنوان نیت پوشش به می‌رسند؛ روی همین نمونه، یا مقصد سراسری با ، و بدون هیچ‌کدام بی‌صداست. معادل بصری: حرکت پنل.
حرکت: نام معنایی با حرکت هر نمایش: برای دیالوگ، برای کشوی کناری و برای کشوی پایینی. با یا بدون انیمیشن است.
چاپ: پیش‌فرض و در چاپ پنهان است. با پوشش در چاپ به‌صورت بلوک ایستا و بدون پرده و دکمهٔ بستن نمایش داده می‌شود (قاعدهٔ در ).

توکن‌ها

فایل توکن‌های کامپوننتی: (گروه overlays؛ این کامپوننت توکن اختصاصی ندارد و از Dialog و Drawer ارث می‌برد).
توکن‌های سطح کامپوننت مصرفی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، و سایر موارد در .
توکن‌های معنایی مصرفی: ، ، ، ، ، ، .
فهرست کامل: .

قرارداد ARCH

آیکون دکمهٔ بستن و کشو فقط با و نام معنایی تعیین می‌شود؛ مسیر asset در کد نمی‌آید.
تم فقط حرکت و توکن‌های مجاز را تغییر می‌دهد؛ انتخاب نمایش و ARIA ثابت‌اند.
این کامپوننت gesture ندارد؛ کشیدن برای بستن وجود ندارد و Escape و دکمهٔ بستن جایگزین آن هستند.

نکات

برای نمایش ثابت و همیشه مرکزی از Dialog استفاده کنید؛ برای کشوی همیشه کناری از Drawer.
برای تأیید کنش مخرب از AlertDialog استفاده کنید.
برای جستجو و اجرای سریع کنش از CommandMenu استفاده کنید.
در حالت روی موبایل، اولین رندر در نقطهٔ شکست انجام می‌شود و سپس نمایش اصلاح می‌شود؛ برای جلوگیری از پرش، از کنترل‌شده با مقدار مشخص استفاده کنید.