DOCS
DOCS

Languages

Version

Theme

表单

文件上传

简介

文件上传字段基于 Filepond。

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
File upload

TIP

Filament 也支持 spatie/laravel-medialibrary。请查看插件文档以获取更多信息。

NOTE

默认情况下，FileUpload 接受配置磁盘内的任何字符串路径——字段值是由客户端控制的字符串，篡改的请求可以提交同一磁盘上的任何其他文件。如果你的磁盘存储了多个用户、租户或记录的文件，请对该字段调用 ->preventFilePathTampering()（或使用 FileUpload::configureUsing() 进行全局应用），或在磁盘或目录级别隔离上传，以便该字段只能处理属于当前所有者的文件。

配置存储磁盘及目录

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

TIP

为了正确预览图像和其他文件，Filepond 要求文件与应用来自同一域名，或者需要存在相应的 CORS 标头。确保 APP_URL 环境变量正确，或修改文件系统驱动以设置正确的URL。如果你在单独的域名(如 S3)上托管文件，请确保设置了 CORS 标头。

要修改特定字段的磁盘和目录，以及文件的可见度，请使用 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.

NOTE

默认可见性由磁盘名称的字面字符串匹配决定：名为 public 的磁盘被视为公开可见，而任何其他磁盘名称默认为 private。因此，即使自定义磁盘的底层配置为私有，如果恰好命名为 public，也会被视为公开可见；而不同名称的自定义公开可见磁盘则默认为私有。为避免混淆，请为自定义磁盘提供明确的名称，或在每个字段上显式设置 visibility()。

NOTE

如果这些文件被移除，开发者有责任从磁盘中删除它们，因为 Filament 无法感知它们是否被其他地方依赖。自动执行此操作的一种方法是观察 模型事件。

上传多个文件

你也可以上传多个文件。这将会把 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
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    { 
        return [
            '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() 方法将原始文件名存储在数据库的单独列中，并将随机生成的文件名保留在文件系统中。这样，你仍然可以向用户显示原始文件名，同时确保文件系统的安全。

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

保留原始文件名

NOTE

在使用此功能之前，请确保你已阅读安全隐患。

要保留上传文件的原始文件名，请使用 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.

生成自定义文件名

NOTE

在使用此功能之前，请确保你已阅读安全隐患。

你可以完全自定义使用 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.

授权现有文件路径

FileUpload 字段的值是一个字符串或字符串数组，其中包含配置磁盘上文件的路径。与任何其他 Livewire 表单字段值一样，它由客户端控制：可以拦截请求以将提交的路径更改为同一磁盘上的任何其他文件。如果该字段指向其他用户无法访问的资源（共享磁盘上的私有文档或用户持有的目录），则攻击者可能会以其他方式导致记录引用（并提供签名 URL）其他人的文件。

Filament 默认允许这样做，因为合法功能依赖于它——例如，将字段设置为预上传的模板文件的操作，或“从另一条记录复制”按钮。如果你的字段都不依赖于此类流程，请在字段上调用 preventFilePathTampering() 以启用内置检查：

use Filament\Forms\Components\FileUpload;

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

Filament 会将每个提交的字符串路径与最初从记录中加载的值（通过 $record->getOriginal() 方法获取与字段名称匹配的属性）进行比较。如果不匹配，则会导致该字段验证失败，因此记录永远不会以篡改后的值保存。新上传的文件总是会通过验证，该字段仍然可以被清空，对于 multiple() 字段，每个条目都会单独进行检查。

NOTE

preventFilePathTampering() 需要表单上有记录。如果没有（比如，在新建页面 ），除非 allowFilePathUsing 回调允许，每个提交的字符串路径都会验证失败。新上传的文件不受影响。

要在应用的每个 FileUpload 上应用此检查，而不在每个字段上重复，请在服务提供者的 boot() 方法中调用 configureUsing()：

use Filament\Forms\Components\FileUpload;

FileUpload::configureUsing(function (FileUpload $component): void {
    $component->preventFilePathTampering();
});

单个字段仍然可以通过调用 preventFilePathTampering(false) 来选择退出。

允许通过回调函数添加额外的文件路径

如果你的应用合法地引用了不在记录中的路径（例如，一个用于选择预先上传的模板文件的按钮），请传递 allowFilePathUsing 参数以批准该路径。已批准的路径将绕过验证错误：

use Filament\Forms\Components\FileUpload;

FileUpload::make('avatar')
    ->preventFilePathTampering(
        allowFilePathUsing: fn (string $file): bool => str_starts_with($file, 'templates/'),
    )
你可以将各个 utility 作为参数传入到 allowFilePathUsing 的函数中。 了解更多 utility 注入详情。
Utility 类型 参数 描述
Field Filament\Forms\Components\Field $component The current field component instance.
File string $file The submitted file path being authorized.
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.

此验证错误信息可以在 validationMessages() 中使用 tampered 键自定义：

use Filament\Forms\Components\FileUpload;

FileUpload::make('avatar')
    ->preventFilePathTampering()
    ->validationMessages([
        'tampered' => 'The selected attachment is not permitted.',
    ])

头像模式

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

use Filament\Forms\Components\FileUpload;

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

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

File upload with avatar mode

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

图片编辑器

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

use Filament\Forms\Components\FileUpload;

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

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

File upload image editor with cropping controls

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

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.

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

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

use Filament\Forms\Components\FileUpload;

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

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

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageEditor()
    ->imageEditorAspectRatioOptions([
        null,
        '16:9',
        '4:3',
        '1:1',
    ])
除了允许静态值之外，imageEditorAspectRatioOptions() 方法也接受函数来动态计算其值。你可以将各种 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.

强制执行特定的宽高比

如果你需要确保所有上传的图像都符合特定的宽高比，你可以将 imageAspectRatio() 验证方法与 automaticallyOpenImageEditorForAspectRatio() 结合使用。当用户上传与所需宽高比不匹配的图像时，这将自动打开一个简化的图像编辑器，允许他们在保存图像之前对其进行裁剪：

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')
    ->automaticallyOpenImageEditorForAspectRatio()

需要裁剪时出现的编辑器仅显示裁剪区域和保存/取消按钮，不包括使用 imageEditor() 时出现的完整编辑控件（旋转、位置输入等）。这提供了一种简化的体验，专注于获得正确的宽高比。

如果你想让用户访问完整的图像编辑器控件，你可以同时启用这两个：

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageEditor()
    ->imageAspectRatio('16:9')
    ->automaticallyOpenImageEditorForAspectRatio()

启用这两个选项后，当宽高比不匹配时，图像编辑器仍将自动打开，但用户还将在每个上传的图像上看到一个编辑按钮，并可以访问所有编辑控件。

可选地，你可以传递一个布尔值来控制是否启用宽高比编辑器：

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')
    ->automaticallyOpenImageEditorForAspectRatio(FeatureFlag::active())
除了允许静态值外，automaticallyOpenImageEditorForAspectRatio() 也接受函数作为参数动态计算其值。你可以将各种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.

NOTE

automaticallyOpenImageEditorForAspectRatio() 只能用于单个宽高比。如果你允许多个宽高比，请只使用 imageAspectRatio() 验证，并考虑同时使用 imageEditor() 和 imageEditorAspectRatioOptions()，以让用户选择它们想要的宽高比。

NOTE

当 multiple() 启用时，automaticallyOpenImageEditorForAspectRatio() 方法不可用。

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

Filepond 允许你在上传图片之前裁剪和调整图片大小，无需使用单独的编辑器。你可以使用 automaticallyResizeImagesToHeight() 和 automaticallyResizeImagesToWidth() 方法自定义此行为。需要设置 automaticallyResizeImagesMode() 才能使这些方法生效 - 可以是 force、cover 或 contain。

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->automaticallyResizeImagesMode('cover')
    ->automaticallyCropImagesToAspectRatio('16:9')
    ->automaticallyResizeImagesToWidth('1920')
    ->automaticallyResizeImagesToHeight('1080')

要启用特定宽高比的自动裁剪，请使用 automaticallyCropImagesToAspectRatio() 方法。如果你也设置了 imageAspectRatio() 验证，并希望自动裁剪使用相同的比率，你可以在没有任何参数的情况下调用 automaticallyCropImagesToAspectRatio()：

use Filament\Forms\Components\FileUpload;

FileUpload::make('image')
    ->image()
    ->imageAspectRatio('16:9')
    ->automaticallyCropImagesToAspectRatio()
    ->automaticallyResizeImagesMode('cover')
    ->automaticallyResizeImagesToWidth('1920')
    ->automaticallyResizeImagesToHeight('1080')
除了允许静态值之外，automaticallyResizeImagesMode()、automaticallyCropImagesToAspectRatio()、automaticallyResizeImagesToHeight() 和 automaticallyResizeImagesToWidth() 方法也接受函数来动态计算它们的值。你可以将各种 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.

NOTE

当使用自动图片裁剪时，图片会在没有用户交互的情况下裁剪。用户无法选择保留图片的哪些部分。如果你希望用户可以控制裁剪方式，请使用 automaticallyOpenImageEditorForAspectRatio()。

修改文件上传区域的外观

你也可以更改 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')
File upload with grid layout
除了允许静态值之外，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.
File upload with openable files

自定义打开文件时的 URL

默认情况下，“打开”按钮链接到用于在 FileBond 中显示文件的同个 URL。如果你需要一个不同的 URL，比如，一个签名 URL、一个不同域的 URL，或者一个派生文件的 URL，如 Spatie Media Library 的图像生成器生成的 PDF 缩略图 —— 你可以使用 getOpenableFileUrlUsing() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->openable()
    ->getOpenableFileUrlUsing(fn (string $file): string => Storage::disk('s3')->temporaryUrl($file, now()->addMinutes(5)))

该函数接收存储的文件路径 $file，并且必须返回打开按钮点击时使用的 URL。返回 null 会回退到默认 URL。

The getOpenableFileUrlUsing() method also accepts a function with utility injection. In addition to the standard utilities, the $file parameter contains the stored file path. 了解更多 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.
File upload with downloadable files

自定义下载文件时使用的 URL

默认情况下，下载按钮链接到用于在 FileBond 中显示文件的同一 URL。如果你需要一个不同的 URL——例如，一个带有 Content-Disposition: attachment 标头的签名 URL，或者在预览渲染派生图像时指向原始文件的 URL——你可以使用 getDownloadableFileUrlUsing() 方法：

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachments')
    ->multiple()
    ->downloadable()
    ->getDownloadableFileUrlUsing(fn (string $file): string => route('attachments.download', ['path' => $file]))

该函数接收存储的 $file 路径，并且必须返回单击下载按钮时应使用的 URL。返回 null 将返回默认 URL。

getDownloadableFileUrlUsing() 方法也接受一个使用 utility 注入的函数。除了标准 utility 之外，$file 参数指向存储的文件路径。 了解更多 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.

NOTE

除非你使用 previewable(false)，否则图片、视频和音频文件在表单预览中不会显示存储的文件名。这是由于 FilePond 预览插件的限制。

根据 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 的最大文件大小。

NOTE

其中许多验证规则仅适用于新上传的文件。在添加验证规则之前上传的现有文件将不会重新验证。

文件类型验证

NOTE

默认情况下，FileUpload 接受任何文件类型，与 Laravel file 验证规则相同。在由执行 PHP 的 web 服务器提供的 local 或 public 磁盘上，这意味着用户可以上传一个 .php 文件并将其作为代码执行——远程代码执行。你应该总是使用 MIME 类型的显式列表调用acceptedFileTypes()（或 image()），除非你有特定的理由不这样做。这样做还会通过 mimetypes 验证规则激活 Laravel 在 PHP 家族扩展（.php、.phtml、.phar 等）上的内置块，拒绝客户端提供的文件名将作为可执行代码落在磁盘上的文件。

你可以使用 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()
File upload with image preview

自定义 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() 方法也接受函数来动态计算它们的值。你可以将各种 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.

图片尺寸验证

使用 rule() 方法搭配 Laravel 的 Rule::dimensions()，你可以限制上传图片的尺寸：

use Filament\Forms\Components\FileUpload;
use Illuminate\Validation\Rule;

FileUpload::make('photo')
    ->image()
    ->rule(Rule::dimensions()->minWidth(800)->minHeight(600))

use Filament\Forms\Components\FileUpload;
use Illuminate\Validation\Rule;

FileUpload::make('photo')
    ->image()
    ->rule(Rule::dimensions()->maxWidth(1920)->maxHeight(1080))

你可以结合最小值和最大值约束：

use Filament\Forms\Components\FileUpload;
use Illuminate\Validation\Rule;

FileUpload::make('photo')
    ->image()
    ->rule(
        Rule::dimensions()
            ->minWidth(800)
            ->minHeight(600)
            ->maxWidth(1920)
            ->maxHeight(1080)
    )

NOTE

这些尺寸验证规则仅适用于新上传的文件。在添加验证规则之前上传的现有文件将不会重新验证。

图片宽高比验证

使用 imageAspectRatio() 方法，你可以严格限制上传图片的宽高比：

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')

通过传入数组，你可以允许多个宽高比：

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio(['16:9', '4:3', '1:1'])
除了允许静态值外，imageAspectRatio() 也接受函数作为参数动态计算其值。你可以将各种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.

你也可以使用 Rule::dimensions() 指定可接受的宽高比范围：

use Filament\Forms\Components\FileUpload;
use Illuminate\Validation\Rule;

FileUpload::make('banner')
    ->image()
    ->rule(Rule::dimensions()->minRatio(4 / 3)->maxRatio(16 / 9))

NOTE

这些宽高比验证规则仅适用于新上传的文件。在验证规则添加之前上传的现有文件将不会重新验证。

TIP

如果你想帮助用户满足宽高比要求，而不仅仅是拒绝无效的上传，可以考虑在 imageAspectRatio() 边上使用 automaticallyOpenImageEditorForAspectRatio()。这将会在上传图片不满足尺寸要求时，自动打开裁剪编辑器。或者，你也可以使用 automaticlyCropImagesToAspectRatio()将图像自动裁剪到所需的比例，而无需用户交互。

文件数验证

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

use Filament\Forms\Components\FileUpload;

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

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

Previous
Date-time picker
Next
富文本编辑器
Your logo here? 💖