Обзор
ImageInput объединяет предварительный просмотр изображения, нативный выбор файла и действия загрузки, удаления или отмены. onFileSelect срабатывает при выборе файла. Ваше приложение проверяет и загружает файл, управляет ходом загрузки и отменой, а также передаёт URL предварительного просмотра через src.
Использование
Выбор и предварительный просмотр
Предварительный просмотр и кнопка «Загрузить» открывают один и тот же нативный выбор файла.onFileSelect получает выбранный File; сам он не запускает загрузку. Отмена или возврат пустого выбора оставляет текущее изображение без изменений. После выбора поле ввода файла очищается, поэтому тот же файл можно выбрать снова, а File в обратном вызове остаётся пригодным для использования.
Компоненты Front поддерживают нативный выбор и читаемое содержимое File. Потоки React и Preact, созданные SDK, проверены в Chromium с активацией указателем, клавишами Enter и Space. Средство выбора открывается только после доверенного щелчка внутри компонента. URL-адреса объектов, созданные Worker и назначенные src изображения, поддерживают предпросмотр.
По умолчанию accept имеет значение image/* и фильтрует средство выбора файлов. Проверяйте допустимые форматы, размеры и размер файла в вашем приложении. Этот селектор, управляемый обратными вызовами, не сохраняет файл для нативной отправки формы. Его кнопки действий используют type="button", поэтому не отправляют окружающую форму.
Для пустого изображения или изображения с ошибкой отображается заполнитель. Изменение src повторяет попытку предварительного просмотра, в том числе после сбоя загрузки предыдущего изображения. Удаление вызывает onRemove; обновите src после того, как ваше приложение удалит изображение. Приложение управляет локальными URL предварительного просмотра и отзывает URL объектов, созданные воркером, когда они больше не нужны. Рендерер отвечает за очистку URL предварительного просмотра своего хоста.
Свойства корневого элемента и поля ввода файла
className, style и ref применяются к корневому div. Корневой ref по умолчанию получает 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.