الانتقال إلى المحتوى الرئيسي

نظرة عامة

يجمع ImageInput بين معاينة الصورة ومنتقي الملفات الأصلي وإجراءات الرفع أو الإزالة أو الإلغاء. يتم تشغيل onFileSelect عند اختيار ملف. يتحقق تطبيقك من الملف ويرفعه، ويمتلك تقدّم الرفع وإلغاءه، ويوفر عنوان URL للمعاينة عبر src.

استخدام

يحتفظ المثال بالمعاينة الحالية أثناء قراءة بديل، ويتجاهل القراءات الناتجة عن التحديدات المُزالة أو المستبدلة.

الاختيار والمعاينة

تفتح المعاينة وزر الرفع منتقي الملفات الأصلي نفسه. يتلقى onFileSelect العنصر File المحدد؛ ولا يبدأ عملية رفع بنفسه. يؤدي الإلغاء أو إرجاع اختيار فارغ إلى إبقاء الصورة الحالية دون تغيير. يُمسح إدخال الملف بعد الاختيار بحيث يمكن اختيار الملف نفسه مجددًا، ويظل File الخاص بدالة الاستدعاء قابلًا للاستخدام. تدعم مكونات الواجهة التحديد الأصلي ومحتويات File القابلة للقراءة. تم التحقق من تدفقات React وPreact المُنشأة بواسطة SDK في Chromium باستخدام التفعيل بالمؤشر وEnter وSpace. لا يُفتح المنتقي إلا عبر نقرة موثوقة داخل المكون. تدعم عناوين URL للكائنات التي ينشئها Worker والمُسندة إلى src للصورة المعاينات. تكون القيمة الافتراضية لـ accept هي image/*، وهو يرشح منتقي الملفات. تحقق من التنسيقات والأبعاد والحجم المسموح بها في تطبيقك. لا يحتفظ هذا المحدد المعتمد على الاستدعاءات بملف لإرساله عبر النموذج الأصلي. تستخدم أزرار إجراءاته type="button"، لذا لا ترسل نموذجًا محيطًا. تعرض الصورة الفارغة أو التي فشل تحميلها عنصرًا نائبًا. يؤدي تغيير src إلى إعادة محاولة المعاينة، بما في ذلك بعد فشل تحميل صورة سابقة. تستدعي الإزالة onRemove؛ حدّث src بعد أن يزيل تطبيقك الصورة. يمتلك التطبيق عناوين URL للمعاينة المحلية ويلغي عناوين URL للكائنات التي ينشئها العامل عندما لا تعود مطلوبة. يمتلك العارض تنظيف عناوين URL لمعاينة مضيفه.

خصائص الجذر وإدخال الملف

تُطبّق className وstyle وref على عنصر div الجذر. يتلقى مرجع الجذر الافتراضي عنصر HTMLDivElement؛ استخدم inputRef لإدخال الملف المخفي. استخدم render={<div ... />} لتوفير سمات الجذر الأصلية أو معالجات الأحداث. أبقِ ذلك الجذر غير تفاعلي، لأن الوحدة تحتوي بالفعل على أزرار. يُطبّق dir على كل من الجذر وإدخال الملف؛ استخدم dir="rtl" للتخطيط من اليمين إلى اليسار. تكون سمات إدخال الملف الأصلية خصائص على المستوى الأعلى، بما في ذلك accept وcapture وname وid وtitle وform وrequired والسمات القابلة للوصول وسمات البيانات ومعالجات الأحداث. تُطبّق على الإدخال المخفي. يتلقى inputRef عنصر HTMLInputElement الخاص به. يستخدم عنصر التحكم دائمًا type="file"، ويقبل ملفًا واحدًا، ويعيد تعيين قيمته بعد كل اختيار. لا يمكن تخصيص children وdangerouslySetInnerHTML وtype وmultiple وvalue وdefaultValue وhidden. لا يزال التحقق الأصلي من required يرى إدخالًا فارغًا بعد الاختيار لأن الإدخال يُعاد تعيينه. تحقق من عمليات الرفع المكتملة في تطبيقك. يتلقى onChange حدث التغيير الأصلي بينما لا يزال الإدخال يحتوي على الملف المحدد. ثم يُعاد تعيين الإدخال قبل تشغيل onFileSelect. تتبع خصائص الأحداث الأصلية عقد الإدخال في React. onAbort هو إجراء إيقاف الرفع.

حالات الرفع والتعطيل

تجعل isUploading الجذر مشغولًا وتجعل الاختيار والإزالة غير متاحين. تبقى عناصر التحكم التي كانت متاحة قابلة للتركيز، لذلك لا يُفقد تركيز لوحة المفاتيح عند بدء الرفع. وفّر onAbort لاستبدال الرفع بالإلغاء أثناء الرفع. يعمل الإلغاء قبل وجود أول عنوان URL للصورة. يتولى التطبيق الإلغاء ويعيد تعيين isUploading إلى false عند انتهاء الرفع. تعطّل disabled كل إجراء. يتطلب الاختيار onFileSelect. تتطلب الإزالة كلاً من onRemove وsrc غير فارغ.

التسميات والإرشادات والأخطاء

وفّر سلاسل uploadLabel وremoveLabel وabortLabel مترجمة محليًا. قيمها الافتراضية هي Upload وRemove وAbort. تسمّي تسمية الرفع أيضًا زر المعاينة وإدخال الملف المخفي. يمكن للسمات الأصلية القابلة للوصول توفير اسم مختلف لإدخال الملف. يصف aria-describedby أيضًا أزرار الاختيار ويتحد مع النص المساعد ونص الخطأ الخاصين بالتطبيق. ينتمي helperText وerrorMessage إلى التطبيق. يصف كلاهما عناصر التحكم في الاختيار، ويُعلن عن الأخطاء كتنبيهات. لا توجد حدود مضمّنة للملفات أو إرشادات للمنتج.

الترحيل

استبدل onUpload بـ onFileSelect. أبقِ accept كخاصية على المستوى الأعلى. لا تزال دالة الاستدعاء تتلقى File؛ أبقِ رمز التحقق والرفع الحالي في تطبيقك.

الخصائص

string
افتراضي:"Abort"
Label for the Abort action.
string
افتراضي:"image/*"
Native file picker filter. Defaults to image/*. The caller validates allowed formats.
string
Accessible description references for the hidden file input and selection buttons, combined with helperText and errorMessage.
string
Accessible name of the hidden file input. Defaults to uploadLabel.
string
Accessible name reference for the hidden file input.
boolean | "user" | "environment"
Native device capture hint for the file picker.
string
Class applied to the root element.
string
Text direction applied to both the root and hidden file input.
boolean
افتراضي:"false"
Disables file selection, removal, and abort actions.
string | null
Application error, displayed as an alert and associated with the selection controls.
string
Native form identifier associated with the hidden file input.
string
Application instructions, associated with the selection controls.
string
Native identifier of the hidden file input.
Ref<HTMLInputElement>
Ref to the hidden single-file HTMLInputElement.
boolean
افتراضي:"false"
Marks the module busy. Selection and removal controls that would otherwise be enabled stay focusable but unavailable. Shows Abort when onAbort is supplied.
string
Native name of the hidden file input.
(() => void)
Shows an abort action while uploading. It can cancel the first upload before a src exists.
ChangeEventHandler<HTMLInputElement, HTMLInputElement>
Native file input change event, fired while the selected file is present and before the input resets. The input does not retain a file for form submission.
((file: File) => void)
Fires when a file is selected and receives its usable File after the input resets. Empty and canceled selections do not call it. Selection is disabled when omitted. The caller owns validation and uploading.
(() => void)
Requests removal of the current image. Removal is disabled without this callback or a nonempty src.
Ref<HTMLDivElement>
Ref to the root div element.
string
افتراضي:"Remove"
Label for the Remove action.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Custom root element or render function. Supply root native attributes here and keep a non-interactive root.
boolean
Native file input requirement. The input resets after selection, so the caller validates completed uploads.
string | null
Resolved image URL. Empty or failed images show the image placeholder.
CSSProperties
Inline style applied to the root element.
string
Native title of the hidden file input.
string
افتراضي:"Upload"
Label for the preview, Upload action, and hidden file input.