文件上传

#简介

文件上传字段基于 Filepond。

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')

#配置存储磁盘及目录

默认情况下，文件会上传到配置文件中定义的存储磁盘中。你也可以设置 FILESYSTEM_DISK 环境变量来修改他。

要修改特定字段的磁盘和目录，以及文件的可见度，请使用 disk()、directory() 和 visibility() 方法。默认情况下，文件以 private 可见度上传到你的存储磁盘，除非你将该磁盘设置为 public：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->disk('s3')
    ->directory('form-attachments')
    ->visibility('public')

除了允许静态值之外，disk()、directory() 和 visibility() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#上传多个文件

你也可以上传多个文件。这将会把 URL 保存到 JSON 中：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()

或者，你也可以传递布尔值来控制是否可以一次上传多个文件：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple(FeatureFlag::active())

除了允许静态值之外，multiple() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

如果你使用 Eloquent 保存文件 URL，则应确保向模型属性添加一个 array cast：

use Illuminate\Database\Eloquent\Model;

class Message extends Model
{
    protected $casts = [
        'attachments' => 'array',
    ];

    // ...
}

#控制最大并行上传数

你可以使用 maxParallelUploads() 方法控制并行上传的最大数量：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->maxParallelUploads(1)

这会将并行上传数量限制为 1。如果未设置，我们将使用 FilePond 的默认值，即 2。

除了允许静态值之外，maxParallelUploads() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#控制文件名

默认情况下，系统会为新上传的文件生成一个随机文件名。这是为了确保不会与现有文件发生任何冲突。

#控制文件名的安全隐患

在使用 preserveFilenames() 或 getUploadedFileNameForStorageUsing() 方法之前，请注意其安全隐患。如果你允许用户使用自定义文件名上传文件，则他们可能会利用这一点上传恶意文件。即使你使用 acceptedFileTypes() 方法 限制可上传的文件类型，这种情况仍然适用，因为它使用了 Laravel 的 mimetypes 规则，该规则不验证文件的扩展名，只验证其 MIME 类型，而 MIME 类型可能会被篡改。

这主要是 TemporaryUploadedFile 对象上的 getClientOriginalName() 方法存在的问题，而 preserveFilenames() 方法正是使用了该方法。默认情况下，Livewire 会为每个上传的文件生成一个随机文件名，并使用文件的 mime 类型来确定文件扩展名。

如果攻击者上传了具有欺骗性 mime 类型的 PHP 文件，则 在 local 或 public 文件系统磁盘上 使用这些方法会使你的应用容易受到远程代码执行攻击。使用 S3 磁盘可以保护你免受这种特定攻击媒介的影响，因为 S3 执行 PHP 文件的方式与服务器从本地存储提供文件的方式不同。

如果你使用的是 local 或 public 磁盘，则应考虑使用 storeFileNamesIn() 方法将原始文件名存储在数据库的单独列中，并将随机生成的文件名保留在文件系统中。这样，你仍然可以向用户显示原始文件名，同时确保文件系统的安全。

除了这个安全问题之外，你还应该注意，允许用户使用自己的文件名上传文件可能会导致与现有文件冲突，并使你的存储管理变得困难。如果你没有将用户限制在特定目录中，用户可能会上传同名文件并覆盖其他用户的内容，因此这些功能在任何情况下都应仅允许受信任的用户访问。

#保留原始文件名

要保留上传文件的原始文件名，请使用 preserveFilenames() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->preserveFilenames()

或者，你可以传递一个布尔值来控制是否应保留原始文件名：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->preserveFilenames(FeatureFlag::active())

除了允许静态值之外，preserveFilenames() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#生成自定义文件名

你可以完全自定义使用 getUploadedFileNameForStorageUsing() 方法生成文件名的方式，并根据上传的 $file 从闭包中返回一个字符串：

use Livewire\Features\SupportFileUploads\TemporaryUploadedFile;

FileUpload::make('attachment')
    ->getUploadedFileNameForStorageUsing(
        fn (TemporaryUploadedFile $file): string => (string) str($file->getClientOriginalName())
            ->prepend('custom-prefix-'),
    )

你可以将各种 utility 作为参数传入到 getUploadedFileNameForStorageUsing() 的参数方法中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
File	Livewire\Features\SupportFileUploads\TemporaryUploadedFile	$file	The temporary file object being uploaded.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#独立保存原始文件名

你可以使用 storeFileNamesIn() 方法保留随机生成的文件名，同时仍存储原始文件名：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->storeFileNamesIn('attachment_file_names')

attachment_file_names 现在将存储你上传文件的原始文件名，以便你在提交表单时将其保存到数据库。如果你使用 multiple() 上传多个文件，请确保也向此 Eloquent 模型属性添加 array cast。

除了允许静态值之外，storeFileNamesIn() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#头像模式

你可以使用 avatar() 方法为文件上传字段启用头像模式：

use Filament\Forms\Components\FileUpload;

FileUpload::make('avatar')
    ->avatar()

这将仅允许上传图片，上传后，图片将以紧凑的圆形布局显示，非常适合头像。

此功能与圆形裁剪器完美搭配。

#图片编辑器

你可以使用 imageEditor() 方法为文件上传字段启用图像编辑器：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()

上传图片后，点击铅笔图标即可打开编辑器。你也可以点击现有图片上的铅笔图标来打开编辑器，保存后会移除该图片并重新上传。

你也可以选择传递布尔值来控制是否启用图片编辑器：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor(FeatureFlag::active())

除了允许静态值之外，imageEditor() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#允许用户按宽高比裁剪图片

你可以使用 imageEditorAspectRatios() 方法允许用户按一组特定的宽高比裁剪图片：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        '16:9',
        '4:3',
        '1:1',
    ])

你还可以通过传递 null 作为选项来允许用户选择无纵横比、“自由裁剪”：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatios([
        null,
        '16:9',
        '4:3',
        '1:1',
    ])

除了允许静态值之外，imageEditorAspectRatios() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#设置图片编辑器模式

你可以使用 imageEditorMode() 方法更改图片编辑器的模式，该方法接受 1、2 或 3。这些选项的详细说明请参阅 Cropper.js 文档：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorMode(2)

除了允许静态值之外，imageEditorMode() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#自定义图片编辑器为空时的填充颜色

默认情况下，图片编辑器会将图片周围的空白区域设置为透明。你可以使用 imageEditorEmptyFillColor() 方法自定义此功能：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorEmptyFillColor('#000000')

除了允许静态值之外，imageEditorEmptyFillColor() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#设置图片编辑器视窗大小

你可以使用 imageEditorViewportWidth() 和 imageEditorViewportHeight() 方法更改图片编辑器视窗的大小，这会产生一个可跨设备尺寸使用的纵横比：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorViewportWidth('1920')
    ->imageEditorViewportHeight('1080')

除了允许静态值之外，imageEditorViewportWidth() 和 imageEditorViewportHeight() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#允许用户将图片裁剪成圆形

使用 circleCropper() 方法，你可以允许用户将图像裁剪为圆形：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->avatar()
    ->imageEditor()
    ->circleCropper()

这与 avatar() 方法 完美兼容，该方法将图像渲染成紧凑的圆形布局。

你也可以选择传递一个布尔值来控制是否启用圆形裁剪器：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->avatar()
    ->imageEditor()
    ->circleCropper(FeatureFlag::active())

除了允许静态值之外，circleCropper() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#无需编辑器即可裁剪和调整图片大小

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')

除了允许静态值之外，imageResizeMode()、imageCropAspectRatio()、imageResizeTargetHeight() 和 imageResizeTargetWidth() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#修改文件上传区域的外观

你也可以更改 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')

除了允许静态值之外，这些方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#在网格中展示文件

你可以通过设置 panelLayout() 来使用 Filepond grid 布局：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->panelLayout('grid')

除了允许静态值之外，panelLayout() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#文件重新排序

你也可以允许用户使用 reorderable() 方法对上传的文件进行重新排序：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable()

使用此方法时，FilePond 可能会将新上传的文件添加到列表的开头，而不是末尾。要解决这个问题，请使用 appendFiles() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable()
    ->appendFiles()

此外，reorderable() 和 appendFiles() 方法也可以接受布尔值来控制文件是否可以重新排序以及是否应将新文件附加到列表末尾：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->reorderable(FeatureFlag::active())
    ->appendFiles(FeatureFlag::active())

除了允许静态值之外，reorderable() 和 appendFiles() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#在新标签页中打开文件

你可以使用 openable() 方法添加一个按钮，以在新标签页中打开每个文件：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->openable()

或者，你也可以传入一个布尔值来控制是否可以在新选项卡中打开文件：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->openable(FeatureFlag::active())

除了允许静态值之外，openable() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#下载文件

如果你希望为每个文件添加下载按钮，则可以使用 downloadable() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->downloadable()

或者，你也可以传入一个布尔值，以控制文件是否可以被下载：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->downloadable(FeatureFlag::active())

除了允许静态值之外，downloadable() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#预览文件

默认情况下，FilePond 中支持部分文件类型的预览。如果你希望禁用所有文件的预览功能，可以使用 previewable(false) 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->previewable(false)

除了允许静态值之外，previewable() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#表单提交时移动文件而非复制文件

默认情况下，文件最初上传到 Livewire 的临时存储目录，然后在提交表单时复制到目标目录。如果你希望移动文件，并且临时上传的文件与永久文件存储在同一磁盘上，则可以使用 moveFiles() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->moveFiles()

此外，你也可以传入布尔值用以控制是否该移动文件

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->moveFiles(FeatureFlag::active())

除了允许静态值之外，moveFiles() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#防止文件被永久保存

如果你希望在提交表单时防止文件被永久保存，可以使用 storeFiles(false) 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->storeFiles(false)

提交表单时，将返回一个临时文件上传对象，而不是永久存储的文件路径。这对于导入的 CSV 等临时文件来说非常理想。

除了允许静态值之外，storeFiles() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#根据 EXIF 数据调整图像方向

默认情况下，FilePond 会根据 EXIF 数据自动调整图像方向。如果你希望禁用此功能，可以使用 orientImagesFromExif(false) 方法

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->orientImagesFromExif(false)

除了允许静态值之外，orientImagesFromExif() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#隐藏删除文件按钮

使用 deletable(false) 可以隐藏删除上传文件按钮：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->deletable(false)

除了允许静态值之外，deletable() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#阻止文件粘贴

使用 pasteable(false) 方法，你可以禁用通过剪贴板粘贴文件的功能：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->pasteable(false)

除了允许静态值之外，pasteable() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#阻止文件信息获取

表单加载时，系统会自动检测文件是否存在、文件大小以及文件类型。这一切都在后端完成。当使用包含大量文件的远程存储时，这可能会非常耗时。你可以使用 fetchFileInformation(false) 方法禁用此功能：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->fetchFileInformation(false)

除了允许静态值之外，fetchFileInformation() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#自定义上传信息

你可以使用 uploadingMessage() 方法自定义表单提交按钮中显示的上传消息：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->uploadingMessage('Uploading attachment...')

除了允许静态值之外，uploadingMessage() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#文件上传验证

除了验证页面上列出的所有规则外，还有一些特定于文件上传的规则。

由于 Filament 由 Livewire 提供支持并使用其文件上传系统，因此你还需要参考 config/livewire.php 文件中默认的 Livewire 文件上传验证规则。这也控制着 12MB 的最大文件大小。

#文件类型验证

你可以使用 acceptedFileTypes() 方法并传递 MIME 类型数组来限制可以上传的文件类型。

use Filament\Forms\Components\FileUpload;

FileUpload::make('document')
    ->acceptedFileTypes(['application/pdf'])

除了允许静态值之外，acceptedFileTypes() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

你也可以使用 image() 方法作为简写来允许所有图像 MIME 类型。

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()

#自定义 MIME 类型映射

上传文件时，有些文件格式可能无法被浏览器正确识别。Filament 允许你使用 mimeTypeMap() 方法手动定义特定文件后缀的 MIME 类型：

use Filament\Forms\Components\FileUpload;

FileUpload::make('designs')
    ->acceptedFileTypes([
        'x-world/x-3dmf',
        'application/vnd.sketchup.skp',
    ])
    ->mimeTypeMap([
        '3dm' => 'x-world/x-3dmf',
        'skp' => 'application/vnd.sketchup.skp',
    ]);

除了允许静态值之外，mimeTypeMap() 方法也接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#文件大小验证

你也可以限制上传文件的大小(以 KB 为计量单位)：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
    ->minSize(512)
    ->maxSize(1024)

除了允许静态值之外，minSize() 和 maxSize() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

#上传大文件

如果你在上传大文件时遇到问题，比如浏览器控制台中显示 HTTP 请求失败(状态码 422)，你可能需要调整你的配置。

在服务器的 php.ini 文件中，增加最大上传文件大小或许可以解决该问题：

post_max_size = 120M
upload_max_filesize = 120M

Livewire 也会在文件上传前验证文件大小。要发布 Livewire 配置文件，请运行：

php artisan livewire:publish --config

在 temporary_file_upload 的 rules 键中可以调整最大上传文件大小。本例中，规则中使用了 KB，120MB 是 122880KB：

'temporary_file_upload' => [
    // ...
    'rules' => ['required', 'file', 'max:122880'],
    // ...
],

#文件数验证

使用 minFiles() 和 maxFiles() 方法，你可以自定义文件上传的数量：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->minFiles(2)
    ->maxFiles(5)

除了允许静态值之外，minFiles() 和 maxFiles() 方法也接受函数来动态计算它们的值。你可以将各种 utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually create, edit, or view.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion