DOCS
DOCS

Languages

Version

Theme

表单

文件上传

简介

文件上传字段基于 Filepond。

use Filament\Forms\Components\FileUpload;

FileUpload::make('attachment')
File upload

TIP

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

NOTE

By default, FileUpload accepts any string path within the configured disk — the field value is a client-controlled string and a tampered request can submit any other file on the same disk. If your disk holds files for more than one user, tenant, or record, either call ->preventFilePathTampering() on the field (or apply it globally with FileUpload::configureUsing()), or isolate uploads at the disk or directory level so the field can only ever address files belonging to the current owner.

配置存储磁盘及目录

默认情况下，文件会上传到配置文件中定义的存储磁盘中。你也可以设置 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

The default visibility is decided by a literal string match against the disk name: a disk literally named public is treated as publicly visible, and any other disk name defaults to private. A custom disk that happens to be named public will therefore be treated as public even if its underlying configuration is private, and a custom publicly-visible disk under a different name will default to private. To avoid confusion, either give custom disks unambiguous names or set visibility() explicitly on each field.

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.

Authorizing existing file paths

The value of a FileUpload field is a string, or an array of strings, containing the path to the file on the configured disk. Like any other Livewire form field value, it is controlled by the client: a request can be intercepted to change the submitted path to any other file on the same disk. If the field points at a resource that must not be accessible to other users — a private document on a shared disk, or a per-user directory — an attacker could otherwise cause the record to reference (and serve a signed URL for) someone else’s file.

Filament allows this by default because legitimate features depend on it — for example, an action that sets the field to a pre-uploaded template file, or a “copy from another record” button. If none of your fields rely on such a flow, call preventFilePathTampering() on the field to enable a built-in check:

use Filament\Forms\Components\FileUpload;

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

Filament compares every submitted string path against the value originally loaded from the record (via $record->getOriginal() for the attribute matching the field name). Paths that do not match cause the field to fail validation, so the record is never saved with a tampered value. Newly uploaded files always pass through, the field can still be cleared, and for multiple() fields each entry is checked individually.

NOTE

preventFilePathTampering() needs a record on the form. Without one — for example, on a create page — every submitted string path fails validation unless the allowFilePathUsing callback approves it. New uploads are unaffected.

To apply this check to every FileUpload in your application without repeating it on each field, call configureUsing() in a service provider’s boot() method:

use Filament\Forms\Components\FileUpload;

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

Individual fields can still opt out by calling preventFilePathTampering(false).

Allowing additional file paths with a callback

If your application legitimately references a path that is not on the record — for example, a button that selects a pre-uploaded template file — pass the allowFilePathUsing argument to approve it. Approved paths bypass the validation error:

use Filament\Forms\Components\FileUpload;

FileUpload::make('avatar')
    ->preventFilePathTampering(
        allowFilePathUsing: fn (string $file): bool => str_starts_with($file, 'templates/'),
    )
You can inject various utilities into the function passed to allowFilePathUsing as parameters. 了解更多 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.

The validation error message can be customized via validationMessages() using the tampered key:

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.

Enforcing a specific aspect ratio

If you need to ensure all uploaded images conform to a specific aspect ratio, you can combine the imageAspectRatio() validation method with automaticallyOpenImageEditorForAspectRatio(). This will automatically open a simplified image editor when a user uploads an image that doesn’t match the required aspect ratio, allowing them to crop the image before it is saved:

use Filament\Forms\Components\FileUpload;

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

The editor that appears when cropping is required only shows the crop area and save/cancel buttons - it does not include the full editing controls (rotation, position inputs, etc.) that appear when using imageEditor(). This provides a streamlined experience focused on getting the correct aspect ratio.

If you want users to have access to the full image editor controls, you can enable both:

use Filament\Forms\Components\FileUpload;

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

With both enabled, the image editor will still open automatically when the aspect ratio doesn’t match, but users will also see an edit button on each uploaded image and have access to all editing controls.

Optionally, you may pass a boolean value to control if the aspect ratio editor is enabled:

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio('16:9')
    ->automaticallyOpenImageEditorForAspectRatio(FeatureFlag::active())
As well as allowing a static value, the automaticallyOpenImageEditorForAspectRatio() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters. 了解更多 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

The automaticallyOpenImageEditorForAspectRatio() method can only be used with a single aspect ratio. If you need to allow multiple aspect ratios, use imageAspectRatio() for validation only, and consider using imageEditor() with imageEditorAspectRatioOptions() to let users choose their preferred ratio.

NOTE

The automaticallyOpenImageEditorForAspectRatio() method is not available when multiple() is enabled.

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

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

To enable automatic cropping with a specific aspect ratio, use the automaticallyCropImagesToAspectRatio() method. If you also have imageAspectRatio() set for validation and want the automatic crop to use the same ratio, you can call automaticallyCropImagesToAspectRatio() without any arguments:

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

When using automatic image cropping, the crop is applied automatically without user interaction. The user cannot choose which part of the image to keep. If you want users to control how their images are cropped, use automaticallyOpenImageEditorForAspectRatio() instead.

修改文件上传区域的外观

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

Customizing the URL used when opening a file

By default, the “open” button links to the same URL that is used to display the file in FilePond. If you need a different URL — for example, a signed URL, a URL on a different domain, or a URL for a derived file such as a PDF thumbnail generated by Spatie Media Library’s image generators — you can use the getOpenableFileUrlUsing() method:

use Filament\Forms\Components\FileUpload;

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

The function receives the stored $file path and must return the URL that should be used when the “open” button is clicked. Returning null falls back to the default 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

Customizing the URL used when downloading a file

By default, the download button links to the same URL that is used to display the file in FilePond. If you need a different URL — for example, a signed URL with a Content-Disposition: attachment header, or a URL to the original file when the preview renders a derived image — you can use the getDownloadableFileUrlUsing() method:

use Filament\Forms\Components\FileUpload;

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

The function receives the stored $file path and must return the URL that should be used when the download button is clicked. Returning null falls back to the default URL.

The getDownloadableFileUrlUsing() 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.

预览文件

默认情况下，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

Many of these validation rules only apply to newly uploaded files. Existing files that were uploaded before the validation rules were added will not be re-validated.

文件类型验证

NOTE

By default, a FileUpload accepts any file type, the same way Laravel’s file validation rule does. On a local or public disk served by a PHP-executing web server, this means a user can upload a .php file and have it executed as code — remote code execution. You should always call acceptedFileTypes() (or image()) with an explicit list of MIME types unless you have a specific reason not to. Doing so also activates Laravel’s built-in block on PHP-family extensions (.php, .phtml, .phar, etc.) via the mimetypes validation rule, rejecting files whose client-supplied filename would otherwise land on disk as executable code.

你可以使用 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.

Image dimension validation

You may restrict the dimensions of uploaded images using the rule() method with Laravel’s 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))

You can combine minimum and maximum constraints:

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

These dimension validation rules only apply to newly uploaded files. Existing files that were uploaded before the validation rules were added will not be re-validated.

Image aspect ratio validation

You may restrict the aspect ratio of uploaded images using the imageAspectRatio() method:

use Filament\Forms\Components\FileUpload;

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

You can allow multiple aspect ratios by passing an array:

use Filament\Forms\Components\FileUpload;

FileUpload::make('banner')
    ->image()
    ->imageAspectRatio(['16:9', '4:3', '1:1'])
As well as allowing a static value, the imageAspectRatio() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters. 了解更多 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.

You can also specify a range of acceptable aspect ratios using 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

These aspect ratio validation rules only apply to newly uploaded files. Existing files that were uploaded before the validation rules were added will not be re-validated.

TIP

If you want to help users meet the aspect ratio requirement rather than just rejecting invalid uploads, consider using automaticallyOpenImageEditorForAspectRatio() alongside imageAspectRatio(). This will automatically open a crop editor when an uploaded image doesn’t match the required ratio. Alternatively, you can use automaticallyCropImagesToAspectRatio() to automatically crop images to the required ratio without user interaction.

文件数验证

使用 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? 💖