版本：4.x

Builder

简介

类似于 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() 的。

You can inject various utilities into the function passed to label() as parameters.

Utility	Type	Parameter	Description
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 <code>create</code>, <code>edit</code>, or <code>view</code>.
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	Type	Parameter	Description
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 <code>create</code>, <code>edit</code>, or <code>view</code>.
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​

Interactive block previews​

添加项目​

设置添加按钮标签​

对齐添加 Action 按钮​

防止用户添加新项目​

删除项目​

防止用户删除项目​

项目重新排序​

防止用户重新排序​

使用按钮重新排序项目​

阻止用户使用拖拽排序​

折叠项目​

克隆项目​

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

修改块选择器中的列数​

增加块选择器的宽度​

限制块可被使用的次数​

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

Builder 验证​

项目数量验证​

自定义 Builder 项 Action​

使用模态框确认 Builder Action​

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

简介

设置块标签

基于内容生成项目标签

Builder 项目编号

设置块图标

在 Block 头部添加图标

预览 Block

Interactive block previews

添加项目

设置添加按钮标签

对齐添加 Action 按钮

防止用户添加新项目

删除项目

防止用户删除项目

项目重新排序

防止用户重新排序

使用按钮重新排序项目

阻止用户使用拖拽排序

折叠项目

克隆项目

自定义块选择器(block picker)

修改块选择器中的列数

增加块选择器的宽度

限制块可被使用的次数

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

Builder 验证

项目数量验证

自定义 Builder 项 Action

使用模态框确认 Builder Action

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