Filament ToggleButtons 字段完整指南：选项按钮组的配置、样式与数据绑定

Filament ToggleButtons 字段完整指南：选项按钮组的配置、样式与数据绑定

发布时间：2026/9/10 8:30:31
Filament ToggleButtons 字段完整指南：选项按钮组的配置、样式与数据绑定 Filament ToggleButtons 字段完整指南选项按钮组的配置、样式与数据绑定【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentToggleButtons选项按钮组是 Filament 表单包中一种非常直观的字段组件它把一组预定义选项渲染为按钮用户只需点击即可完成单选或多选常用于状态切换、喜好反馈、技术栈勾选等场景。本指南以 packages/forms/docs/18-toggle-buttons.md 为核心骨架结合ToggleButtons组件源码与测试用例系统讲解它的全部配置方法从基础options()、颜色/图标/工具提示定制到布尔模式、多选模式、内联/分组布局、多列网格与选项禁用帮助你直接在 Filament 4.x 项目中落地这套交互方案。组件简介与基本用法ToggleButtons位于Filament\Forms\Components命名空间与 TextInput、Select 等一样是一个标准表单字段可以直接放进任意 schema表单、资源页、操作弹窗、表格筛选器等。它适合在选项数量不多、且希望用户“一眼看清所有可能取值”的场景使用。最基本的使用方式是配合options()传入一个键值对数组键是存储值值是按钮上显示的标签use Filament\Forms\Components\ToggleButtons; ToggleButtons::make(status) -options([ draft Draft, scheduled Scheduled, published Published ])动态选项options()不仅接受静态数组还接受一个闭包函数运行时由 Filament 计算得出例如根据当前用户权限、模型数据动态生成。闭包中可以注入表单字段工具类参数如$get、$state、$record等这与 字段工具注入机制 一致。渲染原理源码视角从 ToggleButtons.php 源码 可以看到该组件实现了HasEmbeddedView接口通过toEmbeddedHtml()直接输出内嵌 HTML每个选项会被渲染为一个隐藏的input单选模式下typeradio多选模式下typecheckbox加上一个按钮样式的label。容器根据模式设置role属性单选roleradiogroup多选rolegroup。同时整个字段通过aria-labelledby与字段标签关联保证屏幕阅读器能够正确理解按钮组的语义这也说明组件在无障碍a11y上做了原生支持。定制选项按钮的颜色使用colors()方法可以为每个选项单独指定按钮颜色数组的键必须与options()中的选项值一一对应use Filament\Forms\Components\ToggleButtons; ToggleButtons::make(status) -options([ draft Draft, scheduled Scheduled, published Published ]) -colors([ draft info, scheduled warning, published success, ])在 HasColors trait 源码 中getColor($value)会按选项值从getColors()结果里取色若某个选项未指定颜色渲染时回退为primary见 ToggleButtons.php。如果options()使用 PHP 枚举则不必再手写colors()——只要让枚举实现Filament\Support\Contracts\HasColor接口并定义getColor()方法组件会自动读取每个 case 的颜色见 HasColors 中针对枚举的回退逻辑。这也适用于文档中提到的HasColor接口与枚举颜色 所在的 09-advanced/03-enums.md。与options()相同colors()也接受闭包动态计算。为选项按钮添加图标icons()方法可以为每个选项按钮添加图标键对应选项值值可以是任何有效的 Filament 图标。在 Filament 4.x 中推荐使用Filament\Support\Icons\Heroicon枚举引用 Heroicons 图标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, ])与颜色类似如果选项来自实现了HasIcon接口的枚举icons()也可以省略组件会自动从枚举读取图标。渲染时图标位于按钮标签之前见 toEmbeddedHtml 源码实现“图标 文字”的按钮形态。只显示图标、隐藏文字如果只想显示图标而不显示文字标签使用hiddenButtonLabels()ToggleButtons::make(status) -options([/* ... */]) -icons([/* ... */]) -hiddenButtonLabels()该方法也支持传入布尔值或闭包。隐藏标签后组件会自动为按钮生成aria-label取自选项标签的纯文本源码见 ToggleButtons.php保证纯图标按钮对屏幕阅读器仍然可读。为每个选项添加工具提示Tooltiptooltips()方法可以为不同选项配置不同的悬浮提示文本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, ])从源码看工具提示通过x-tooltipAlpine 指令渲染且支持富文本如果传入的值实现了Htmlable例如Illuminate\Support\HtmlString渲染时会输出allowHTML: true允许提示内包含 HTML普通字符串则输出allowHTML: false见 ToggleButtons.php。这一行为在 ToggleButtonsTest.php 中有专门的测试断言覆盖。布尔模式一键生成“是/否”按钮组对于只有两个互斥选项的简单场景可以直接调用boolean()方法组件会自动生成 “Yes / No” 两个按钮并自动配置好颜色与图标Yes 为success 对勾图标No 为danger 叉号图标use Filament\Forms\Components\ToggleButtons; ToggleButtons::make(feedback) -label(Like this post?) -boolean()从 boolean() 源码 可以看到它实际做的事以1/0为键设置选项标签默认取语言包中的翻译英文为 “Yes”/“No”多语言包见 packages/forms/resources/lang/en/components.php 以及其他语言包对应位置自动配置success/danger颜色与对勾/叉号图标挂载BooleanStateCast以整数存储的布尔状态转换器将布尔值转为1/0存储、读取时再转回布尔。因此布尔模式下boolean()自动设置的颜色和图标也可以通过后续的colors()或icons()覆盖。测试用例 ToggleButtonsTest.php 验证了默认颜色与图标确实被设置。自定义 Yes / No 标签通过命名参数trueLabel和falseLabel可以分别定制两个按钮的文字ToggleButtons::make(feedback) -label(Like this post?) -boolean(trueLabel: Absolutely!)ToggleButtons::make(feedback) -label(Like this post?) -boolean(falseLabel: Not at all!)注意boolean()模式下字段的存储值为1/0整数而不是true/false。测试 converts boolean default state to int 验证了default(true)会被转换为1、default(false)转换为0而BooleanStateCast见 schemas 的 BooleanStateCast 源码会在get()时把整数还原为布尔值。这意味着若模型属性是布尔类型或使用 Eloquent 布尔 cast无需额外处理即可正确读写。让按钮内联排列inline()默认情况下非分组模式的选项按钮按网格纵向堆叠。调用inline()可以让所有按钮在同一行内并排显示ToggleButtons::make(feedback) -label(Like this post?) -boolean() -inline()也可以传入布尔值或闭包来控制是否内联ToggleButtons::make(feedback) -label(Like this post?) -boolean() -inline(FeatureFlag::active())从渲染源码看inline()生效时组件会给容器追加fi-inline类并跳过网格布局见 ToggleButtons.php。isInline()默认返回false相关断言在 ToggleButtonsTest.php。分组按钮grouped()如果希望按钮紧凑地连成一组看起来像一组粘连的按钮同时天然水平排列使用grouped()ToggleButtons::make(feedback) -label(Like this post?) -boolean() -grouped()同样支持布尔值或闭包控制ToggleButtons::make(feedback) -label(Like this post?) -boolean() -grouped(FeatureFlag::active())grouped()模式下组件会切换为专用的分组视图filament-forms::components.toggle-buttons.grouped常量ToggleButtons::GROUPED_VIEW见 ToggleButtons.php按钮容器使用fi-btn-group类渲染成按钮组样式。多选模式multiple()默认是单选。调用multiple()后用户可以同时选择多个选项此时底层 input 变为typecheckbox容器role变为group见 ToggleButtons.phpuse Filament\Forms\Components\ToggleButtons; ToggleButtons::make(technologies) -multiple() -options([ tailwind Tailwind CSS, alpine Alpine.js, laravel Laravel, livewire Laravel Livewire, ])同样支持布尔值或闭包控制多选开关ToggleButtons::make(technologies) -multiple(FeatureFlag::active()) -options([ tailwind Tailwind CSS, alpine Alpine.js, laravel Laravel, livewire Laravel Livewire, ])多选结果的存储与模型 Cast多选模式下选中的值以 JSON 数组形式返回。若使用 Eloquent 模型保存这些值需要在模型上为对应属性添加arraycastuse Illuminate\Database\Eloquent\Model; class App extends Model { /** * return arraystring, string */ protected function casts(): array { return [ technologies array, ]; } // ... }从 getDefaultStateCasts() 源码 可以看到组件内部针对多选/单选自动应用了不同的状态转换器多选使用OptionsArrayStateCast保证状态始终是数组单选使用可空的OptionStateCast若绑定了枚举则分别使用EnumArrayStateCast/EnumStateCast。这也是为什么多选模式下状态以数组形式与表单和模型交互。自动校验测试 automatically validates multiple options 表明多选模式下每个选中的值都会被单独校验传入未定义的选项值会触发in校验错误。将选项拆分为多列columns() 与网格方向当选项较多时可以用columns()把按钮排列到多列网格中用法与 grid 布局系统 的columns()一致支持传入列数或响应式断点配置ToggleButtons::make(technologies) -options([ // ... ]) -columns(2)该方法同样接受闭包动态计算。设置网格方向gridDirection()默认多列时按钮按列方向垂直依次排列。如果需要横向按行排列使用gridDirection(GridDirection::Row)use Filament\Forms\Components\ToggleButtons; use Filament\Support\Enums\GridDirection; ToggleButtons::make(technologies) -options([ // ... ]) -columns(2) -gridDirection(GridDirection::Row)GridDirection是定义在 packages/support/src/Enums/GridDirection.php 的字符串枚举包含Rowrow和Columncolumn两个 case默认值为Column。HasGridDirectiontrait源码负责解析该配置并允许传入字符串形式的值。禁用特定选项disableOptionWhen()disableOptionWhen()接受一个闭包根据选项值$value和标签$label判断该选项是否应被禁用use Filament\Forms\Components\ToggleButtons; ToggleButtons::make(status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -disableOptionWhen(fn (string $value): bool $value published)闭包可注入的参数包括参数类型说明$valuemixed被判断是否禁用的选项值$labelstring \| Illuminate\Contracts\Support\Htmlable该选项的标签该能力来自 CanDisableOptions traitdisableOptionWhen()支持传入单个回调或使用merge: true追加多个回调渲染时每个选项都会调用isOptionDisabled($value, $label)判断见 ToggleButtons.php。被禁用的选项 input 会加上disabled属性按钮获得fi-disabled样式类。配合校验getEnabledOptions()禁用选项后如果希望校验规则只接受未禁用的值可以使用getEnabledOptions()取出所有未被禁用的选项再配合in()校验规则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()))实际上这一自动行为在组件内部已经内置getInValidationRuleValues()会优先使用自定义的in()取值否则自动返回getEnabledOptions()的键见 ToggleButtons.php。测试 returns only enabled option keys from getInValidationRuleValues() 验证了禁用archived后合法取值只剩[active, inactive]。关于in()校验规则的更多用法可参考 表单校验文档。综合实战示例把以上能力组合起来一个完整的文章发布表单字段可以这样写use Filament\Forms\Components\ToggleButtons; use Filament\Support\Enums\GridDirection; use Filament\Support\Icons\Heroicon; ToggleButtons::make(status) -label(Publication status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -colors([ draft info, scheduled warning, published success, ]) -icons([ draft Heroicon::OutlinedPencil, scheduled Heroicon::OutlinedClock, published Heroicon::OutlinedCheckCircle, ]) -tooltips([ draft Save as a draft for later., scheduled Publish automatically on a future date., published Make visible to everyone now., ]) -disableOptionWhen(fn (string $value): bool $value published ! auth()-user()-can(publish)) -columns(3) -gridDirection(GridDirection::Row) -default(draft) -required()要点回顾单选/多选由multiple()决定多选记得给模型属性加arraycast布尔场景优先用boolean()可自定义trueLabel/falseLabel存储值为1/0布局三兄弟inline()单行并排、grouped()紧凑按钮组、columns()gridDirection()多列网格视觉三件套colors()、icons()、tooltips()枚举选项可借助HasColor/HasIcon接口免配置禁用选项用disableOptionWhen()校验会自动排除已禁用选项。测试与源码索引想深入了解该组件的内部行为可以阅读以下仓库文件组件源码packages/forms/src/Components/ToggleButtons.php含boolean()、inline()、grouped()、multiple()、hiddenButtonLabels()及内嵌 HTML 渲染逻辑选项禁用 traitpackages/forms/src/Components/Concerns/CanDisableOptions.php颜色 traitpackages/forms/src/Components/Concerns/HasColors.php网格方向枚举packages/support/src/Enums/GridDirection.php布尔状态转换packages/schemas/src/Components/StateCasts/BooleanStateCast.php测试用例tests/src/Forms/Components/ToggleButtonsTest.php覆盖渲染、状态读写、布尔/多选模式、布局属性、禁用选项与校验、工具提示allowHTML等场景【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考