跳到主要内容
版本：3.0

Repeater

概述​

Repeater 组件允许你输出重复表单组件的 JSON 数组：

use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\Select;
use Filament\Forms\Components\TextInput;

Repeater::make('members')
    ->schema([
        TextInput::make('name')->required(),
        Select::make('role')
            ->options([
                'member' => 'Member',
                'administrator' => 'Administrator',
                'owner' => 'Owner',
            ])
            ->required(),
    ])
    ->columns(2)
Repeater

建议将 repeater 数据存储在数据库的 JSON 字段中。此外，如果你使用了 Eloquent，请确保该对该字段进行 array cast。

上例可以明显看出，组件 Schema 在组件的 schema() 方法中定义:

use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\TextInput;

Repeater::make('members')
    ->schema([
        TextInput::make('name')->required(),
        // ...
    ])

如果你想要使用可以以任何顺序重复的多个 Schema 块来定义 Repeater，请使用 Builder。

设置空默认项​

使用 defaultItems() 方法，Repeater 可以创建特定数量的默认项：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->defaultItems(3)

请注意，默认项只会表单中没有加载已有数据时创建。在面板资源内，它只会在创建页面生效，因为编辑页面始终回从模型中填充数据。

添加项目​

Repeater 下面有一个 Action 按钮，用来添加新项目。

设置添加按钮标签​

使用 addActionLabel() 方法，你可以设置添加按钮上显示的标签文本：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->addActionLabel('Add member')

阻止用户添加项目​

使用 addable(false) 方法，你可以阻止用户添加项目到 Repeater：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->addable(false)

删除项目​

每个项目上都有个 Action 按钮，用以删除项目。

防止用户删除项目​

使用 deletable(false) 方法，你可以阻止用户删除 Repeater 中的项目：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->deletable(false)

项目重新排序​

每个项目上都有一个按钮，用于允许用户拖拽来对项目进行重新排序。

防止用户重新排序​

使用 reorderable(false) 方法，你可以阻止用户在 Repeater 中对项目进行重新排序：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->reorderable(false)

使用按钮重新排列项目​

使用 reorderableWithButtons() 方法，你可以启用通过按钮重新排序，将项目上下移动:

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->reorderableWithButtons()
Repeater that is reorderable with buttons

阻止使用拖拽进行重新排序​

使用 reorderableWithDragAndDrop(false) 方法，可以阻止项目通过拖拽进行排序：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->reorderableWithDragAndDrop(false)

可折叠的项目​

使用 collapsible() 方法，可以将 Repeater 设为可折叠的，使其在长表单中隐藏内容：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->schema([
        // ...
    ])
    ->collapsible()

你可以将所有项目设置成默认折叠：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->schema([
        // ...
    ])
    ->collapsed()
Collapsed repeater

克隆项目​

使用 cloneable() 方法，可以将 Repeater 项目设为可复制的。

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->schema([
        // ...
    ])
    ->cloneable()
Cloneable repeater

集成 Eloquent 关联​

如果你在 Livewire 组件内创建表单，请确保设置好表单模型。否则，Filament 不知道应该使用哪个模型去检索关联。

你可以使用 Repeater 上的 relationship() 方法去配置 HasMany 关联。Filament 将从关联中加载项目数据，并在表单提交后将其保存回关联。如果没有将自定义关联名传入到 relationship()，Filament 将回使用字段名作为关联名：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])

在关联中重排项目​

默认情况下，Repeater 项目 重新排序是禁用的。这是因为关联模型需要有一个 sort 字段用来存储关联记录的排序。要启用重新排序功能，你需要使用 orderColumn() 方法，传入关联模型的用于排序的字段名：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])
    ->orderColumn('sort')

如果你使用了诸如 spatie/eloquent-sortable 这样使用 order_column 作为排序字段的包，你可以将其传入到 orderColumn() 中：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])
    ->orderColumn('order_column')

集成 BelongsToMany Eloquent 关联​

有一种常见的误解是，在 Repeater 中使用 BelongsToMany 关联与使用 HasMany 关联一样简单。事实并非如此，BelongsToMany 关联需要中间表来存储关联数据。Repeater 将数据保存到关联模型，而非中间表。因此，如果你想将每个 Repeater 项目映射到中间表行数据，你必须使用 HasMany 关联中间模型，才可以在 Repeater 中使用 BelongsToMany 关联。

假设你有一个新建 Order 模型的表单。每个订单属于多个 Product 模型，并且每个产品也属于多个订单。你使用了 order_product 中间表来存储关联数据。你不应该在 Repeater 中使用 products 关联，而应该在 Order 模型上创建一个 orderProducts 关联，并在 Repeater 上使用：

use Illuminate\Database\Eloquent\Relations\HasMany;

public function orderProducts(): HasMany
{
    return $this->hasMany(OrderProduct::class);
}

如果你没有 OrderProduct 中间模型，你应该创建一个，将其反转关联到 Order 及 Product 上：

use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\Pivot;

class OrderProduct extends Pivot
{
    public function order(): BelongsTo
    {
        return $this->belongsTo(Order::class);
    }
    
    public function product(): BelongsTo
    {
        return $this->belongsTo(Product::class);
    }
}

现在，你可以在 Repeater 上使用 orderProducts 关联，并将数据保存到 order_product 中间表中：

use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\Select;

Repeater::make('orderProducts')
    ->relationship()
    ->schema([
        Select::make('product_id')
            ->relationship('product', 'name')
            ->required(),
        // ...
    ])

填充字段前更改关联项目数据​

使用 mutateRelationshipDataBeforeFillUsing() 方法，你可以在数据填充到该字段之前修改关联项目的数据。该方法接收一个闭包，闭包使用 $data 变量接收当前项目的数据。你必须返回修改过的数据数组：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])
    ->mutateRelationshipDataBeforeFillUsing(function (array $data): array {
        $data['user_id'] = auth()->id();

        return $data;
    })

新建前修改关联项目数据​

使用 mutateRelationshipDataBeforeCreateUsing() 方法，你可以在数据库中新建记录之前修改关联项数据。该方法接收一个闭包，闭包使用 $data 变量接收当前项目的数据。你必须返回修改过的数据数组：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])
    ->mutateRelationshipDataBeforeCreateUsing(fn (array $data): array {
        $data['user_id'] = auth()->id();

        return $data;
    })

保存前修改关联项目数据​

使用 mutateRelationshipDataBeforeSaveUsing() 方法，你可以在数据保存到数据库之前修改已有关联项目的数据。该方法接收一个闭包，闭包使用 $data 变量接收当前项目的数据。你必须返回修改过的数据数组：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->relationship()
    ->schema([
        // ...
    ])
    ->mutateRelationshipDataBeforeSaveUsing(fn (array $data): array {
        $data['user_id'] = auth()->id();

        return $data;
    })

网格布局​

使用 grid() 方法，你可以将 Repeater 项目组织到网格列中：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->schema([
        // ...
    ])
    ->grid(2)
Repeater with a 2 column grid of items

该方法接收的参数与 grid 的 columns() 相同。它允许你在不同的临界点中响应式地自定义网格列数。

基于内容为 Repeater 项目添加标签​

使用 itemLabel() 方法，你可以为 Repeater 项目添加标签。该方法接收一个闭包，闭包使用 $state 变量接收当前项目的数据。你必须返回字符串用作项目标签：

use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Select;

Repeater::make('members')
    ->schema([
        TextInput::make('name')
            ->required()
            ->blur(),
        Select::make('role')
            ->options([
                'member' => 'Member',
                'administrator' => 'Administrator',
                'owner' => 'Owner',
            ])
            ->required(),
    ])
    ->columns(2)
    ->itemLabel(fn (array $state): ?string => $state['name'] ?? null),

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

Repeater with item labels

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

所有表单组件都可以使用 $get() 和 $set() 去访问另一个字段的值。不过，当在 Repeater 的 Schema 中使用时，你可能回遇到非预期的行为。

这是因为 $get() 和 $set() 默认作用于当前的 Repeater 项目。这意味着，你可以在该 Repeater 内和其他字段交互，而不必知晓当前表单组件属于哪个 Repeater 项目。

后果是，当你无法与 Repeater 之外的字段进行交互时，你可能会感到疑惑。我们使用 ../ 语法来解决这个问题 —— $get('../../parent_field_name')。

假设你的表单数据结构如下：

[
    'client_id' => 1,

    'repeater' => [
        'item1' => [
            'service_id' => 2,
        ],
    ],
]

你要在 Repeater 项目中检索 client_id。

$get() 是相对当前 Repeater 项目，因此 $get('client_id') 查找的是 $get('repeater.item1.client_id')。

你可以使用 ../ 回到该数据结构的上一级，因此 $get('../client_id') 相当于 $get('repeater.client_id')，$get('../../client_id') 相当于 $get('client_id')。

Repeater 验证​

除了验证页面中列出的所有规则，还有一些其他专用于 Repeater 的验证规则。

验证项目数量​

设置 minItems() 和 maxItems() 方法，你可以验证 Repeater 中项目的最小和最大数量：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->minItems(2)
    ->maxItems(5)

自定义 Repeater Action 对象​

该字段使用 Action 对象，在其中对按钮进行自定义。通过传递一个函数到 action 注册方法中，可以自定义这些按钮。该函数可以访问 $action 对象，用于自定义。下面是一些可以用于自定义 action 的方法：

  • addAction()
  • cloneAction()
  • collapseAction()
  • collapseAllAction()
  • deleteAction()
  • expandAction()
  • expandAllAction()
  • moveDownAction()
  • moveUpAction()
  • reorderAction()

下面是一个自定义 action 的示例：

use Filament\Forms\Components\Actions\Action;
use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->collapseAllAction(
        fn (Action $action) => $action->label('Collapse all members'),
    )

使用模态框确认 Repeater Action​

在 action 对象中使用 requiresConfirmation() 方法，你可以使用模态框确认 action。你可以使用所有模态框自定义方法来修改其内容和行为：

use Filament\Forms\Components\Actions\Action;
use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->deleteAction(
        fn (Action $action) => $action->requiresConfirmation(),
    )

collapseAction()、collapseAllAction()、expandAction()、expandAllAction() 和 reorderAction() 方法不支持确认模态框，因为点击这些按钮不会发起要求显示模态框的网络请求。