دکمه تقسیمی — SplitButton

یک کنش اصلی را کنار دکمهٔ منو قرار می‌دهد. کنش اصلی با اجرا می‌شود و دکمهٔ منو گزینه‌های جانبی را نشان می‌دهد، مثل «ذخیره» در کنار «خروجی PDF / CSV». منو با React Aria ساخته شده و کلیدهای فلش، Home و End، Escape و بازگشت فوکوس را دارد. ساختار دو‌دکمه‌ای و منو ثابت است؛ هویت فقط توکن و حرکت را عوض می‌کند.

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

TSX

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

نمونهٔ زنده

کد قابل کپی

کنش اصلی با گزینه‌های خروجی

TSX

import { SplitButton } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';// exportAs و copyLink را خودتان پیاده‌سازی کنید.declare function exportAs(format: 'pdf' | 'csv'): void;declare function copyLink(): void;export function ExportMenu() {  return (    <SplitButton      menuLabel="گزینه‌های بیشتر"      onPress={() => exportAs('pdf')}      options={[        { id: 'pdf', label: 'خروجی PDF', icon: <Icon name="download" size="sm" />, onAction: () => exportAs('pdf') },        { id: 'csv', label: 'خروجی CSV', icon: <Icon name="download" size="sm" />, onAction: () => exportAs('csv') },        { id: 'copy', label: 'کپی پیوند', icon: <Icon name="copy" size="sm" />, onAction: copyLink },      ]}    >      ذخیره    </SplitButton>  );}

واریانت ثانویه، اندازه و آیکون

TSX

import { SplitButton } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';export function SendMenu({ onSend, onSchedule }: { onSend: () => void; onSchedule: () => void }) {  return (    <SplitButton      variant="secondary"      size="lg"      icon={<Icon name="send" size="sm" mirror />}      menuLabel="زمان‌بندی ارسال"      onPress={onSend}      options={[{ id: 'later', label: 'زمان‌بندی', onAction: onSchedule }]}    >      ارسال    </SplitButton>  );}

غیرفعال و گزینهٔ غیرفعال

TSX

import { SplitButton } from '@tokapps/tuk';export function LockedSave() {  return (    <SplitButton      isDisabled      menuLabel="گزینه‌های بیشتر"      options={[        { id: 'pdf', label: 'خروجی PDF', onAction: () => undefined },        { id: 'csv', label: 'خروجی CSV', disabled: true, onAction: () => undefined },      ]}    >      ذخیره    </SplitButton>  );}

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

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

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

code

div[data-tds="split-button"][data-variant][data-size][data-print][data-disabled]?  ├─ button[data-part="main"]        کنش اصلی (icon + children)  └─ button[data-part="toggle"]      دکمهٔ منو، aria-label = menuLabel، aria-expanded        └─ (پورتال) div[data-tds="split-button-menu"]              └─ Menu (role=menu)                    └─ div[data-tds="split-button-item"] × N

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

همهٔ حالت‌ها

حالت	نشانه	نمایش
پیش‌فرض	واریانت و اندازه	دو بخش کنار هم با جداکنندهٔ
hover	روی هر بخش	: ؛ :
pressed	روی هر بخش	مقیاس
focus-visible	روی هر بخش	حلقهٔ فوکوس درون‌تراز با
menu-open	روی دکمهٔ منو	منو در پورتال باز است
disabled	روی ریشه و روی هر دو بخش	کدری ؛
گزینهٔ focused	روی آیتم	پس‌زمینهٔ
گزینهٔ disabled	روی آیتم	کدری و
print		در پنهان

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

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

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

ساختار دو دکمه‌ای با و . دکمهٔ منو کنار کنش اصلی و منو با React Aria می‌ماند.
دکمهٔ منو بدون نیست؛ نام دسترسی الزامی است.
رفتار کیبورد منو: فلش‌ها، Home و End، Escape و بازگشت فوکوس به دکمهٔ منو (React Aria).
هر دو بخش همزمان غیرفعال می‌شوند؛ منو در حالت غیرفعال باز نمی‌شود.
رنگ خام یا گرادیان. رنگ از توکن معنایی می‌آید.
حرکت در : بدون حرکت، فقط تغییر رنگ.
هدف لمسی: هر بخش باید به اندازهٔ کافی بزرگ باشد. اندازهٔ از می‌آید؛ در موبایل یا بدهید.

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

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

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

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

توکن‌ها

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

قرارداد ARCH

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

نکات

برای کنش تکی بدون گزینه از Button استفاده کنید.
برای منوی زمینه‌ای روی یک عنصر از ContextMenu استفاده کنید.
برای انتخاب بین گزینه‌های هم‌وزن بدون کنش اصلی، از Select استفاده کنید.
برای جستجو در تعداد زیاد گزینه از CommandMenu استفاده کنید.