fileUploadField 单文件上传

fileUploadField 将文件上传到内存，以字节数组保存。

XML 元素

fileUploadField

Java 类

FileUploadField

基本用法

这个控件可以包含标题、已上传文件的链接和一个上传按钮。当点击上传按钮的时候，会弹出标准的文件选择器，用户可以在这里选择需要上传的文件。

fileUploadField 既可以 绑定实体属性，也可以不绑定数据。

下面的示例我们展示在没有数据绑定的情况下使用组件。可以用来直接处理上传的文件，而无需将其与任何 Jmix 实体关联。典型的使用场景是需要处理文件、将其保存到其他位置或执行某些其他操作而不进行持久化存储。

<fileUploadField id="fileUploadField"
                 clearButtonVisible="true"
                 fileNameVisible="true"
                 dropAllowed="true"
                 acceptedFileTypes=".pdf, .jpeg, .jpg, .png, .doc, .docx"
                 maxFileSize="921600"
                 label="msg://fileUploadField.label"
                 helperText="msg://fileUploadField.helperText"
                 fileTooBigText="msg://fileUploadField.fileTooBigText"/>

可以直接在 FileUploadSucceededEvent 事件中处理上传的文件。

@Autowired
private Notifications notifications;

@Subscribe("fileUploadField")
public void onFileUploadFieldFileUploadSucceeded(final FileUploadSucceededEvent<FileStorageUploadField, byte[]> event) {
    notifications.create("Your file %s has been uploaded successfully.".formatted(event.getFileName()))
            .withThemeVariant(NotificationVariant.LUMO_PRIMARY)
            .show();
}
fileUploadField 内部使用了 Vaadin 的 UploadHandler API 并将上传的文件以字符数组的形式保存在内存中。没有在文件系统创建任何物理文件。因此在处理不需要持久化存储的小文件时特别方便。

上传和保存大文件时，建议使用 fileStorageUploadField 组件。

如需同时上传多个文件，请使用 upload 组件。

数据感知的 fileUploadField

在线示例

fileUploadField 支持用户上传文件并以字符数组的格式保存在实体属性中。

下面例子中，User 实体的 document 属性是字节数组类型。

@Column(name = "DOCUMENT")
private byte[] document;
<data>
    <instance id="pictureDc" class="io.jmix.uisamples.entity.Picture">
    </instance>
</data>
<layout>
    <fileUploadField id="fileUploadField" label="Select File"
                     dataContainer="pictureDc" property="content"
                     clearButtonVisible="true"
                     fileNameVisible="true"
                     dropAllowed="true"
                     maxFileSize="51200"
                     acceptedFileTypes="image/png,image/jpeg"
    />
</layout>

fileUploadField 的 dataContainer 属性设置为数据容器；而 property 属性设置为展示在 fileUploadField 组件的实体属性。

如需上传文件至文件存储，并使用 FileRef 类型作为实体属性，请使用 fileStorageUploadField 组件。

XML 属性

下面是 fileUploadField 的特殊属性：

名称 描述 默认值

acceptedFileTypes

设置支持的文件类型。

—

clearButtonAriaLabel

设置清除按钮的 aria-label 属性。

—

clearButtonVisible

设置是否显示清除按钮。

false

connectingStatusText

设置当上传对话框连接后显示的状态文字。

—

dropAllowed

设置是否允许用户拖拽文件进行上传。

—

fileName

当组件值是通过数据容器设置时，设置需要显示的文本。

—

fileNameVisible

设置是否显示所选文件的名称。

—

fileNotSelectedText

设置当无选中文件时显示的文本。

—

fileTooBigText

设置文件超出大小限制时显示的信息。

—

incorrectFileTypeText

设置文件类型不匹配时显示的信息。

—

maxFileSize

设置允许上传的最大文件大小，单位为字节。

—

processingStatusText

设置当上传文件正在处理时显示的状态文本。

—

remainingTimeText

设置显示剩余上传时间的文本。

—

remainingTimeUnknownText

设置当无法计算剩余上传时间时显示的文本。

—

uploadDialogCancelText

设置上传对话框中取消按钮的文本。

—

uploadDialogTitle

设置上传对话框的标题。

—

uploadIcon

设置上传按钮的图标。

—

uploadText

设置上传按钮显示的文本。

—

下面是 fileUploadField 支持的其他通用属性：

id - alignSelf - classNames - colspan - css - dataContainer - enabled - errorMessage - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - readOnly - required - requiredMessage - visible - width

事件和处理器

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

名称 描述

FileUploadFailedEvent

文件上传失败时发出。

FileUploadFileRejectedEvent

文件由于违反了约束被拒绝时发出。

FileUploadFinishedEvent

文件上传完成时发出。

FileUploadProgressEvent

文件上传进度变化时发出。

FileUploadStartedEvent

文件开始上传时发出。

FileUploadSucceededEvent

io.jmix.flowui.kit.component.upload.event.FileUploadSucceededEvent 当底层 Upload 组件发出 SucceededEvent 事件时发送。

validator

验证组件值。

下面是 fileUploadField 支持的其他通用事件：

AttachEvent - ComponentValueChangeEvent - DetachEvent - statusChangeHandler

XML 内部元素

一个 fileUploadField 可以包含 tooltip 和 uploadIcon 作为其内部元素。