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)

我们建议你使用 JSON 列将 Repeater 数据存储在数据库中。此外，如果你使用的是 Eloquent，请确保该列具有 array 类型转换。

如上例所示，组件架构可以在组件的 schema() 方法中定义：

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

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

如果你希望使用多个 Schema 块来定义 Repeater，使之可以以任何排列顺序重复，请使用 Builder。

#设置空默认项

Repeater 可以默认创建一些空项目。只有 Schema 加载时没有数据，才会使用默认项。在标准的面板资源中，默认项只在新建页面中使用，而不会在编辑页面中生效。要使用默认项，请将项目数传入到 defaultItems() 方法：

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

#对齐添加按钮

默认情况下，添加按钮居中对齐。你可以使用 addActionAlignment() 方法，传递一个 Alignment 选项(如 Alignment::Start 或 Alignment::End)，调整对其方式：

use Filament\Forms\Components\Repeater;
use Filament\Support\Enums\Alignment;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->addActionAlignment(Alignment::Start)

#阻止用户添加项目

使用 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 是否应该通过按钮进行排序：

use Filament\Forms\Components\Repeater;

Repeater::make('members')
    ->schema([
        // ...
    ])
    ->reorderableWithButtons(FeatureFlag::active())

#阻止通过拖拽重新排序

使用 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()

同时，collapsible() 和 collapsed() 方法也可以接受一个布尔值，用以控制 Repeater 是否可折叠或者是否默认为折叠：

use Filament\Forms\Components\Repeater;

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

#克隆项目

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

use Filament\Forms\Components\Repeater;

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

或者，cloneable() 方法也接受一个布尔值，用以控制该 Repeater 是否应该可复制：

use Filament\Forms\Components\Repeater;

Repeater::make('qualifications')
    ->schema([
        // ...
    ])
    ->cloneable(FeatureFlag::active())

#与 Eloquent 关联集成

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

use Filament\Forms\Components\Repeater;

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

use Filament\Forms\Components\Repeater;

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

#重新排序关联中的项目

默认情况下，Repeater 项目重新排序关联的 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 $incrementing = true;

    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 变量接收当前项目的数据。你可以返回修改过的数据数组，或者用于避免该项被创建的 null：

use Filament\Forms\Components\Repeater;

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

        return $data;
    })

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

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

use Filament\Forms\Components\Repeater;

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

        return $data;
    })

#网格布局

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

use Filament\Forms\Components\Repeater;

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

该方法接收的参数与网格的 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()
            ->live(onBlur: true),
        Select::make('role')
            ->options([
                'member' => 'Member',
                'administrator' => 'Administrator',
                'owner' => 'Owner',
            ])
            ->required(),
    ])
    ->columns(2)
    ->itemLabel(fn (array $state): ?string => $state['name'] ?? null),

#单个字段的简单 Repeater

你可以使用 simple() 方法，使用单个字段来创建 Repeater，最小化设计：

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

Repeater::make('invitations')
    ->simple(
        TextInput::make('email')
            ->email()
            ->required(),
    )

不再使用嵌套数组存储数据，简单 Repeater 使用平面数组值。这意味着，上例的数据结构在像这样：

[
    'invitations' => [
        'dan@filamentphp.com',
        'ryan@filamentphp.com',
    ],
],

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

所有表单组件都可以[使用 $get() 和 $set()]](overview#注入另一个字段的状态) 去访问另一个字段的值。不过，当在 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')。

有一个特例是, 没有参数的 $get()，或者 $get('') 或 $get('./')，总是返回当前 Repeater 项目的全数据数组。

#表格 Repeater

使用 table() 方法，你可以将 Repeater 项目以表格格式展示，该方法接收一个 TableColumn 对象数组。这些对象表示的是表格的列，对应于 Repeater 中 Schema 组件：

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

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

表头标题中显示的标签传入到 TableColumn::make() 方法。如果你想要为列提供一个可访问的标签，但不想显示它，你可以使用 hiddenHeaderLabel() 方法：

use Filament\Forms\Components\Repeater\TableColumn;

TableColumn::make('Name')
    ->hiddenHeaderLabel()

如果你想使用星号将列标记为“必填(required)”，你可以使用 markAsRequired() 方法：

use Filament\Forms\Components\Repeater\TableColumn;

TableColumn::make('Name')
    ->markAsRequired()

使用 wrapHeader() 方法，你可以启用列标题的包装：

use Filament\Forms\Components\Repeater\TableColumn;

TableColumn::make('Name')
    ->wrapHeader()

使用 alignment() 方法，并传入 Alignment 选项，比如 Alignment::Start、Alignment::Center 或者 Alignment::End，你也可以调整列标题的对齐方式：

use Filament\Forms\Components\Repeater\TableColumn;
use Filament\Support\Enums\Alignment;

TableColumn::make('Name')
    ->alignment(Alignment::Start)

使用 width() 方法，并传入一个表示列宽的字符串，你可以为列设置固定宽度。这个值会被直接传入到列标题的 style 属性中：

use Filament\Forms\Components\Repeater\TableColumn;

TableColumn::make('Name')
    ->width('200px')

#Repeater 验证

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

#验证项目数

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

use Filament\Forms\Components\Repeater;

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

#不同状态验证

在许多情况下，你需要确保不同的 Repeater 项目之间有某种唯一性。通用的一些示例如：

• 确保在 Repeater 项目之间一次只能有一个复选框或者切换按钮处于激活状态。
• 确保下拉列表、单选框或者复选框列表或者切换按钮组这些字段中的某个选项一次只能在 Repeater 中被选中一次。

使用 distinct() 方法，可以验证一个字段的状态在 Repeater 内所有的子项中是否是唯一的：

use Filament\Forms\Components\Checkbox;
use Filament\Forms\Components\Repeater;

Repeater::make('answers')
    ->schema([
        // ...
        Checkbox::make('is_correct')
            ->distinct(),
    ])

distinct() 验证的行为取决于字段所处理的数据类型：

• 如果字段返回的是布尔值，比如复选框或切换按钮，验证将确保只有一项的值会是 true。Repeater 中可能有多个字段值为 false。
• 此外，像下拉列表、单选框、复选框列表或切换按钮组这些字段，验证会确保每个选项只能被选择一次。

或者，你也可以传入一个布尔值到 distinct() 方法，用以控制字段是否该为 distinc：

use Filament\Forms\Components\Checkbox;

Checkbox::make('is_correct')
    ->distinct(FeatureFlag::active())

#自动修复非 distinct 状态

如果你想修复非 distinct 状态，可以使用 fixIndistinctState() 方法：

use Filament\Forms\Components\Checkbox;
use Filament\Forms\Components\Repeater;

Repeater::make('answers')
    ->schema([
        // ...
        Checkbox::make('is_correct')
            ->fixIndistinctState(),
    ])

该方法将自动启用字段中的 distinct() 和 live() 方法。

取决于该字段所处理的数据类型，fixIndistinctState() 的行为适配：

• 如果字段返回的是布尔值，比如复选框或切换按钮，并且其中一个字段启用了，Filament 会自动禁用所有其他已启用的字段。
• 此外，像下拉列表、单选框、复选框列表或切换按钮组这些字段，当用户选择一个选项时，Filament 会自动取消选择所有已选该选项的地方。

或者，你也可以传入一个布尔值到 fixIndistinctState() 方法，用以控制该字段是否应该修复非 distinct 状态：

use Filament\Forms\Components\Checkbox;

Checkbox::make('is_correct')
    ->fixIndistinctState(FeatureFlag::active())

#禁用其他项目选择的选项

如果你想在下拉列表、单选框、复选框列表或切换按钮组中禁用已被其他项目选中的选项，可以使用 disableOptionsWhenSelectedInSiblingRepeaterItems() 方法：

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

Repeater::make('members')
    ->schema([
        Select::make('role')
            ->options([
                // ...
            ])
            ->disableOptionsWhenSelectedInSiblingRepeaterItems(),
    ])

该方法将自动启用字段的 distinct() 和 live() 方法。

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

Repeater::make('members')
    ->schema([
        Select::make('role')
            ->options([
                // ...
            ])
            ->disableOptionsWhenSelectedInSiblingRepeaterItems()
            ->disableOptionWhen(fn (string $value): bool => $value === 'super_admin', merge: true),
    ])

#自定义 Repeater 子项 Action

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

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

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

use Filament\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\Actions\Action;
use Filament\Forms\Components\Repeater;

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

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

通过将 Action 对象传入到 extraItemActions() 方法，你可以将新的 Action 按钮添加到每个 Repeater 项目中：

use Filament\Actions\Action;
use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\TextInput;
use Filament\Support\Icons\Heroicon;
use Illuminate\Support\Facades\Mail;

Repeater::make('members')
    ->schema([
        TextInput::make('email')
            ->label('Email address')
            ->email(),
        // ...
    ])
    ->extraItemActions([
        Action::make('sendEmail')
            ->icon(Heroicon::Envelope)
            ->action(function (array $arguments, Repeater $component): void {
                $itemData = $component->getItemState($arguments['item']);

                Mail::to($itemData['email'])
                    ->send(
                        // ...
                    );
            }),
    ])

本例中，$arguments['item'] 提供了当前 Repeater 项目的 ID。你可以在 Repeater 组件中使用 getItemState() 方法验证该 Repeater 项目中的数据。该方法返回该项目已验证的数据。如果数据无效，它会取消该操作并在表单中显示该项目的错误消息。

如果你想获取当前项目的原始数据，而不对其进行验证，你可以使用 $component->getRawItemState($arguments['item'])。

如果你想操作整个 Repeater 的原始数据，比如，添加、删除或修改项目，你可以使用 $component->getState() 获取数据，并 $component->state($state) 对其重新设置：

use Illuminate\Support\Str;

// Get the raw data for the entire repeater
$state = $component->getState();

// Add an item, with a random UUID as the key
$state[Str::uuid()] = [
    'email' => auth()->user()->email,
];

// Set the new data for the repeater
$component->state($state);

Still need help? Join our Discord community or open a GitHub discussion