- Обзор
- Настройка диска и каталога хранения
- Загрузка нескольких файлов
- Управление именами файлов
- Режим аватара
- Редактор изображений
- Обрезка изображений в соответствии с соотношением сторон
- Настройка режима редактора изображений
- Настройка цвета прозрачности заливки редактора изображений
- Установка размера области просмотра редактора изображений
- Позволяет обрезать изображения в виде круга
- Обрезка и изменение размера изображений без редактора
- Изменение внешнего вида области загрузки файлов
- Упорядочивание файлов
- Открытие файлов в новой вкладке
- Загрузка файлов
- Предварительный просмотр файлов
- Перемещение файлов вместо копирования при отправке формы
- Предотвращение постоянного хранения файлов
- Ориентация изображений на основе их EXIF-данных
- Скрытие кнопки удаления файла
- Предотвращение получения информации о файле
- Настройка уведомления о загрузке
- Проверка корректности загружаемых файлов
Обзор
Поле для загрузки файлов в Filament работает на Filepond.
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
Filament также поддерживает
spatie/laravel-medialibrary. Более подробную информацию можно найти в документации к этому плагину.
Настройка диска и каталога хранения
По умолчанию файлы будут открыто загружаться на диск, указанный в конфигурационном файле. Чтобы изменить это, можно задать переменную окружения FILAMENT_FILESYSTEM_DISK.
Для корректного превью изображений и других файлов FilePond требует, чтобы файлы передавались из того же домена, что и приложение, или чтобы присутствовали соответствующие CORS-заголовки. Убедитесь, что переменная окружения
APP_URLверна, или измените настройки драйвера файловой системы, чтобы установить правильный URL. Если файлы размещаются на отдельном домене, например S3, убедитесь, что настроены CORS-заголовки.
Чтобы изменить диск и каталог для определенного поля, а также видимость файлов, используйте методы disk(), directory() и visibility():
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->disk('s3')
->directory('form-attachments')
->visibility('private')Ответственность за удаление этих файлов с диска лежит на разработчике, поскольку Filament не знает, зависят ли они от чего-либо еще. Один из способов сделать это автоматически — наблюдение за событиями модели.
Загрузка нескольких файлов
Предусмотрена возможность загрузки нескольких файлов. В этом случае URL-адреса хранятся в JSON:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()Если вы сохраняете URL-адреса файлов с помощью Eloquent, не забудьте добавить array cast к свойству модели:
use Illuminate\Database\Eloquent\Model;
class Message extends Model
{
protected $casts = [
'attachments' => 'array',
];
// ...
}Управление именами файлов
По умолчанию для вновь загружаемых файлов генерируется случайное имя. Это делается для того, чтобы не возникало конфликтов с существующими именами файлов.
Сохранение оригинальных имен файлов
Чтобы сохранить оригинальные имена загружаемых файлов, используется метод preserveFilenames():
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->preserveFilenames()Создание пользовательских имен файлов
Чтобы настроить генерирование имен файлов, можно использовать метод getUploadedFileNameForStorageUsing(), который возвращает строку из замыкания, построенную на основе $file, который был загружен:
use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;
FileUpload::make('attachment')
->getUploadedFileNameForStorageUsing(
fn (TemporaryUploadedFile $file): string => (string) str($file->getClientOriginalName())
->prepend('custom-prefix-'),
)Независимое хранение оригинальных имен файлов
С помощью метода storeFileNamesIn() можно сохранить случайно сгенерированные имена файлов, сохранив при этом оригинальное имя файла:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->storeFileNamesIn('attachment_file_names')attachment_file_names теперь будет хранить оригинальное имя/имена загруженных файлов, чтобы их можно было сохранить в базе данных при отправке формы. Если загружается несколько файлов multiple(), убедитесь, что в это свойство модели Eloquent также добавлен array cast.
Режим аватара
Вы можете включить режим аватара для поля загрузки файла с помощью метода avatar():
use Filament\Forms\Components\FileUpload;
FileUpload::make('avatar')
->avatar()Это позволит загружать только изображения, а когда они будут загружены, отобразит их в виде круга, который идеально подходит для аватаров.
Эта функция хорошо сочетается с функцией обрезки картинок в виде круга.
Редактор изображений
С помощью метода imageEditor() можно включить редактор изображений для поля загрузки файла:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()Редактор можно открыть после загрузки изображения, нажав на значок карандаша. Редактор также открывается при нажатии на значок карандаша на существующем изображении, что приведет к его удалению и повторной загрузке при сохранении.
Обрезка изображений в соответствии с соотношением сторон
С помощью метода imageEditorAspectRatios() возможно разрешить пользователям обрезать изображения до определенного соотношения сторон:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()
->imageEditorAspectRatios([
'16:9',
'4:3',
'1:1',
])Кроме того, можно разрешить пользователям не выбирать соотношение сторон, "свободное кадрирование" (free cropping), передав в качестве параметра null:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()
->imageEditorAspectRatios([
null,
'16:9',
'4:3',
'1:1',
])Настройка режима редактора изображений
Сменить режим редактора изображений можно с помощью метода imageEditorMode(), который принимает значения 1, 2 или 3. Эти параметры описаны в документации Cropper.js:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()
->imageEditorMode(2)Настройка цвета прозрачности заливки редактора изображений
По умолчанию редактор изображений делает пустое пространство вокруг изображения прозрачным. Его цвет можно изменить с помощью метода imageEditorEmptyFillColor():
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()
->imageEditorEmptyFillColor('#000000')Установка размера области просмотра редактора изображений
С помощью методов imageEditorViewportWidth() и imageEditorViewportHeight() можно изменить размер области просмотра редактора изображений, которые генерируют соотношение сторон для использования на разных устройствах:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageEditor()
->imageEditorViewportWidth('1920')
->imageEditorViewportHeight('1080')Позволяет обрезать изображения в виде круга
С помощью метода circleCropper() можно разрешить пользователям обрезать изображения в виде круга:
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->avatar()
->imageEditor()
->circleCropper()Он прекрасно сочетается с методом avatar(), который отображает изображения в виде компактного круга.
Обрезка и изменение размера изображений без редактора
Filepond позволяет обрезать и изменять размер изображений перед их загрузкой, без необходимости использования отдельного редактора. Это можно настроить с помощью методов imageCropAspectRatio(), imageResizeTargetHeight() и imageResizeTargetWidth(). imageResizeMode() должен быть установлен для того, чтобы эти методы имели эффект – либо force, либо cover, либо contain.
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()
->imageResizeMode('cover')
->imageCropAspectRatio('16:9')
->imageResizeTargetWidth('1920')
->imageResizeTargetHeight('1080')Изменение внешнего вида области загрузки файлов
Также можно изменить общий вид компонента Filepond. Доступные параметры для этих методов можно найти в документации Filepond.
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->imagePreviewHeight('250')
->loadingIndicatorPosition('left')
->panelAspectRatio('2:1')
->panelLayout('integrated')
->removeUploadedFileButtonPosition('right')
->uploadButtonPosition('left')
->uploadProgressIndicatorPosition('left')Упорядочивание файлов
С помощью метода reorderable() можно также разрешить пользователям изменять порядок загруженных файлов при загрузке нескольких файлов:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->reorderable()При использовании этого метода FilePond может добавлять вновь загруженные файлы в начало списка, а не в конец. Чтобы исправить это, используйте метод appendFiles():
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->reorderable()
->appendFiles()Открытие файлов в новой вкладке
С помощью метода openable() можно добавить кнопку для открытия каждого файла в новой вкладке:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->openable()Загрузка файлов
Если требуется добавить кнопку загрузки к каждому файлу, можно использовать метод downloadable():
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->downloadable()Предварительный просмотр файлов
По умолчанию некоторые типы файлов могут быть предварительно просмотрены в FilePond. Если нужно отключить предварительный просмотр для всех файлов, можно использовать метод previewable(false):
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->previewable(false)Перемещение файлов вместо копирования при отправке формы
По умолчанию файлы сначала загружаются в каталог временного хранения Livewire, а затем копируются в целевой каталог при отправке формы. Если требуется переместить файлы вместо этого, при условии, что временные файлы хранятся на том же диске, что и постоянные, можно использовать метод moveFiles():
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->moveFiles()Предотвращение постоянного хранения файлов
Если необходимо запретить постоянное сохранение файлов при отправке формы, можно использовать метод storeFiles(false):
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->storeFiles(false)При отправке формы вместо постоянно хранимого пути к файлу будет возвращен временный объект загрузки файла. Это идеально подходит для временных файлов, таких как импортированные CSV.
Ориентация изображений на основе их EXIF-данных
По умолчанию FilePond автоматически ориентирует изображения, основываясь на их EXIF-данных. Если требуется отключить это поведение, можно воспользоваться методом orientImagesFromExif(false):
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->orientImagesFromExif(false)Скрытие кнопки удаления файла
Также можно скрыть кнопку удаления загруженного файла с помощью функции deletable(false):
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->deletable(false)Предотвращение получения информации о файле
Пока форма загружается, она автоматически определяет, существуют ли файлы, каков их размер и тип. Все это делается на сервере. При использовании удаленного хранилища с большим количеством файлов это может занять много времени. Чтобы отключить эту функцию, можно использовать метод fetchFileInformation(false):
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->fetchFileInformation(false)Настройка уведомления о загрузке
С помощью метода uploadingMessage() можно настроить сообщение о загрузке, которое будет отображаться в кнопке отправки формы:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->uploadingMessage('Uploading attachment...')Проверка корректности загружаемых файлов
Помимо всех правил, перечисленных на странице валидации, есть дополнительные правила, специфичные для загрузки файлов.
Поскольку Filament работает на базе Livewire и использует его систему загрузки файлов, необходимо также обратиться к правилам проверки загрузки файлов Livewire по умолчанию в файле config/livewire.php. Они также задают по умолчанию максимальный размер файла 12 МБ.
Проверка типа файла
С помощью метода acceptedFileTypes() и передачи массива MIME-типов можно ограничить типы загружаемых файлов.
use Filament\Forms\Components\FileUpload;
FileUpload::make('document')
->acceptedFileTypes(['application/pdf'])Также можно использовать метод image(), чтобы разрешить все MIME-типы изображений.
use Filament\Forms\Components\FileUpload;
FileUpload::make('image')
->image()Проверка размера файла
Можно также ограничить размер загружаемых файлов в килобайтах:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachment')
->minSize(512)
->maxSize(1024)Проверка количества файлов
С помощью методов minFiles() и maxFiles() можно настроить количество загружаемых файлов:
use Filament\Forms\Components\FileUpload;
FileUpload::make('attachments')
->multiple()
->minFiles(2)
->maxFiles(5)Перевод с английского официальной документации Filament:
https://filamentphp.com/docs/3.x/forms/fields/file-upload
