复选框列表

简介

复选框列表组件允许从预定义选项列表中选择多个值：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])

TIP

除静态数组外，options() 方法也接受函数以动态计算选项。可将各种工具注入该函数作为参数。

这些选项以 JSON 格式返回。若用 Eloquent 保存，请务必在模型属性上添加 array 转换（cast）：

php

use Illuminate\Database\Eloquent\Model;

class App extends Model
{
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'technologies' => 'array',
        ];
    }

    // ...
}

设置选项描述

可用 descriptions() 方法为每个选项提供可选描述。该方法接受纯文本字符串数组，或 Illuminate\Support\HtmlString / Illuminate\Contracts\Support\Htmlable 实例，从而可在描述中渲染 HTML 甚至 Markdown：

php

use Filament\Forms\Components\CheckboxList;
use Illuminate\Support\HtmlString;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->descriptions([
        'tailwind' => 'A utility-first CSS framework for rapidly building modern websites without ever leaving your HTML.',
        'alpine' => new HtmlString('A rugged, minimal tool for composing behavior <strong>directly in your markup</strong>.'),
        'laravel' => str('A **web application** framework with expressive, elegant syntax.')->inlineMarkdown()->toHtmlString(),
        'livewire' => 'A full-stack framework for Laravel building dynamic interfaces simple, without leaving the comfort of Laravel.',
    ])

TIP

除静态数组外，descriptions() 方法也接受函数以动态计算描述。可将各种工具注入该函数作为参数。

INFO

请确保描述数组中的 key 与选项数组中的 key 相同，以便正确描述对应正确选项。

将选项拆分为多列

可用 columns() 方法将选项拆分为多列：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)

TIP

除静态值外，columns() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

该方法接受与网格的 columns() 方法相同的选项，从而可在各断点响应式自定义列数。

设置网格方向

默认情况下，将复选框排成多列时会按垂直顺序排列。若希望水平排列，可使用 gridDirection(GridDirection::Row) 方法：

php

use Filament\Forms\Components\CheckboxList;
use Filament\Support\Enums\GridDirection;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->columns(2)
    ->gridDirection(GridDirection::Row)

TIP

除静态值外，gridDirection() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

搜索选项

可用 searchable() 方法启用搜索输入，便于在大量选项中查找：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()

也可传入布尔值，控制选项是否可搜索：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable(FeatureFlag::active())

TIP

除静态值外，searchable() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

批量切换复选框

可用 bulkToggleable() 方法允许用户一次切换全部复选框：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->bulkToggleable()

也可传入布尔值，控制复选框是否可批量切换：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->bulkToggleable(FeatureFlag::active())

TIP

除静态值外，bulkToggleable() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

禁用特定选项

可用 disableOptionWhen() 方法禁用特定选项。它接受一个闭包，可在其中判断具有特定 $value 的选项是否应禁用：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'livewire')

TIP

可将各种工具注入该函数作为参数。

若要获取未被禁用的选项（例如用于校验），可使用 getEnabledOptions()：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        'tailwind' => 'Tailwind CSS',
        'alpine' => 'Alpine.js',
        'laravel' => 'Laravel',
        'livewire' => 'Laravel Livewire',
        'heroicons' => 'SVG icons',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'heroicons')
    ->in(fn (CheckboxList $component): array => array_keys($component->getEnabledOptions()))

关于 in() 函数的更多信息，请参阅校验文档。

允许选项标签中使用 HTML

默认情况下，Filament 会转义选项标签中的任何 HTML。若要允许 HTML，可使用 allowHtml() 方法：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml()

DANGER

请确保 HTML 可安全渲染，否则应用将面临 XSS 攻击风险。

也可传入布尔值，控制选项是否允许 HTML：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technology')
    ->options([
        'tailwind' => '<span class="text-blue-500">Tailwind</span>',
        'alpine' => '<span class="text-green-500">Alpine</span>',
        'laravel' => '<span class="text-red-500">Laravel</span>',
        'livewire' => '<span class="text-pink-500">Livewire</span>',
    ])
    ->searchable()
    ->allowHtml(FeatureFlag::active())

TIP

除静态值外，allowHtml() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

与 Eloquent 关系集成

若在 Livewire 组件内构建表单，请确保已设置[表单的模型](/5.x/components/form#setting-a-form-model)。否则 Filament 不知道用哪个模型检索关系。

可用 CheckboxList 的 relationship() 方法指向 BelongsToMany 关系。Filament 会从该关系加载选项，并在提交表单时写回关系的 pivot 表。titleAttribute 是用于为每个选项生成标签的列名：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->relationship(titleAttribute: 'name')

WARNING

将 disabled() 与 relationship() 一起使用时，请确保先调用 disabled() 再调用 relationship()。这样可保证 disabled() 中的 saved() 调用不会在 relationship() 配置之后才应用：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->disabled()
    ->relationship(titleAttribute: 'name')

自定义关系查询

可用 relationship() 方法的 modifyOptionsQueryUsing 参数自定义用于检索选项的数据库查询：

php

use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;

CheckboxList::make('technologies')
    ->relationship(
        titleAttribute: 'name',
        modifyQueryUsing: fn (Builder $query) => $query->withTrashed(),
    )

TIP

modifyQueryUsing 参数可将各种工具注入该函数作为参数。

自定义关系选项标签

若要自定义每个选项的标签（例如更详细，或拼接姓名），可在数据库迁移中使用虚拟列：

php

$table->string('full_name')->virtualAs('concat(first_name, \' \', last_name)');

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('authors')
    ->relationship(titleAttribute: 'full_name')

或者，可用 getOptionLabelFromRecordUsing() 方法将选项的 Eloquent 模型转换为标签：

php

use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

CheckboxList::make('authors')
    ->relationship(
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionLabelFromRecordUsing(fn (Model $record) => "{$record->first_name} {$record->last_name}")

TIP

getOptionLabelFromRecordUsing() 方法可将各种工具注入该函数作为参数。

自定义关系选项描述

若要自定义每个选项的描述，可用 getOptionDescriptionFromRecordUsing() 方法将选项的 Eloquent 模型转换为描述：

php

use Filament\Forms\Components\CheckboxList;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

CheckboxList::make('authors')
    ->relationship(
        modifyQueryUsing: fn (Builder $query) => $query->orderBy('first_name')->orderBy('last_name'),
    )
    ->getOptionDescriptionFromRecordUsing(fn (Model $record) => $record->notes)

TIP

getOptionDescriptionFromRecordUsing() 方法可将各种工具注入该函数作为参数。

向关系保存 pivot 数据

若 pivot 表有额外列，可用 pivotData() 方法指定要写入这些列的数据：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('primaryTechnologies')
    ->relationship(name: 'technologies', titleAttribute: 'name')
    ->pivotData([
        'is_primary' => true,
    ])

TIP

除静态值外，pivotData() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

设置自定义无搜索结果消息

使用可搜索的复选框列表时，可在无搜索结果时显示自定义消息。使用 noSearchResultsMessage() 方法即可：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->noSearchResultsMessage('No technologies found.')

TIP

除静态值外，noSearchResultsMessage() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

设置自定义搜索提示

使用可搜索的复选框列表时，可调整用户尚未输入搜索词时搜索框的占位符。使用 searchPrompt() 方法即可：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchPrompt('Search for a technology')

TIP

除静态值外，searchPrompt() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

调整搜索防抖

默认情况下，用户在可搜索复选框列表中输入时，Filament 会等待 1000 毫秒（1 秒）后再搜索选项；若用户持续输入，也会在每次搜索之间等待 1000 毫秒。可用 searchDebounce() 方法更改：

php

use Filament\Forms\Components\CheckboxList;

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->searchable()
    ->searchDebounce(500)

TIP

除静态值外，searchDebounce() 方法也接受函数以动态计算。可将各种工具注入该函数作为参数。

自定义复选框列表操作对象

该字段使用 action 对象，便于自定义其中的按钮。可将函数传给操作注册方法来自定义这些按钮。函数可访问 $action 对象，用于自定义。可用以下方法自定义操作：

selectAllAction()
deselectAllAction()

以下是自定义操作的示例：

php

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

CheckboxList::make('technologies')
    ->options([
        // ...
    ])
    ->selectAllAction(
        fn (Action $action) => $action->label('Select all technologies'),
    )

TIP

操作注册方法可将各种工具注入该函数作为参数。

复选框列表 ​

简介 ​

设置选项描述 ​

将选项拆分为多列 ​

设置网格方向 ​

搜索选项 ​

批量切换复选框 ​

禁用特定选项 ​

允许选项标签中使用 HTML ​

与 Eloquent 关系集成 ​

自定义关系查询 ​

自定义关系选项标签 ​

自定义关系选项描述 ​

向关系保存 pivot 数据 ​

设置自定义无搜索结果消息 ​

设置自定义搜索提示 ​

调整搜索防抖 ​

自定义复选框列表操作对象 ​