ورودی تگ (TagInput)

معرفی

کامپوننت TagInput برای دریافت چندین مقدار (تگ) از کاربر استفاده می‌شود. کاربر می‌تواند با فشار دادن Enter تگ جدید اضافه کند و با کلیک روی × آن را حذف کند.

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

• وقتی کاربر باید مقادیر آزاد (نه از لیست مشخص) وارد کند
• برای دریافت کلمات کلیدی، تگ‌ها یا برچسب‌های سفارشی
• وقتی تعداد مقادیر ورودی نامشخص است و کاربر خودش تعیین می‌کند

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

• وقتی گزینه‌ها از پیش تعریف‌شده‌اند — از MultiSelect استفاده کنید
• وقتی فقط یک مقدار لازم دارید — از Input استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

import { TagInput } from '@partodata/ui'

export default function MyComponent() {
  const [tags, setTags] = React.useState<string[]>(['ایران', 'تهران'])

  return <TagInput value={tags} onChange={setTags} placeholder="تگ جدید اضافه کنید..." />
}

حداکثر تعداد تگ

با استفاده از maxTags می‌توانید سقف تعداد تگ‌ها را تعیین کنید. شمارشگر تعداد/سقف به‌صورت داخلی نمایش داده می‌شود و نیازی به پیاده‌سازی جداگانه نیست:

<TagInput value={tags} onChange={setTags} placeholder="تگ جدید..." maxTags={5} />

وقتی کاربر تگ تکراری وارد کند یا به سقف maxTags برسد، متن پیش‌نویس در فیلد باقی می‌ماند، دلیل رد شدن برای screen reader اعلام می‌شود و در صورت نیاز می‌توانید با onReject واکنش سفارشی (مثلاً نمایش پیام خطا) اضافه کنید:

<TagInput
  value={tags}
  onChange={setTags}
  maxTags={5}
  onReject={(value, reason) => {
    if (reason === 'duplicate') console.warn(`تگ «${value}» تکراری است`)
    if (reason === 'max') console.warn('سقف تعداد تگ رسیده است')
  }}
/>

هشتگ: prefix

برای هشتگ‌ها prefix="#" بدهید. # فقط روی تگ نمایش داده می‌شود و در مقدار ذخیره نمی‌شود؛ اگر کاربر خودش # بنویسد حذف می‌شود.

<TagInput prefix="#" placeholder="هشتگ را بنویسید و Enter بزنید" />

حالت غیرفعال

<TagInput defaultValue={['تگ اول', 'تگ دوم']} placeholder="غیرفعال است" disabled />

کنترل شده و غیرکنترل شده

کنترل شده (Controlled)

const [tags, setTags] = React.useState<string[]>([])

;<TagInput value={tags} onChange={setTags} placeholder="تگ جدید..." />

غیرکنترل شده (Uncontrolled)

<TagInput defaultValue={['تگ پیش‌فرض']} placeholder="تگ جدید..." />

رفتار کیبورد

Props

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

حالت کنترل‌شده

با value و onChange مقدار تگ‌ها را کنترل کنید.

حالت غیرکنترل‌شده

با defaultValue مقدار اولیه را تنظیم کنید.

با محدودیت تعداد

با maxTags سقف تعداد تگ‌ها را تعیین کنید؛ شمارشگر تعداد/سقف به‌طور خودکار نمایش داده می‌شود.

حالت نامعتبر

با aria-invalid کادر و پس‌زمینه کامپوننت به رنگ خطا تغییر می‌کند (مشابه Input/Textarea).

حالت غیرفعال

با disabled ورودی و حذف تگ‌ها غیرفعال می‌شود.

استایل‌ها

با variant بین "default" و "secondary" انتخاب کنید.

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

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

• اضافه کردن تگ با Enter
• حذف آخرین تگ با Backspace (در صورت خالی بودن input)
• حذف تگ با کلیک روی دکمه ×
• جلوگیری از ورود تگ‌های تکراری، همراه با اعلام دلیل رد شدن (تکراری یا رسیدن به maxTags) از طریق ناحیه aria-live="polite" برای screen reader
• دکمه حذف هر تگ دارای متن sr-only برای screen reader
• کاملاً سازگار با RTL

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

• اگر گزینه‌ها از پیش تعریف‌شده هستند و کاربر باید از لیست انتخاب کند → MultiSelect
• اگر نیاز به نمایش فیلترهای فعال به صورت chip دارید → FilterChip