رفع الملفات
FileUploadمكون رفع ملفات في React بالسحب والإفلات، مع التحقق من النوع والحجم، حالة وتقدم لكل ملف، ونمط زر مضغوط. خاضع للتحكم بالكامل وجاهز للاتجاه العربي.
يعمل FileUpload خاضعاً للتحكم بالكامل: تملك أنت مصفوفة files، وتنفذ الرفع بنفسك، وتحدّث status لكل ملف. يتحقق المكون من الملفات عبر accept، maxSize، وmaxFiles.
متى تستخدمه
استخدم FileUpload للمرفقات مثل صور الهوية، العقود، والمستندات الداعمة. اضبط accept، maxSize، وmaxFiles بحسب قواعد الخدمة، وحدّث status لكل ملف مع تقدم الرفع.
استخدم نمط الزر داخل النماذج الكثيفة، ومنطقة الإفلات حين يمثل رفع الملفات المهمة الرئيسية. أبق القواعد ظاهرة في النص المساعد.
أمثلة
الخصائص
الخصائص التي يعرفها FileUpload. سمات العنصر الأصلي تمر كما هي.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
variant | "button" | "dropzone" | ||
filesإلزامي | UploadFile[] | Controlled list of files to render. The consumer is the source of truth. With name, the
native input mirrors this list, so the files submit through FormData (multipart) and
required passes once the list is non-empty. form.reset() doesn't clear the list; clear
files in your own reset handler. | |
onFilesAddedإلزامي | (accepted: File[]) => void | Called with the files that passed validation. The consumer wraps each in
an {@link UploadFile} (assigning an id) and starts the upload. | |
onFilesRejected | (rejections: FileRejection[]) => void | Called with files that failed validation. Never enter files. | |
onRemove | (id: string) => void | Per-row remove handler. Omit to hide the remove button. | |
accept | string | Native accept string (e.g. 'image/*,.pdf'). Also drives validation. | |
maxSize | number | Maximum size per file, in bytes. | |
maxFiles | number | Maximum total files (existing + incoming). When multiple is false this
is forced to 1. | |
multiple | boolean | Allow selecting/dropping more than one file. Defaults to true. | |
disabled | boolean | Disables the drop zone / button and the picker. | |
required | boolean | Marks the field required: renders the asterisk and sets the input's
required attribute. | |
label | react.ReactNode | Visible field label, auto-associated to the input. | |
title | react.ReactNode | ||
description | react.ReactNode | ||
buttonLabel | react.ReactNode | ||
errorMessage | react.ReactNode | Message shown below the field when error is true. | |
error | boolean | Marks the field invalid: sets aria-invalid and error styling. | |
removeLabel | string | Accessible label for the per-row remove button. Defaults to 'Remove'. | |
id | string | ||
className | string | ||
aria-label | string | Defines a string value that labels the current element. | |
aria-labelledby | string | Identifies the element (or elements) that labels the current element. |
إمكانية الوصول
تعمل منطقة الإفلات زراً أيضاً، مما يتيح لمستخدم لوحة المفاتيح فتح منتقي الملفات بمفتاح Enter أو Space. تعلن التقنيات المساعدة الملفات المرفوضة عبر قائمة role="alert" تذكر سبب رفض كل ملف.
يعرض كل صف ملف حالته وزر إزالة له تسمية. ويربط المكون تسمية الحقل، النص المساعد، ورسالة الخطأ كما يربطها TextInput.