ورودی تگ (Tag Input)
کامپوننت ورودی چندتگی برای افزودن و مدیریت تگها
معرفی
کامپوننت TagInput برای دریافت چندین مقدار (تگ) از کاربر استفاده میشود. کاربر میتواند با فشار دادن Enter تگ جدید اضافه کند و با کلیک روی × آن را حذف کند.
چه زمانی استفاده کنیم:
- وقتی کاربر باید مقادیر آزاد (نه از لیست مشخص) وارد کند
- برای دریافت کلمات کلیدی، تگها یا برچسبهای سفارشی
- وقتی تعداد مقادیر ورودی نامشخص است و کاربر خودش تعیین میکند
چه زمانی استفاده نکنیم:
- وقتی گزینهها از پیش تعریفشدهاند — از
MultiSelectاستفاده کنید - وقتی فقط یک مقدار لازم دارید — از
Inputاستفاده کنید
استفاده
ایرانتهران
Enter را برای اضافه کردن تگ فشار دهید
import { TagInput } from '@parto-system-design/ui'
export default function MyComponent() {
const [tags, setTags] = React.useState<string[]>(['ایران', 'تهران'])
return <TagInput value={tags} onChange={setTags} placeholder="تگ جدید اضافه کنید..." />
}حداکثر تعداد تگ
با استفاده از maxTags میتوانید سقف تعداد تگها را تعیین کنید:
تگ اولتگ دومتگ سوم
3/5 تگ
<TagInput value={tags} onChange={setTags} placeholder="تگ جدید..." maxTags={5} />حالت غیرفعال
تگ اولتگ دوم
<TagInput defaultValue={['تگ اول', 'تگ دوم']} placeholder="غیرفعال است" disabled />کنترل شده و غیرکنترل شده
کنترل شده (Controlled)
const [tags, setTags] = React.useState<string[]>([])
;<TagInput value={tags} onChange={setTags} placeholder="تگ جدید..." />غیرکنترل شده (Uncontrolled)
<TagInput defaultValue={['تگ پیشفرض']} placeholder="تگ جدید..." />رفتار کیبورد
| کلید | عملکرد |
|---|---|
Enter | اضافه کردن تگ جدید |
Backspace | حذف آخرین تگ (در صورت خالی بودن input) |
| کلیک روی × | حذف همان تگ |
Props
حالتها و انواع
حالت کنترلشده
با value و onChange مقدار تگها را کنترل کنید.
حالت غیرکنترلشده
با defaultValue مقدار اولیه را تنظیم کنید.
با محدودیت تعداد
با maxTags سقف تعداد تگها را تعیین کنید.
حالت غیرفعال
با disabled ورودی و حذف تگها غیرفعال میشود.
استایلها
با variant بین "default" و "secondary" انتخاب کنید.
راهنمای استفاده
بکنید
- از
maxTagsبرای محدود کردن تعداد تگها استفاده کنید -placeholderمناسب و راهنما ارائه دهید - از حالت کنترلشده برای مدیریت بهتر state استفاده کنید
نکنید
- وقتی گزینهها از پیش مشخص هستند از TagInput استفاده نکنید —
MultiSelectمناسبتر است - بدونmaxTagsدر فرمهای عمومی رها نکنید — ممکن است کاربر تعداد زیادی تگ وارد کند - تگهای خالی یا فاصلهدار را بدون اعتبارسنجی قبول نکنید
دسترسیپذیری
- اضافه کردن تگ با Enter
- حذف آخرین تگ با Backspace (در صورت خالی بودن input)
- حذف تگ با کلیک روی دکمه ×
- جلوگیری از ورود تگهای تکراری
- دکمه حذف هر تگ دارای متن
sr-onlyبرای screen reader - کاملاً سازگار با RTL
کامپوننتهای مرتبط
- اگر گزینهها از پیش تعریفشده هستند و کاربر باید از لیست انتخاب کند → MultiSelect
- اگر نیاز به ورودی هشتگ با پیشوند
#دارید → HashtagInput - اگر نیاز به نمایش فیلترهای فعال به صورت chip دارید → FilterChip