حقل الوسوم
TagInputحقل وسوم في React يحول النص المكتوب إلى شرائح قابلة للإزالة، مع تحقق وحد أقصى ومنع التكرار وربط للحقل. يعمل بلوحة المفاتيح وبالعربية.
يحول Enter أو الفاصلة النص إلى شريحة، ويحذف Backspace آخر شريحة. يمنع TagInput التكرار، ويدعم max وvalidate.
متى تستخدمه
استخدم TagInput لجمع عدة قيم قصيرة حرة: مستلمي بريد، كلمات مفتاحية، أو أرقام مرجعية. استخدم validate لرفض المدخلات غير الصحيحة وmax لتحديد العدد.
حين تأتي القيم من قائمة ثابتة، استخدم Dropdown مع multiple ليختار المستخدم بدل أن يكتب.
أمثلة
الخصائص
الخصائص التي يعرفها TagInput. سمات العنصر الأصلي تمر كما هي.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
size | "sm" | "md" | "lg" | ||
name | string | Submits each tag as its own FormData entry under this exact name, in order, like a native
<select multiple>: read them with getAll(name). For PHP and Laravel arrays, pass
name="tags[]". No tags submits nothing, and the uncommitted draft text is never submitted. | |
value | string[] | Controlled tag list. | |
defaultValue | string[] | Uncontrolled initial tag list. | |
onChange | (tags: string[]) => void | Fires with the full accepted tag set after every add/remove. | |
label | react.ReactNode | Visible field label, associated to the text input. | |
helperText | react.ReactNode | Hint shown below the field. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the field when invalid. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
max | number | Caps the number of tags. Adds beyond the cap are no-ops. | |
allowDuplicates | boolean | Allow the same tag more than once. Off → duplicates are rejected. | |
caseSensitive | boolean | Make duplicate detection case-sensitive. Default: case-insensitive. | |
validate | (tag: string, tags: string[]) => boolean | Consumer gate run on each candidate tag. Return false to reject (draft kept). | |
delimiters | string[] | Characters that commit the draft and split a paste. Newline always splits a paste. | |
chipVariant | "primary" | "secondary" | "outline" | "destructive" | "destructive-subtle" | "default" | "success" | "warning" | "info" | "primary-subtle" | "secondary-subtle" | "success-subtle" | "warning-subtle" | "info-subtle" | "on-color" | Tag variant used for the chips. | |
removeLabel | (tag: string) => string | Accessible name for each chip's remove button. | |
formatAnnouncement | (tag: string, action: "add" | "remove") => string | Live-region text announced on add/remove (screen readers). |
إمكانية الوصول
تظهر الشرائح في قائمة، لذا يسمع مستخدم قارئ الشاشة عدد القيم ويستطيع التنقل بينها. يحول Enter أو الفاصلة القيمة إلى شريحة، ويحذف Backspace آخر شريحة. تعلن منطقة حية الإضافات والحذف.
ترتبط تسمية الحقل والنص المساعد ورسالة الخطأ بالحقل كما في TextInput. يحمل كل زر إزالة اسم الوسم في تسميته المتاحة.