Toggle buttons

#简介

Toogle Buttons 提供了从一个预定义选项列表中选择一个或多个值的按钮组：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])

除了允许静态值之外，options() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#修改选项按钮的颜色

使用 colors() 方法，你可以修改选项按钮的[颜色]。数组中的每个键应该对应于选项值：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])
    ->colors([
        'draft' => 'info',
        'scheduled' => 'warning',
        'published' => 'success',
    ])

如果你的选项使用了枚举，你可以使用 HasColor 接口来定义颜色。

除了允许静态值之外，colors() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#添加图标到选项按钮

使用 icons() 方法，你可以添加图标到选项按钮中。数组的每个键对应于选项值，并且选项值应该是有效的图标：

use Filament\Forms\Components\ToggleButtons;
use Filament\Support\Icons\Heroicon;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published'
    ])
    ->icons([
        'draft' => Heroicon::OutlinedPencil,
        'scheduled' => Heroicon::OutlinedClock,
        'published' => Heroicon::OutlinedCheckCircle,
    ])

除了允许静态值之外，icons() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

如果你的选项使用了枚举值，你可以使用 HasIcon 接口来定义图标。

如果你想只展示图标，你可以使用 hiddenButtonLabels() 来隐藏选项标签。

#Adding tooltips to option buttons

You can add different tooltips to each option button using the tooltips() method.

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->tooltips([
        'draft' => 'Set as a draft before publishing.',
        'scheduled' => 'Schedule publishing on a specific date.',
        'published' => 'Publish now',
    ])

As well as allowing a static array, the tooltips() method also accepts a function to dynamically calculate it. You can inject various utilities into the function as parameters.

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#布尔值选项

如果你想要使用简单的布尔值 Toggle 按钮组，该按钮组使用 “Yes” 和 “No” 选项，你可以使用 boolean() 方法：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()

这些选项将自动设置颜色和图标，不过你可以通过 colors() 和 icons() 按钮重写。

要自定义 “Yes” 标签，你可以在 boolean() 方法中使用 trueLabel 参数：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean(trueLabel: 'Absolutely!')

要自定义 “No” 的标签，你可以在 boolean() 方法中使用 falseLabel 参数：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean(falseLabel: 'Not at all!')

#选项行内显示

使用 inline() 方法，你可以行内显示按钮：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline()

或者，你也可以传入一个布尔值，以控制按钮是否应该以行内方式布局：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->inline(FeatureFlag::active())

除了允许静态值之外，inline() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#选项按钮分组

如果你想将选项按钮分组到一起，使之更为紧凑，请使用 grouped() 方法。这也使它们呈水平排列：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->grouped()

或者，你也可以传入一个布尔值，以控制按钮是否应该分组：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('feedback')
    ->label('Like this post?')
    ->boolean()
    ->grouped(FeatureFlag::active())

除了允许静态值之外，grouped() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#多选

ToggleButtons 组件的 multiple() 方法允许你从选项列表中选择多个值：

use Filament\Forms\Components\ToggleButtons;

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

这些渲染以 JSON 格式返回。如果你使用 Eloquent 保存这些数据，请确保添加 array [强制转换(cast)]到模型属性中：

use Illuminate\Database\Eloquent\Model;

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

    // ...
}

或者，你也可以传入一个布尔值，以控制按钮是否允许多选：

use Filament\Forms\Components\ToggleButtons;

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

除了允许静态值之外，multiple() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#将选项分割成多列

使用 columns() 方法，你可以将选项分割成多列：

use Filament\Forms\Components\ToggleButtons;

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

除了允许静态值之外，columns() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

该方法接收与网格的 columns() 方法同样的选项。这允许你在不同临界点响应式地自定义列数。

#设置网格方向

默认情况下，当你将按钮排列到列中时，按钮会以垂直方式按顺序排列。如果你想水平排列，请使用 gridDirection(GridDirection::Row) 方法：

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

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

除了允许静态值之外，gridDirection() 方法也接受函数以动态计算其值。你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

#禁用指定选项

使用 disableOptionWhen 你可以禁用指定选项。它接收一个闭包，该闭包用于检测有指定 $value 值的选项是否该被禁用：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')

你可以将各种 Utility 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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.
Option label	string | Illuminate\Contracts\Support\Htmlable	$label	The label of the option to disable.
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 create, edit, or view.
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.
Option value	mixed	$value	The value of the option to disable.

如果你想要检索未被禁用的选项，比如，用于验证，你可以使用 getEnabledOptions() 方法：

use Filament\Forms\Components\ToggleButtons;

ToggleButtons::make('status')
    ->options([
        'draft' => 'Draft',
        'scheduled' => 'Scheduled',
        'published' => 'Published',
    ])
    ->disableOptionWhen(fn (string $value): bool => $value === 'published')
    ->in(fn (ToggleButtons $component): array => array_keys($component->getEnabledOptions()))

更多关于 in() 函数的信息，请查看验证文档。

Edit on GitHub

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