upload 上传

在线示例

upload 支持用户上传一个或多个文件，并显示每个文件的上传进度和状态。可以通过单击 Upload files 按钮或将文件拖放至组件进行上传。

XML 元素

upload

Java 类

JmixUpload

XML 属性

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

XML 内部元素

uploadIcon - dropLabelIcon

基本用法

upload 的示例：

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

自动上传

autoUpload 属性设置组件是否在用户选择了文件之后自动上传，或者是需要用户主动触发上传。

  • 当设置为 true 时，文件会在选择后自动上传。此时会显示上传进度，用户还可以按需取消上传。

  • 当设置为 false 时，文件不会自动上传。用户必须点击 Upload 按钮开始上传。

默认值为 true。

拖放

upload 组件支持拖放功能，用户可以从文件系统直接拖拽文件至该组件实现上传。

拖放功能默认开启。如需禁用，请设置 dropAllowed 属性为 false。

dropLabel 属性设置组件中引导用户拖放文件的文本。

该属性的值可以是一个纯文本，或 消息包 中的一个键值。如果是键值，需要以 msg:// 开头。

dropLabelIcon 属性设置一个 dropLabel 文本旁边可以显示的图标。

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

文件计数

默认情况下，upload 不限制用户可以上传的文件数量。可以通过 maxFiles 属性控制用户能上传的文件数。

设置允许用户上传的最大文件个数。如果设置为 1，则系统原生的文件选择器将不允许选择多个文件。

默认不会在 UI 显示文件上传的异常。请使用 FileRejectedEvent 捕捉异常，然后可以使用通知为用户展示异常。

@Autowired
private Notifications notifications;

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

XML 属性

通用属性 对所有组件都是一样的配置。

下面是 upload 的特殊属性：

名称

描述

默认值

autoUpload

设置组件是否在选择文件后自动上传。参阅 自动上传。

true

dropLabel

设置组件中引导用户拖放文件的文本。参阅 拖放。

dropLabelIcon

设置 dropLabel 的图标。用户可以拖放文件时该图标可见。参阅 拖放。

maxFiles

设置允许上传的最大文件数量。参阅 文件计数

无限制

uploadHandlerFqn

为该 upload 组件设置自定义上传处理方法实现的完整限定名称。该类必须实现 Vaadin 的 UploadHandler 接口。示例：

  • com.company.app.upload.CustomUploadHandler

uploadHandlerType

指定内置的上传处理方法的类型。支持以下值：

  • IN_MEMORY – 用 InMemoryUploadHandler 将上传的数据保存在内存中。在 UploadSucceededEvent<V> 事件中，上传数据的格式是 byte[]。

  • FILE_TEMPORARY_STORAGE 将上传的文件保存在 临时存储。

IN_MEMORY

事件和处理器

通用事件和处理器 对所有组件都是一样的配置。

下面是 upload 的特殊事件和处理器：

在 Jmix Studio 生成处理器桩代码时，可以使用 Jmix UI 组件面板的 Handlers 标签页或者视图类顶部面板的 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 当选择的文件不满足 upload 的要求时发送，例如，文件大小限制 或 文件数量限制。参阅 文件数量。

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 文档