پرتوپرتو

انتخابگر (Select)

کامپوننت انتخاب گزینه از لیست

معرفی

کامپوننت Select برای انتخاب یک گزینه از لیست کشویی استفاده می‌شود.

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

  • برای بیش از ۱۵ گزینه — از Autocomplete استفاده کنید
  • برای انتخاب چند گزینه — از MultiSelect استفاده کنید
  • برای ۲-۵ گزینه که باید همیشه نمایش داده شوند — از RadioGroup استفاده کنید

استفاده

import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@parto-system-design/ui'
;<Select defaultValue="option1">
  <SelectTrigger className="w-[220px]">
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">گزینه ۱</SelectItem>
    <SelectItem value="option2">گزینه ۲</SelectItem>
    <SelectItem value="option3">گزینه ۳</SelectItem>
  </SelectContent>
</Select>

زمین بازی

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

زمین بازی
تنظیمات
import { Select } from '@parto-system-design/ui'

<Select />

اندازه‌ها

کامپوننت SelectTrigger از چهار اندازه استاندارد پشتیبانی می‌کند:

<div className="flex flex-col gap-4">
  <Select>
    <SelectTrigger size="xs" className="w-[180px]">
      <SelectValue placeholder="خیلی کوچک (xs)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه ۱</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="sm" className="w-[180px]">
      <SelectValue placeholder="کوچک (sm) — پیش‌فرض" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه ۱</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="md" className="w-[180px]">
      <SelectValue placeholder="متوسط (md)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه ۱</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="lg" className="w-[180px]">
      <SelectValue placeholder="بزرگ (lg)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه ۱</SelectItem>
    </SelectContent>
  </Select>
</div>

با Label

<div className="space-y-2">
  <label htmlFor="framework">فریمورک</label>
  <Select>
    <SelectTrigger id="framework" className="w-[180px]">
      <SelectValue placeholder="انتخاب فریمورک" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="next">Next.js</SelectItem>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
      <SelectItem value="svelte">Svelte</SelectItem>
    </SelectContent>
  </Select>
</div>

کنترل شده

const [value, setValue] = React.useState('')

;<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">سیب</SelectItem>
    <SelectItem value="banana">موز</SelectItem>
    <SelectItem value="orange">پرتقال</SelectItem>
  </SelectContent>
</Select>

با گروه‌بندی

import { SelectGroup, SelectLabel } from '@parto-system-design/ui'
;<Select>
  <SelectTrigger className="w-[280px]">
    <SelectValue placeholder="انتخاب میوه" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>میوه‌های استوایی</SelectLabel>
      <SelectItem value="banana">موز</SelectItem>
      <SelectItem value="pineapple">آناناس</SelectItem>
      <SelectItem value="mango">انبه</SelectItem>
    </SelectGroup>
    <SelectGroup>
      <SelectLabel>میوه‌های معمولی</SelectLabel>
      <SelectItem value="apple">سیب</SelectItem>
      <SelectItem value="orange">پرتقال</SelectItem>
      <SelectItem value="grape">انگور</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

غیرفعال کردن گزینه

<Select>
  <SelectTrigger>
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">گزینه ۱</SelectItem>
    <SelectItem value="option2" disabled>
      گزینه ۲ (غیرفعال)
    </SelectItem>
    <SelectItem value="option3">گزینه ۳</SelectItem>
  </SelectContent>
</Select>

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

Select از اجزای زیر تشکیل شده است:

  • Select: کانتینر اصلی و مدیریت state
  • SelectTrigger: دکمه باز کننده منو
  • SelectValue: نمایش مقدار انتخاب شده
  • SelectContent: کانتینر محتوای منو
  • SelectItem: هر گزینه
  • SelectGroup: گروه‌بندی گزینه‌ها
  • SelectLabel: برچسب گروه
  • SelectSeparator: خط جداکننده بین گزینه‌ها

Props

Select

Prop

Type

SelectTrigger

Prop

Type

SelectSeparator

Prop

Type

SelectItem

Prop

Type

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

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

  • از Select برای انتخاب از فهرست‌های ثابت و مشخص استفاده کنید - از Autocomplete برای جستجوی پویا یا فهرست‌های بلند استفاده کنید - همیشه یک مقدار placeholder مناسب تعریف کنید

از این‌ها پرهیز کنید

  • از Select برای فهرست‌های بیش از ۲۰ گزینه استفاده نکنید — به‌جای آن از Autocomplete استفاده کنید - از تغییر مستقیم مقدار انتخاب‌شده بدون تعامل کاربر خودداری کنید - گزینه‌های Select را خیلی طولانی نکنید — حداکثر ۵۰ کاراکتر

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

  • پیمایش با کیبورد (Arrow keys، Enter، Space)
  • جستجو با تایپ
  • از role="combobox" استفاده می‌شود
  • aria-expanded برای وضعیت باز/بسته
  • aria-selected برای گزینه انتخاب شده
  • پشتیبانی کامل از screen readers

ملاحظات RTL

  • منوی dropdown به‌درستی راست‌چین می‌شود
  • آیکون کشویی در سمت مناسب قرار می‌گیرد
  • متن‌ها راست‌چین هستند
  • پیمایش کیبورد با RTL سازگار است
  • نشانگر انتخاب در سمت راست نمایش داده می‌شود

تعامل با کیبورد

  • Enter یا Space: باز/بسته کردن لیست - Arrow Down / Arrow Up: حرکت بین گزینه‌ها - Escape: بستن لیست - حروف: جستجوی سریع گزینه‌ها

مرتبط

  • Autocomplete — Select با قابلیت جستجو برای لیست‌های بزرگ
  • Multi Select — انتخاب چند گزینه همزمان
  • Radio Group — برای انتخاب از بین ۲-۵ گزینه قابل مشاهده
  • Input — برای ورودی آزاد به‌جای انتخاب از لیست

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

  • Autocomplete — برای لیست‌های بزرگ با جستجو
  • MultiSelect — برای انتخاب چند گزینه
  • RadioGroup — برای گزینه‌های کم و قابل رویت
  • NativeSelect — برای فرم‌های ساده بدون styling پیچیده