Builder - 表单 - Filament

简介

类似于 Repeater，Builder 组件允许你用重复的表单组件输出 JSON 数组。Repeater 只定义一个表单 Schema，与之不同的是，Builder 允许你定义不同的 Schema 块，你可以使用任何顺序重复。这对于创建更高级的数组结构非常有用。

Builder 主要用于通过预定义块创建网页内容。这可能是营销网站的内容，甚至可能是在线表单中的字段。下面的示例在页面内容中为不同元素定义了多个块。在网站的前端，你可以循环 JSON 中的每个块，并根据自己的意愿对其进行格式化。

use Filament\Forms\Components\Builder;
use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\FileUpload;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\TextInput;

Builder::make('content')
    ->blocks([
        Block::make('heading')
            ->schema([
                TextInput::make('content')
                    ->label('Heading')
                    ->required(),
                Select::make('level')
                    ->options([
                        'h1' => 'Heading 1',
                        'h2' => 'Heading 2',
                        'h3' => 'Heading 3',
                        'h4' => 'Heading 4',
                        'h5' => 'Heading 5',
                        'h6' => 'Heading 6',
                    ])
                    ->required(),
            ])
            ->columns(2),
        Block::make('paragraph')
            ->schema([
                Textarea::make('content')
                    ->label('Paragraph')
                    ->required(),
            ]),
        Block::make('image')
            ->schema([
                FileUpload::make('url')
                    ->label('Image')
                    ->image()
                    ->required(),
                TextInput::make('alt')
                    ->label('Alt text')
                    ->required(),
            ]),
    ])

我们建议你在数据库中使用 JSON 类型存储 Builder 数据。此外，如果使用 Eloquent，请确保对该列进行 array 强制转换(cast)。

如上例所示，区块(Block)在组件的 blocks() 方法中定义。块是 Builder\Block 对象，需要传入一个唯一名称和一个组件 Schema：

use Filament\Forms\Components\Builder;
use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\TextInput;

Builder::make('content')
    ->blocks([
        Block::make('heading')
            ->schema([
                TextInput::make('content')->required(),
                // ...
            ]),
        // ...
    ])

设置区块标签

默认情况下，区块的标签是基于块名自动生成。要重写区块标签，请使用 label() 方法。如果你想使用本地化翻译字符用这种方法自定义标签很有用。

use Filament\Forms\Components\Builder\Block;

Block::make('heading')
    ->label(__('blocks.heading'))

基于内容生成项目标签

使用该 label() 方法，可以为 Builder 项目添加标签。该方法接受一个闭包，闭包以 $state 变量接收项目数据。如果 $state 为空，你应该返回在区块选择器中显示的块标签。否则，请返回用作项目标签的字符串：

use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\TextInput;

Block::make('heading')
    ->schema([
        TextInput::make('content')
            ->live(onBlur: true)
            ->required(),
        // ...
    ])
    ->label(function (?array $state): string {
        if ($state === null) {
            return 'Heading';
        }

        return $state['content'] ?? 'Untitled heading';
    })

如果你想在使用表单时，实时更新项目标签，那么任何 $state 用到的字段都应该是 live() 的。

你可以注入各种 utility 到传入到 label() 的函数中作为参数。

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.
Key	`string`	`$key`	The key for the current block.
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	`array<string, mixed>`	`$state`	The raw unvalidated data for the current block.

Utility	类型	参数	描述
Action	`Filament\Actions\Action`	`$action`	The action object to customize.
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.

#简介

#设置区块标签

#基于内容生成项目标签

#Builder 项目编号

#设置区块图标

#在 Block 头部添加图标

#预览 Block

#交互式区块预览

#添加项目

#设置添加按钮标签

#对齐添加 Action 按钮

#防止用户添加新项目

#删除项目

#防止用户删除项目

#项目重新排序

#防止用户重新排序

#使用按钮重新排序项目

#阻止用户使用拖拽排序

#折叠项目

#Deferring the loading of block schemas

#克隆项目

#自定义块选择器(block picker)

#修改块选择器中的列数

#增加块选择器的宽度

#限制块可被使用的次数

#使用 $get() 访问父级字段值

#Builder 验证

#项目数量验证

#自定义 Builder 项 Action

#使用模态框确认 Builder Action

#将额外的项目 Action 添加到 Builder 中

简介

设置区块标签

基于内容生成项目标签

Builder 项目编号

设置区块图标

在 Block 头部添加图标

预览 Block

交互式区块预览

添加项目

设置添加按钮标签

对齐添加 Action 按钮

防止用户添加新项目

删除项目

防止用户删除项目

项目重新排序

防止用户重新排序

使用按钮重新排序项目

阻止用户使用拖拽排序

折叠项目

Deferring the loading of block schemas

克隆项目

自定义块选择器(block picker)

修改块选择器中的列数

增加块选择器的宽度

限制块可被使用的次数

使用 `$get()` 访问父级字段值

Builder 验证

项目数量验证

自定义 Builder 项 Action

使用模态框确认 Builder Action

将额外的项目 Action 添加到 Builder 中