انتخاب چندتایی (MultiSelect)

معرفی

کامپوننت MultiSelect برای انتخاب چندین گزینه از لیست استفاده می‌شود. مقادیر انتخاب‌شده به صورت FilterChip نمایش داده می‌شوند.

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

• وقتی کاربر باید چندین گزینه از لیست مشخصی انتخاب کند
• وقتی گزینه‌های انتخاب‌شده باید به صورت chip قابل حذف نمایش داده شوند
• برای فیلترهای چند مقداری در فرم‌ها و داشبوردها

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

• برای انتخاب تک گزینه — از Select استفاده کنید
• برای بیش از 100 گزینه — از Command با multi-select استفاده کنید
• وقتی گزینه‌ها باید همیشه دیده شوند — از Checkbox group استفاده کنید

لیست بلند و پیمایش

فهرست داخل فضای قابل‌دسترسِ پنجره باز می‌شود و گزینه‌ها در همان فهرست پیمایش می‌شوند. جست‌وجو و پاک‌کردن انتخاب‌ها در دسترس می‌مانند؛ برای رسیدن به گزینه‌های آخر لازم نیست خود صفحه یا پنجرهٔ فرم را جابه‌جا کنید.

زمین بازی

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

استفاده

import { MultiSelect } from '@partodata/ui'

const options = [
  { value: 'tehran', label: 'تهران' },
  { value: 'isfahan', label: 'اصفهان' },
  { value: 'shiraz', label: 'شیراز' },
  { value: 'tabriz', label: 'تبریز' },
]

const [selected, setSelected] = useState<string[]>([])

;<MultiSelect options={options} value={selected} onValueChange={setSelected} placeholder="شهر را انتخاب کنید" />

با محدودیت انتخاب

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  maxSelected={3}
  placeholder="حداکثر 3 مورد"
/>

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

<MultiSelect options={[]} isLoading={true} placeholder="در حال بارگذاری..." />

Props

حالت‌ها و انواع

پایه — انتخاب چندتایی با چیپ

ساده‌ترین استفاده؛ بدون محدودیت تعداد. هر گزینه‌ی انتخاب‌شده به‌صورت FilterChip در trigger ظاهر می‌شود.

const options = [
  { value: 'tehran', label: 'تهران' },
  { value: 'isfahan', label: 'اصفهان' },
  { value: 'shiraz', label: 'شیراز' },
]

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  placeholder="شهر را انتخاب کنید"
/>

size — اندازهٔ تریگر

با size ارتفاع تریگر را با سایر کنترل‌های همان نوار فیلتر (Input، Select، Button) هم‌تراز کنید. مقدار پیش‌فرض 'md' (38 پیکسل، اندازهٔ فیلد فرم) است. داخل ControlSizeProvider یا PageToolbar، size ندهید: تریگر اندازهٔ ردیف را می‌گیرد و با یک خط برچسب انتخاب‌شده دقیقاً هم‌قد بقیهٔ ردیف است. بیرون از Provider، برچسب‌های انتخاب‌شده تریگر را بلندتر می‌کنند.

<MultiSelect options={options} value={selected} onValueChange={setSelected} size="lg" />

maxSelected — سقف تعداد انتخاب

با maxSelected بعد از رسیدن به سقف، انتخاب گزینه‌های جدید نادیده گرفته می‌شود. مناسب برای فیلترهایی که منطقاً تعداد محدود دارند.

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  maxSelected={3}
  placeholder="حداکثر 3 مورد"
/>

maxDisplayed — جمع‌بندی چیپ‌ها به «+N»

وقتی تعداد انتخاب‌ها زیاد است، فقط maxDisplayed چیپ اول نمایش داده می‌شود و باقی به‌صورت یک Badge شمارنده جمع می‌شوند تا فضا اشغال نشود.

<MultiSelect options={longOptionsList} value={selected} onValueChange={setSelected} maxDisplayed={2} />

حالت بارگذاری — Skeleton در dropdown

وقتی گزینه‌ها از API می‌آیند، تا قبل از resolve با isLoading={true} Skeleton در dropdown نمایش دهید.

<MultiSelect options={[]} isLoading={true} placeholder="در حال بارگذاری..." />

حالت غیرفعال

با disabled={true} کل کنترل (trigger و dropdown) غیرفعال می‌شود؛ مناسب برای فرم‌های read-only.

<MultiSelect options={options} value={['tehran']} disabled={true} />

گزینه‌های دامنه — شدت/پلتفرم

برای فیلترهای افکارسنجی می‌توانید مقادیر value را به کلیدهای دامنه (severity، platform) map کنید و در parent به توکن رنگی تبدیل کنید.

const severityOptions = [
  { value: 'urgent', label: 'فوری' },
  { value: 'high', label: 'بالا' },
  { value: 'medium', label: 'متوسط' },
  { value: 'low', label: 'پایین' },
]

<MultiSelect
  options={severityOptions}
  value={selectedSeverity}
  onValueChange={setSelectedSeverity}
  placeholder="شدت را انتخاب کنید"
/>

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

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

• باز و بسته کردن dropdown با Enter و Space
• پیمایش بین گزینه‌ها با ↑ و ↓
• جستجوی درون لیست با تایپ کردن
• حذف چیپ‌ها با کلیک، یا با فوکوس روی دکمه‌ی حذف و زدن Enter/Space — این کار dropdown را باز نمی‌کند
• در حالت disabled تریگر با aria-disabled به صفحه‌خوان اعلام می‌شود و از ترتیب Tab خارج می‌شود
• وضعیت انتخاب هر گزینه با aria-checked به صفحه‌خوان اعلام می‌شود و فهرست با aria-multiselectable به‌عنوان چندانتخابی معرفی می‌شود
• پشتیبانی کامل از RTL

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

• اگر فقط نیاز به انتخاب یک گزینه دارید → Select
• اگر لیست گزینه‌ها بسیار بزرگ است و نیاز به جستجوی پیشرفته دارید → Command
• اگر نیاز به نمایش فیلترهای فعال به صورت chip دارید → FilterChip
• اگر نیاز به جستجو و انتخاب از API دارید → Autocomplete