5.5.2.1.16. FileUploadField
Компонент FileUploadField
позволяет пользователю загружать файлы на сервер. Компонент может содержать заголовок, ссылку на загруженный файл и две кнопки: для загрузки файла и для очистки. При нажатии на кнопку загрузки на экране отображается стандартное для операционной системы окно, в котором можно выбрать один файл. Чтобы дать пользователю возможность загружать сразу несколько файлов, используйте компонент FileMultiUploadField.
XML-имя компонента: upload
.
Компонент реализован для блоков Web Client и Desktop Client.
-
FileUploadField
автоматически используется внутри FieldGroup для атрибутов типаFileDescriptor
. В этом случае компонент выглядит как на приведенном выше скриншоте и не требует никакого конфигурирования. Загруженный файл сразу же сохраняется в file storage, а соответствующийFileDescriptor
- в базу данных. -
Компонент можно использовать вне
FieldGroup
и подключить к источнику данных. В примере ниже предполагается, что источник данныхpersonDs
содержит сущность с атрибутомphoto
, который является ссылкой наFileDescriptor
:<upload fileStoragePutMode="IMMEDIATE" datasource="personDs" property="photo"/>
-
Сохранением файла и
FileDescriptor
можно также управлять программно.-
Объявляем компонент в XML-дескрипторе экрана:
<upload id="uploadField" fileStoragePutMode="MANUAL"/>
-
-
В контроллере экрана инжектируем сам компонент, а также интерфейсы FileUploadingAPI и DataSupplier. Затем в методе
init()
добавляем слушатели, которые будут реагировать на события успешной загрузки или ошибки:@Inject private FileUploadField uploadField; @Inject private FileUploadingAPI fileUploadingAPI; @Inject private DataSupplier dataSupplier; @Override public void init(Map<String, Object> params) { uploadField.addFileUploadSucceedListener(event -> { // here you can get the file uploaded to the temporary storage if you need it File file = fileUploadingAPI.getFile(uploadField.getFileId()); if (file != null) { showNotification("File is uploaded to temporary storage at " + file.getAbsolutePath()); } // normally you would want to save the file to the file storage of the middle tier FileDescriptor fd = uploadField.getFileDescriptor(); try { // save file to FileStorage fileUploadingAPI.putFileIntoStorage(uploadField.getFileId(), fd); } catch (FileStorageException e) { throw new RuntimeException("Error saving file to FileStorage", e); } // save file descriptor to database dataSupplier.commit(fd); showNotification("Uploaded file: " + uploadField.getFileName()); }); uploadField.addFileUploadErrorListener(event -> showNotification("File upload error")); }
Компонент загружает файл во временное хранилище клиентского уровня и вызывает слушатель, добавленный методом
addFileUploadSucceedListener()
. В этом слушателе у компонента запрашивается объектFileDescriptor
, соответствующий загруженному файлу. Объектcom.haulmont.cuba.core.entity.FileDescriptor
является персистентной сущностью, которая однозначно идентифицирует загруженный файл и впоследствии используется для выгрузки файла из системы.Метод
FileUploadingAPI.putFileIntoStorage()
используется для перемещения загружаемого файла из временного хранилища клиентского уровня в FileStorage. Параметрами этого метода являются идентификатор файла во временном хранилище и объектFileDescriptor
. Оба эти параметра предоставляетFileUploadField
.После загрузки файла в
FileStorage
выполняется сохранение экземпляраFileDescriptor
в базе данных посредством вызоваDataSupplier.commit()
. Возвращаемый этим методом сохраненный экземпляр может быть установлен в атрибут какой-либо сущности предметной области, связанной с данным файлом. В данном же случаеFileDescriptor
просто сохраняется в базе данных. Соответствующий файл будет доступен через экран Administration → External Files.Слушатель, добавленный методом
addFileUploadErrorListener()
, вызывается в случае ошибки загрузки файла во временное хранилище клиентского уровня.Ниже приведён полный список доступных слушателей для отслеживания процесса загрузки:
-
AfterValueClearListener
,
-
BeforeValueClearListener
,
-
FileUploadErrorListener
,
-
FileUploadFinishListener
-
FileUploadStartListener
,
-
FileUploadSucceedListener
, -
ValueChangeListener
.
-
Атрибуты fileUploadField
:
-
fileStoragePutMode
- задает режим сохранения файла и соответствующегоFileDescriptor
.-
В режиме
IMMEDIATE
это делается автоматически сразу после загрузки файла во временное хранилище клиентского уровня. -
В режиме
MANUAL
необходимо сделать это в листенереFileUploadSucceedListener
.Режим
IMMEDIATE
выбирается по умолчанию, когдаFileUploadField
используется внутриFieldGroup
. В противном случае, по умолчанию выбираетсяMANUAL
.
-
-
XML-атрибуты
uploadButtonCaption
,uploadButtonIcon
иuploadButtonDescription
позволяют задать параметры кнопки загрузки.
-
showFileName
- управляет отображением имени загруженного файла рядом с кнопкой загрузки. По умолчаниюfalse
.
-
showClearButton
- управляет видимостью кнопки очистки. По умолчаниюfalse
.
-
XML-атрибуты
clearButtonCaption
,clearButtonIcon
иclearButtonDescription
позволяют задать параметры кнопки очистки, если она видима.
-
XML-атрибут
accept
(и соответствующий методsetAccept()
) может быть использован для установки маски расширений файлов в диалоге выбора файла. Пользователи будут иметь возможность выбрать "All files" и загрузить произвольные файлы.Значением атрибута должен быть список масок, разделенных запятыми. Например:
*.jpg,*.png
. -
Максимальный размер загружаемого файла определяется свойством приложения cuba.maxUploadSizeMb и по умолчанию равен 20MB. При выборе пользователем файла большего размера выдается соответствующее сообщение и загрузка прерывается.
-
XML-атрибут
fileSizeLimit
(и соответствующий методsetFileSizeLimit()
) может быть использован для установки максимально допустимого размера файла. Значением атрибута должно быть целое число для указания количества байт.<upload id="uploadField" fileSizeLimit="2000"/>
-
XML-атрибут
permittedExtensions
(и соответствующий методsetPermittedExtensions()
) может быть использован для установки "белого списка" допустимых расширений загружаемых файлов.Значением атрибута должен быть набор расширений с лидирующими точками, разделенных запятыми. Например:
uploadField.setPermittedExtensions(Sets.newHashSet(".png", ".jpg"));
-
dropZone
- используется для указания BoxLayout, который будет использован в качестве целевой площадки для перетаскивания файлов извне браузера. Зона перетаскивания может занимать всю площадь диалогового окна. Выбранный контейнер будет подсвечиваться, когда пользователь переносит над ним файлы, без наведения файла контейнер не отображается.<layout spacing="true" width="100%"> <vbox id="dropZone" height="AUTO" spacing="true"> <textField id="textField" caption="Title" width="100%"/> <textArea id="textArea" caption="Description" width="100%" rows="5"/> <checkBox caption="Is reference document" width="100%"/> <upload id="upload" dropZone="dropZone" showClearButton="true" showFileName="true"/> </vbox> <hbox spacing="true"> <button caption="mainMsg://actions.Apply"/> <button caption="mainMsg://actions.Cancel"/> </hbox> </layout>
Чтобы сделать область dropZone статической и отображать её постоянно, необходимо назначить её контейнеру готовый стиль
dropzone-container
. В этом случае контейнер необходимо оставить пустым, поместив в него только текстовый компонентlabel
:<layout spacing="true" width="100%"> <textField id="textField" caption="Title" width="100%"/> <checkBox caption="Is reference document" width="100%"/> <upload id="upload" dropZone="dropZone" showClearButton="true" showFileName="true"/> <vbox id="dropZone" height="150px" spacing="true" stylename="dropzone-container"> <label stylename="dropzone-description" value="Drop file here" align="MIDDLE_CENTER"/> </vbox> <hbox spacing="true"> <button caption="mainMsg://actions.Apply"/> <button caption="mainMsg://actions.Cancel"/> </hbox> </layout>
-
pasteZone
- используется для указания контейнера, который будет использован для обработки нажатий горячих клавиш вставки, когда текстовое поле внутри этого контейнера находится в фокусе. Это свойство поддерживается семейством браузеров на базе Chromium.<upload id="uploadField" pasteZone="vboxId" showClearButton="true" showFileName="true"/>
В разделе Загрузка и вывод изображений приведен более сложный пример работы с загруженными файлами.
- Атрибуты upload
-
accept - align - caption - clearButtonCaption - clearButtonDescription - clearButtonIcon - contextHelpText - contextHelpTextHtmlEnabled - datasource - description - dropZone - editable - enable - fileSizeLimit - fileStoragePutMode - height - icon - id - pasteZone - permittedExtensions - property - showClearButton - showFileName - stylename - tabIndex - uploadButtonCaption - uploadButtonDescription - uploadButtonIcon - visible - width
- API
-
addValueChangeListener - commit - discard - isModified - setContextHelpIconClickHandler
- Слушатели upload
-
AfterValueClearListener - BeforeValueClearListener - FileUploadErrorListener - FileUploadFinishListener - FileUploadStartListener - FileUploadSucceedListener