دکمه — Button

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

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه و واریانت‌ها

TSX

import { Button } from '@tokapps/tuk';export function IdeaActions() {  return (    <>      <Button>ثبت ایده</Button>      <Button variant="secondary">انصراف</Button>      <Button variant="ghost">بعداً</Button>    </>  );}

کنش ناهمگام با آیکون

وقتی داده شود، دکمه تا پایان Promise در حالت در حال انجام می‌ماند و حلقهٔ پردازش سراسری روشن است. لازم نیست خودتان را صدا بزنید.

TSX

import { Button } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';// saveIdea را خودتان پیاده‌سازی کنید؛ خطا را throw کنید تا دکمه به حالت عادی برگردد.declare function saveIdea(): Promise<void>;export function SubmitIdea() {  return (    <Button      variant="primary"      size="lg"      icon={<Icon name="check" size="sm" aria-hidden />}      action={() => saveIdea()}    >      ارسال ایده    </Button>  );}

آیکون با انیمیشن

انیمیشن آیکون از خود می‌آید: ( · · · · ) و . با حرکت با hover یا فوکوس خود دکمه اجرا می‌شود؛ (پیش‌فرض ) پیوسته است و برای جلب توجه تنها یک‌بار در هر نما به کار می‌رود. در هیچ آیکونی حرکت نمی‌کند.

TSX

import { Button } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';export function IconMotionButtons() {  return (    <>      <Button icon={<Icon name="notification" size="sm" animate="wiggle" trigger="hover" />}>اعلان‌ها</Button>      <Button variant="secondary" icon={<Icon name="download" size="sm" animate="bounce" trigger="hover" />}>دانلود</Button>      <Button variant="ghost" icon={<Icon name="sparkles" size="sm" animate="pulse" trigger="hover" />}>پیشنهاد</Button>      <Button variant="secondary" icon={<Icon name="check" size="sm" animate="draw" trigger="hover" />}>تأیید</Button>      <Button variant="ghost" icon={<Icon name="settings" size="sm" animate="spin" trigger="hover" />}>تنظیمات</Button>    </>  );}

برای دکمهٔ خطر، همان حرکت با :

TSX

import { Button } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';export function DangerIconButton() {  return (    <Button tone="danger" variant="secondary" icon={<Icon name="delete" size="sm" animate="wiggle" trigger="hover" />}>      حذف ایده    </Button>  );}

حالت در حال انجام، غیرفعال و بی‌صدا

TSX

import { Button } from '@tokapps/tuk';type Props = {  busy: boolean;  canContinue: boolean;  onContinue: () => void;};export function AuthStep({ busy, canContinue, onContinue }: Props) {  return (    <Button      variant="primary"      loading={busy}      disabled={!canContinue}      sound={false}      onClick={onContinue}    >      ادامه    </Button>  );}

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

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

به‌علاوه همهٔ ویژگی‌های (مانند ، ، ، ) از پذیرفته می‌شوند.

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

code

button[data-tds="button"][data-variant][data-size][data-print]  ├─ آیکون یا چرخنده (وقتی busy است، فقط چرخنده)  └─ children (برچسب)

عنصر ریشه همان بومی است؛ بدون لایهٔ میانی.
، ، و بنیان ثابت‌اند و از می‌آیند.
هیچ یا ندارد؛ ساختار یک‌سطحی است.
آیکون و برچسب قابل‌تغییرند؛ ترتیب آن‌ها ثابت است (آیکون پیش از برچسب).

همهٔ حالت‌ها

حالت	نشانه	نمایش
پیش‌فرض	واریانت و اندازه	رنگ پس‌زمینهٔ همان واریانت
hover		: ؛ : ؛ : پس‌زمینهٔ و متن پررنگ‌تر
active (فشردن)		مقیاس ؛ رنگ
focus-visible		حلقهٔ فوکوس با و ضخامت
disabled	صفت بومی ()	کدری ، بدون پاسخ به نشانگر
loading	پراپ ، یا در حال اجرا؛	نشانگر ، آیکون چرخان، کلیک نادیده. دکمه کدر نمی‌شود
print		در پنهان
pressed / selected	در کد تعریف نشده	برای دکمهٔ دوحالته، را مصرف‌کننده بدهد؛ استایل مخصوص در CSS نیست

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

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

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

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

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

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

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

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

توکن‌ها

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

قرارداد ARCH

آیکون فقط با و نام معنایی داده می‌شود؛ مسیر فایل تصویری در کد مصرف‌کننده نمی‌آید.
تم فقط حرکت و توکن را عوض می‌کند؛ ساختار DOM، ARIA و رفتار کیبورد ثابت می‌مانند.
این کامپوننت gesture ندارد؛ معادل کیبوردی همان و بومی است.

نکات

برای دکمهٔ فقط‌آیکون از IconButton استفاده کنید.
برای یک کنش اصلی با گزینه‌های جانبی از SplitButton استفاده کنید.
کنش مخرب را پیش از اجرا با AlertDialog تأیید کنید.
ناوبری بین صفحه‌ها با لینک انجام می‌شود: با (یا برای فریم‌ورک) همان ظاهر دکمه روی رندر می‌شود.

دکمه با ظاهر پیوند (href / as)

TSX

<Button href="/docs" variant="secondary">مستندات</Button><Button href="https://tokapps.com" target="_blank">سایت توکاپس</Button> {/* rel="noopener noreferrer" خودکار */}<Button as={Link} href="/profile">پروفایل</Button> {/* Link از next/link */}

با عنصر رندر می‌شود (نقش link، نه button)؛ نمی‌گیرد. روی پیوند ، و جلوگیری از ناوبری را می‌دهد. کنش (ثبت، حذف) همچنان دکمهٔ بومی است.