upload

ДЕМО

Компонент upload позволяет пользователям загружать один или несколько файлов. Он отображает прогресс загрузки и статус каждого файла. Файлы можно загрузить, нажав кнопку Upload files или перетащив их в компонент.

XML-элемент

upload

Java-класс

JmixUpload

Атрибуты

id - acceptedFileTypes - alignSelf - autoUpload - classNames - colspan - css - dropAllowed - dropLabel - dropLabelIcon - enabled - height - maxFileSize - maxFiles - maxHeight - maxWidth - minHeight - minWidth - uploadHandlerFqn - uploadHandlerType - uploadIcon - uploadText - visible - width

Обработчики

AllFinishedEvent - AttachEvent - DetachEvent - FailedEvent - FileRejectedEvent - FileRemovedEvent - FinishedEvent - ProgressUpdateEvent - StartedEvent - UploadSucceededEvent

Элементы

uploadIcon - dropLabelIcon

Основы

Пример использования компонента upload:

<upload id="upload"
        maxFiles="2"
        autoUpload="false"/>
upload basics

Автозагрузка

Атрибут autoUpload определяет, должны ли файлы загружаться автоматически сразу после выбора или же пользователю необходимо явно инициировать загрузку.

  • Если значение true, файлы загружаются сразу после выбора. Отображается индикатор прогресса загрузки, и пользователь может отменить загрузку, если это необходимо.

  • Если значение false, файлы не загружаются автоматически. Пользователю необходимо нажать кнопку Upload, чтобы запустить процесс загрузки.

Значение по умолчанию - true.

Drag & Drop

Компонент upload поддерживает функциональность перетаскивания, позволяя пользователям загружать файлы, просто перетаскивая их из своей файловой системы и сбрасывая на компонент.

Функциональность drag & drop включена по умолчанию. Чтобы отключить ее, установите атрибут dropAllowed в значение false.

Атрибут dropLabel позволяет настроить сообщение, которое подсказывает пользователям сбросить файлы в область загрузки.

Значение атрибута может быть либо самим текстом, либо ключом в пакете сообщений. В случае ключа, значение должно начинаться с префикса msg://.

Атрибут dropLabelIcon позволяет указать иконку, который будет отображаться вместе с текстом dropLabel.

<upload dropLabel="Drop files here to upload"
        dropLabelIcon="vaadin:cloud-upload-o"/>
upload drag drop

Лимит файлов

По умолчанию, компонент upload не имеет ограничения на количество загружаемых файлов. Вы можете установить лимит количества файлов с помощью атрибута maxFiles.

Этот атрибут задает максимальное количество файлов для загрузки. Если значение установлено в единицу, то стандартный файловый браузер не позволит выбрать несколько файлов.

Исключения, которые возникают, по умолчанию не отображаются в пользовательском интерфейсе. Используйте событие FileRejectedEvent для перехвата этих исключений и, например, уведомление, чтобы проинформировать пользователя о проблеме.

@Autowired
private Notifications notifications;

@Subscribe("upload")
public void onUploadFileRejected(final FileRejectedEvent event) {
    notifications.create(event.getErrorMessage())
            .show();
}

Атрибуты

В Jmix есть множество общих атрибутов, которые выполняют одну и ту же функцию для всех компонентов.

Ниже приведены атрибуты, специфичные для upload:

Название

Описание

Значение по умолчанию

autoUpload

Устанавливает, разрешает ли компонент начать загрузку сразу после выбора файлов. Смотрите Автозагрузка.

true

dropLabel

Задает текст подсказки, которая отображается пользователю, чтобы он мог сбросить файлы в компонент upload. Смотрите Drag & Drop.

dropLabelIcon

Устанавливает иконку для подсказки. Смотрите Drag & Drop.

maxFiles

Задает максимальное количество файлов для загрузки. Смотрите Лимит файлов.

unlimited

uploadHandlerFqn

Задает полное имя класса пользовательской реализации обработчика загрузки для этого компонента upload. Класс должен реализовывать интерфейс Vaadin UploadHandler. Пример значения:

  • com.company.app.upload.CustomUploadHandler

uploadHandlerType

Задает тип встроенного обработчика загрузки. Возможные значения:

  • IN_MEMORY - сохраняет загруженные данные в памяти с помощью InMemoryUploadHandler. В UploadSucceededEvent<V> загруженные данные доступны как byte[].

  • FILE_TEMPORARY_STORAGE - сохраняет загруженные файлы во временное хранилище.

IN_MEMORY

Обработчики

В Jmix существует множество общих обработчиков, которые конфигурируются одинаково для всех компонентов.

Ниже приведены обработчики, специфичные для upload.

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню Code → Generate (Alt+Insert / Cmd+N).

Название

Описание

AllFinishedEvent

Событие com.vaadin.flow.component.upload.AllFinishedEvent отправляется, когда upload обработал все файлы в очереди загрузки, независимо от того, были ли все операции приема успешными или нет.

FailedEvent

Событие com.vaadin.flow.component.upload.FailedEvent отправляется, когда upload принимает файл, но прием по какой-либо причине прерывается. В Java-коде используйте addUploadFailedListener().

FileRejectedEvent

Событие com.vaadin.flow.component.upload.FileRejectedEvent отправляется, когда выбранный для загрузки файл не соответствует ограничениям, заданным для загрузки, например, ограничение размера файла или ограничение количества файлов. Смотрите Лимит файлов.

FileRemovedEvent

Событие com.vaadin.flow.component.upload.FileRemovedEvent отправляется, когда файл удаляется из очереди загрузки.

FinishedEvent

Событие com.vaadin.flow.component.upload.FinishedEvent отправляется, когда upload получает файл, независимо от того, была ли операция приема успешной или завершилась ошибкой. В Java-коде используйте addUploadFinishedListener().

ProgressUpdateEvent

Событие com.vaadin.flow.component.upload.ProgressUpdateEvent отправляется для отслеживания хода загрузки. В Java-коде используйте addUploadProgressListener().

StartedEvent

Событие com.vaadin.flow.component.upload.StartedEvent отправляется, когда upload начинает прием файла. В Java-коде используйте addUploadStartedListener() или подпишитесь на событие компонента в контроллере экрана.

UploadSucceededEvent

Событие io.jmix.flowui.component.upload.UploadSucceededEvent<V> отправляется при успешной загрузке через upload. Событие предоставляет загруженные данные через getData(). В контроллере экрана Jmix подпишитесь на это событие с помощью @Subscribe("upload"). В Java-коде также можно использовать addUploadSucceededListener().

@Autowired
private Notifications notifications;

@Subscribe("upload")
public void onUploadUploadSucceeded(final UploadSucceededEvent<?> event) {
    notifications.create(
                    "Your file %s has been uploaded successfully.".formatted(
                            event.getFileName()))
            .withThemeVariant(NotificationVariant.LUMO_PRIMARY)
            .show();
}

Смотрите также

Дополнительную информацию смотрите в документации Vaadin.