حقل الوسوم
TagInputحقل وسوم في React يحوّل النص المكتوب إلى شرائح قابلة للإزالة، مع تحقّق وحدّ أقصى ومنع التكرار وربط للحقل. يعمل بلوحة المفاتيح وبالعربية.
يثبت Enter أو الفاصلة النص حبة، ويحذف Backspace آخر واحدة. يزيل التكرار ويدعم max وvalidate.
متى تستخدمه
استخدم TagInput لجمع عدّة قيم قصيرة حرّة: مستلمي بريد، أو كلمات مفتاحية، أو أرقام مرجعية. استخدم validate لرفض المدخلات غير الصحيحة وmax لتحديد العدد.
حين تأتي القيم من قائمة ثابتة، استخدم Dropdown مع multiple ليختار المستخدم بدل أن يكتب.
أمثلة
الخصائص
الخصائص التي يعرّفها TagInput. سمات العنصر الأصلي تمرّ كما هي.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
size | "sm" | "md" | "lg" | ||
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. يحمل كل زر إزالة اسم الوسم في تسميته المتاحة.