ددیگ

Toggle Group

دکمه‌ای که روشن و خاموش می‌ماند (Toggle) و گروهی از همین دکمه‌ها که کنار هم می‌نشینند (ToggleGroup). برای نوار ابزار ویرایشگر، انتخاب حالت نمایش و هر جایی که گزینه‌ها آیکونی و کوتاه‌اند.

ری‌اکت ۱۹ و Next.js با پیاده‌سازی دسترس‌پذیری داخلی دیگویو ۳ با Composition API و Reka UISvelte ۵ با runes و Bits UIانگولار با signals و Angular CDK

این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

نصب

با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.

نصب سریع با لینک سخت و دیسک مشترکپکیج‌منیجر پیش‌فرض Node.jsYarn نسخهٔ ۲ به بالا (Berry)رانتایم و پکیج‌منیجر Bun
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/toggle-group.json
npx dig-ui@latest add https://design-system-tau-green.vercel.app/r/toggle-group.json
yarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/toggle-group.json
bunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/toggle-group.json

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.

استفاده

import { Toggle } from "@/components/ui/toggle"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

// دکمهٔ دوحالتهٔ تکی
<Toggle aria-label="درشت">
  <Bold />
</Toggle>

// گروه تک‌انتخابی
<ToggleGroup type="single" defaultValue="center">
  <ToggleGroupItem value="right" aria-label="راست‌چین">
    <AlignRight />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="وسط‌چین">
    <AlignCenter />
  </ToggleGroupItem>
</ToggleGroup>

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.

ترکیب اجزا

ToggleGroup استایلش را از toggleVariants فایل Toggle می‌گیرد، پس دکمهٔ تکی و گروه همیشه یک شکل‌اند و رجیستری هم توگل را همراه گروه نصب می‌کند. variant و size را روی خود گروه بگذارید؛ از طریق کانتکست به همهٔ آیتم‌ها می‌رسد و لازم نیست روی تک‌تکشان تکرار شود (اگر روی یک آیتم هم بدهید، مقدار گروه برنده است). گِرد شدن گوشه‌ها و ادغام حاشیه با کلاس‌های منطقی rtl-آگاه انجام می‌شود و با orientation هماهنگ است (start/end در حالت افقی، بالا/پایین در حالت عمودی)، پس با چرخش جهت صفحه یا تغییر چیدمان، اولین و آخرین دکمه خودشان جای درست را می‌گیرند. separated این ادغام را کنار می‌گذارد و هر دکمه گوشهٔ گرد و فاصلهٔ خودش را می‌گیرد.

دسترس‌پذیری

  • گروه role=toolbar با ناوبری roving focus است: با Tab یک‌بار وارد گروه می‌شوید و با کلیدهای جهت‌دار (و Home/End) بین دکمه‌ها حرکت می‌کنید، نه با Tab. با rovingFocus={false} این رفتار خاموش می‌شود و هر دکمه جداگانه با Tab فوکوس می‌گیرد.
  • جهت کلیدهای جهت‌دار با orientation عوض می‌شود (چپ/راست برای horizontal، بالا/پایین برای vertical) و در حالت افقی از نزدیک‌ترین dir در DOM می‌خواند؛ برای همین dir="rtl" را روی html نگه دارید تا در راست‌به‌چپ برعکس نشود. برای رفتار متفاوت از dir صفحه، پراپ dir را مستقیم بدهید.
  • هر دکمه‌ای که فقط آیکون دارد باید aria-label داشته باشد؛ بدون آن صفحه‌خوان چیزی برای خواندن ندارد.
  • حالت روشن با data-state=on و aria-pressed مشخص می‌شود؛ اتکا به تفاوت رنگ به‌تنهایی کافی نیست، از آیکون یا متن گویا استفاده کنید.
  • اگر انتخاب یکی از گزینه‌ها اجباری است، از type="single" همراه با مقدار پیش‌فرض و disallowEmptySelection استفاده کنید تا حالت «هیچ‌کدام» اصلاً پیش نیاید.

مرجع API

ToggleGroup

ویژگینوعپیش‌فرضتوضیح
type"single" | "multiple"—الزامی. single یعنی حداکثر یک گزینهٔ فعال و multiple یعنی هر تعداد.
value / onValueChangestring | string[] / (value) => void—کنترل‌شده؛ در حالت multiple نوع مقدار آرایهٔ رشته است.
defaultValuestring | string[]—مقدار اولیه در حالت کنترل‌نشده.
variant"default" | "outline""default"روی گروه بگذارید تا از کانتکست به همهٔ آیتم‌ها برسد.
size"sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg""default"اندازهٔ همهٔ آیتم‌های گروه.
disabledbooleanfalseغیرفعال کردن کل گروه.
disallowEmptySelectionbooleanfalseجلوی خالی‌شدنِ کامل انتخاب را می‌گیرد. در single یعنی نمی‌شود گزینهٔ فعال را با کلیک دوباره خاموش کرد؛ در multiple یعنی آخرین گزینهٔ روشن را نمی‌شود خاموش کرد.
orientation"horizontal" | "vertical""horizontal"چیدمان دکمه‌ها و جهت کلیدهای جهت‌دار؛ گِردشدن گوشه‌ها هم با آن هماهنگ می‌شود.
separatedbooleanfalseبه‌جای دکمه‌های به‌هم‌چسبیده، هر دکمه گوشهٔ گرد و فاصلهٔ خودش را می‌گیرد، برای نوار ابزاری که نباید شکل کنترل تک‌پارچه بدهد.
fullWidthbooleanfalseدکمه‌ها به‌اندازهٔ مساوی فضای موجود را پر می‌کنند؛ در orientation="vertical" یعنی ارتفاع کامل.
rovingFocusbooleantrueناوبری با کلیدهای جهت‌دار؛ با false هر دکمه با Tab فوکوس می‌گیرد.
loopbooleantrueرسیدن به انتهای گروه دوباره به ابتدا برمی‌گردد.
dir"rtl" | "ltr"—جهت ناوبری کلیدها؛ معمولاً از dir صفحه (html) ارث می‌رسد.

ToggleGroupItem

ویژگینوعپیش‌فرضتوضیح
valuestring—الزامی و یکتا؛ همان مقداری که در value گروه می‌آید.
disabledbooleanfalseفقط همین آیتم را غیرفعال می‌کند.
variant / size"default" | "outline" / "sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg"—اگر روی گروه ست شده باشد، مقدار گروه اولویت دارد؛ این‌ها برای آیتم‌های خارج از گروه‌اند.

Toggle

ویژگینوعپیش‌فرضتوضیح
pressed / onPressedChangeboolean / (pressed: boolean) => void—حالت کنترل‌شدهٔ روشن و خاموش.
defaultPressedbooleanfalseحالت اولیه در وضعیت کنترل‌نشده.
variant"default" | "outline""default"بدون حاشیه یا با حاشیه و سایهٔ خفیف.
size"sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg""default"اندازهٔ دکمه؛ آیکون‌ها خودکار size-4 می‌گیرند. سه‌تای icon* مربع‌اند و برای دکمهٔ فقط‌آیکونی‌اند.
disabledbooleanfalseغیرفعال کردن دکمه.

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.