跳到主要内容
版本: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 中间模型,你应该创建一个,将其反转关联到 OrderProduct 上:

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

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

基于内容为 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() 方法不支持确认模态框,因为点击这些按钮不会发起要求显示模态框的网络请求。