دکمه (Button)

معرفی

دکمه برای اجرای اقدامات و ارسال فرم‌ها استفاده می‌شود.

چه زمانی استفاده کنیم:

• برای شروع یک عملیات (ذخیره، ارسال، حذف)
• برای ناوبری با ظاهر دکمه (با asChild)
• برای تأیید تصمیمات کاربر در دیالوگ‌ها

چه زمانی استفاده نکنیم:

• برای ناوبری ساده بین صفحات — از لینک استفاده کنید
• برای تغییر وضعیت روشن/خاموش — از Toggle یا Switch استفاده کنید
• برای انتخاب از گزینه‌ها — از RadioGroup یا Select استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، دکمه را به صورت زنده مشاهده کنید.

import { Button } from '@partodata/ui'

<Button>
  دکمه نمونه
</Button>

استفاده

import { Button } from '@partodata/ui'

<Button variant="outline">دکمه</Button>

همچنین می‌توانید از prop type استفاده کنید که alias برای variant است تا با استایل Supabase هماهنگ باشد.

لینک

می‌توانید از helper buttonVariants برای ایجاد یک لینک که شبیه دکمه است استفاده کنید.

import { buttonVariants } from '@partodata/ui'

<Link className={buttonVariants({ variant: 'outline' })}>اینجا کلیک کنید</Link>

یا می‌توانید prop asChild را تنظیم کنید و کامپوننت لینک را داخل آن قرار دهید.

<Button asChild>
  <Link href="/login">ورود</Link>
</Button>

مثال‌ها

اندازه‌ها

از prop size برای تعیین اندازه دکمه استفاده کنید. اندازه‌ها روی نردبان کنترل‌ها هستند (نسخهٔ 4.0):

دکمهٔ بدون size از نسخهٔ 4.0 سی پیکسل است (تا 3٫x سی‌وچهار بود). چرا سی: ساختار سوپابیس (دکمهٔ 26 با متن 12)، یک پله راحت‌تر برای فارسی؛ دلیل کامل در اندازه و تراکم.

دکمه‌ای که size ندارد، داخل ControlSizeProvider اندازهٔ Provider را می‌گیرد (از 4.0).

روی اشاره‌گر درشت (گوشی و تبلت) یا زیر data-touch روی <html>، دکمه با هر size دست‌کم 38 پیکسل است و ناحیهٔ لمس 44 پیکسلی دارد (اندازه و تراکم).

دکمهٔ فقط‌آیکون

دکمهٔ فقط‌آیکون (آیکون با icon یا iconEnd، بدون متن، با aria-label) از نسخهٔ 4.0 روی همان نردبان است: مربعی به ارتفاع اندازه‌اش — xs 26، sm 30 (پیش‌فرض)، md 38 و … — داخل ردیف و بیرون از آن، با size صریح یا بدون آن. پس دکمهٔ آیکونی و دکمهٔ متنی یک ردیف همیشه هم‌قدند: یک ردیف، یک ارتفاع.

<Button variant="ghost" icon={<Settings />} aria-label="تنظیمات" />          // مربع 30
<Button variant="ghost" icon={<Settings />} aria-label="تنظیمات" size="md" /> // مربع 38، کنار فیلدهای فرم

متنی که شرطی نمایش داده می‌شود ({!isMobile && 'خروجی'}) وقتی false یا خالی است متن حساب نمی‌شود، پس همان دکمه روی موبایل مربعی است. آیکونی که به‌جای icon به‌صورت children داده شود قابل تشخیص نیست و دکمه فاصلهٔ متنی‌اش را نگه می‌دارد: آیکون را با icon بدهید. فقط آیکونِ تنها مربع می‌سازد: icon همراه iconEnd بدون متن (مثل آواتار و فلش) و دکمهٔ block فاصلهٔ متنی‌شان را نگه می‌دارند. مربع همیشه مربع است، حتی مستقیم داخل یک ستون flex-col (عرضش از ارتفاعش می‌آید) و روی لمس (38 × 38).

رنگ آیکون در icon رنگ آیکونِ خود دکمه است (برای ghost، default و outline: foreground-lighter، کنتراست 5.4 به 1 در تم روشن و 6.5 به 1 در تیره). آیکونی که تا 3٫x به‌صورت children می‌آمد رنگ متن (foreground) را داشت؛ با رفتن به icon کمی کم‌رنگ‌تر می‌شود — همان رنگ آیکون‌های نوار بالا (ThemeToggle، زنگوله‌ها، SidebarTrigger).

اندازه‌های قدیمی icon (36)، icon-sm (28)، icon-xs (24) و icon-lg (40) هیچ‌وقت با دکمه‌های متنی هم‌قد نمی‌شدند؛ در 5.0 حذف شدند. npx --no parto-migrate-v5 هر کدام را به پله‌ای می‌برد که در 4.x می‌داد: icon ← بدون size (30)، icon-sm و icon-xs ← xs (26)، icon-lg ← md (38). اگر جایی واقعاً مربع قدیمی لازم است، ارتفاعش را بدهید؛ عرض از ارتفاع می‌آید:

<Button variant="ghost" icon={<Settings />} aria-label="تنظیمات" className="h-9" /> // مربع 36 مثل icon در 3٫x

انواع

این‌ها تمام انواع مختلف variant (یا type) هستند.

اصلی (Primary)

برای اعمال درج داده، تأیید خرید، اعمال مثبت قوی استفاده می‌شود.

پیش‌فرض (Default)

برای باز کردن دیالوگ‌ها، ناوبری به صفحات و سایر اعمال غیر CRUD استفاده می‌شود.

از نسخهٔ 4.0 دکمهٔ بدون variant همین default خاکستری است (از 2.4 تا 3٫x، primary بود). دکمهٔ اصلی همیشه صریح است و در هر نما فقط یکی:

• در صفحه: دکمه را در primaryAction سرِ صفحه (PageHeader) یا نوار ابزار (PageToolbar) بگذارید؛ دکمهٔ بدون variant در این جایگاه primary رندر می‌شود.
• جای دیگر (پای دیالوگ یا فرم): variant="primary" بنویسید.

ثانویه (Secondary)

می‌تواند برای نشان دادن تغییر داده یا تنظیمات استفاده شود، اما به جدی بودن دکمه primary نیست. برای اعمال مخرب یا با عوارض جانبی، از variant destructive یا warning استفاده کنید.

این variant معکوس است: متن به رنگ صفحه روی زمینه‌ای به رنگ متن. اگر دکمهٔ خاکستری کم‌رنگ می‌خواهید، variant="default" را انتخاب کنید، نه secondary. از نسخهٔ 4.0 متن آن در حالت hover کمی کم‌رنگ می‌شود (80٪) و در focus کامل می‌ماند، و آیکونش هم‌رنگ متن است؛ در همهٔ حالت‌ها و هر دو تم کنتراست دست‌کم 4.5 به 1 دارد. پیش از آن متن در hover و focus ناپدید می‌شد و آیکون هیچ‌وقت دیده نمی‌شد.

هشدار (Warning)

برای اعمالی که ممکن است عوارض جانبی داشته باشند، اما به جدی بودن یک عمل مخرب نیستند استفاده می‌شود.

مخرب (Destructive)

برای اعمالی که عوارض جانبی مخرب جدی خواهند داشت، مانند حذف داده استفاده می‌شود.

variant="destructive" بنویسید (یا به سبک Supabase type="destructive"). نام دوم danger در 5.0 حذف شد.

حاشیه‌دار (Outline)

برای اعمال ثانویه، یا اعمالی که به اهمیت عمل primary نیستند استفاده می‌شود.

خط‌چین (Dashed)

برای اعمال ثانویه با حاشیه خط‌چین استفاده می‌شود.

شبح (Ghost)

برای اعمالی که به اهمیت عمل primary نیستند استفاده می‌شود: بدون پس‌زمینه و حاشیه، و با اشاره‌گر پس‌زمینهٔ surface می‌گیرد. variant="ghost" بنویسید.

متنی (Text)

type="text" (نام سبک Supabase) هم بدون پس‌زمینه و حاشیه است، اما variant جداگانه‌ای است و با ghost یکی نیست: با اشاره‌گر پس‌زمینهٔ accent می‌گیرد، و وقتی منو یا پاپ‌اوری را که باز کرده باز است (data-state="open") پس‌زمینه‌اش می‌ماند. برای دکمه‌ای مناسب است که منو یا پاپ‌اور باز می‌کند.

لینک (Link)

برای اعمالی که به اهمیت عمل primary نیستند استفاده می‌شود.

فقط آیکون

نمایش فقط یک آیکون در یک دکمه.

با آیکون

دکمه‌ها می‌توانند آیکون در سمت چپ یا راست داشته باشند.

حالت‌ها

سه حالت اصلی دکمه — عادی، در حال بارگذاری، و غیرفعال — کنار هم.

غیرفعال همراه با دلیل

وقتی کاربر باید بداند چرا اقدامی در دسترس نیست، به جای disabled از disabledReason استفاده کنید. دکمه غیرفعال می‌شود و دلیل با hover یا فوکوس صفحه‌کلید در Tooltip نمایش داده می‌شود. برای اقدامی که به مجوز یا سهمیه وابسته است و در قالب‌ها قرار می‌گیرد، GatedAction مناسب‌تر است.

<Button disabledReason="سهمیهٔ ارسال این ماه تمام شده است">ارسال گزارش</Button>

حالت بارگذاری

دکمه‌ها می‌توانند حالت بارگذاری را نمایش دهند.

به عنوان فرزند (As Child)

از prop asChild برای رفتار slot پشتیبانی می‌کند.

ویژگی‌ها (Props)

راهنمای استفاده

دسترسی‌پذیری

• از <button> یا <a> مناسب استفاده کنید
• همیشه متن یا aria-label قابل فهم داشته باشید
• حالت فوکوس کیبورد را حفظ کنید
• در صورت نیاز از disabled استفاده کنید

کامپوننت‌های مرتبط

• ButtonGroup — اگر چند دکمه مرتبط را کنار هم نیاز دارید
• Toggle — اگر نیاز به دکمه‌ای با حالت روشن/خاموش دارید
• CopyButton — دکمه آماده برای کپی متن در کلیپبورد