Filament Radio 单选框组件完全指南选项、描述、禁用与布尔模式的源码级解析【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 表单包packages/forms中的Radio组件用于渲染一组互斥的单选框radio button group供用户从预定义选项中选取唯一值。本文以官方文档 07-radio.md 为主线结合 Radio.php 及其底层 Trait 与测试用例系统讲解选项定义、选项描述、内联排列、按选项禁用、布尔快捷模式等全部能力并深入其渲染与状态转换实现帮助你在 Laravel Livewire 的 Filament 表单中熟练驾驭该组件。组件基础定义选项并绑定状态Radio组件通过make()指定状态字段名再以options()方法传入一个「值 标签」的关联数组use Filament\Forms\Components\Radio; Radio::make(status) -options([ draft Draft, scheduled Scheduled, published Published, ])options()不仅支持静态数组也支持闭包动态计算并可在闭包中注入表单字段相关的各种工具Utility Injection如当前$record、$state、$get、$livewire等。从源码看options()定义于 Concerns/HasOptions.php其底层签名接受array | Arrayable | string | Closure | null五种形态并有两个值得注意的细节枚举类支持若传入的字符串是 PHP 枚举类名options()会自动调用enum()而在getOptions()中HasOptions.php如果枚举实现了Filament\Support\Contracts\HasLabel接口会用getLabel()作为标签否则以枚举name作为标签。标签支持嵌套数组options的类型注解为arraystring | arraystring即每个选项的标签也可以是数组从而支持分组渲染结构。Radio在渲染时会为容器添加roleradiogroup与aria-labelledby保证无障碍语义见 Radio.php 中的toEmbeddedHtml()。为选项添加描述文字当选项较多或含义需要补充说明时可使用descriptions()为每个选项追加一段辅助描述文字use Filament\Forms\Components\Radio; Radio::make(status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -descriptions([ draft Is not visible., scheduled Will be visible., published Is visible., ])务必保证descriptions()数组的key与options()数组的key一一对应描述才会正确匹配到对应选项。descriptions()同样支持闭包动态计算。其实现位于 Concerns/HasDescriptions.php描述数组的类型为arraystring | Htmlable | Arrayable | Closure描述值可以是纯文本或Htmlable对象结果会被缓存cachedDescriptions同一生命周期内多次getDescriptions()不会重复求值当未显式提供描述、但绑定了枚举且枚举实现了Filament\Support\Contracts\HasDescription接口时getDescriptions()会自动从枚举的getDescription()生成描述实现「枚举即描述源」的约定。测试 RadioTest.php 验证了getDescription(low)、hasDescription(missing)等检索行为。内联排列选项默认情况下各选项纵向堆叠显示。调用inline()可将选项横向排列成一行use Filament\Forms\Components\Radio; Radio::make(feedback) -label(Like this post?) -boolean() -inline()也可以传入布尔值或闭包动态控制是否内联Radio::make(feedback) -label(Like this post?) -boolean() -inline(FeatureFlag::active())从源码看Radio.phpinline()的完整签名为inline(bool | Closure $condition true)内部保存到$isInline属性isInline()会通过evaluate()求值闭包。渲染时非内联模式下容器会应用网格布局grid($this-getColumns(), $gridDirection)支持通过columns()控制每行选项数量内联模式下为容器追加fi-inlineCSS 类见 Radio.php。测试 RadioTest.php 验证了默认isInline()为false、调用inline()后为trueL212-L225 进一步验证闭包内联与inline(false)撤销内联均可用。禁用特定选项与校验联动使用disableOptionWhen()禁用指定选项disableOptionWhen()接受一个闭包闭包内检查某个选项的$value是否需要被禁用use Filament\Forms\Components\Radio; Radio::make(status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -disableOptionWhen(fn (string $value): bool $value published)闭包可注入两个参数参数类型说明$valuemixed当前待判断选项的值$labelstring \| Illuminate\Contracts\Support\Htmlable当前待判断选项的标签实现位于 Concerns/CanDisableOptions.php其完整签名为disableOptionWhen(bool | Closure | null $callback, bool $merge false)默认$merge false会覆盖此前的禁用规则传入$merge true时可追加多条禁用规则isOptionDisabled[] $callbackisOptionDisabled()逐条evaluate()所有规则只要有一条命中即视为禁用。渲染时Radio.php被禁用的选项会生成带disabled属性的原生input[typeradio]。获取未禁用的选项做校验getEnabledOptions()禁用选项只影响交互并不自动拦截提交的非法值。若要在校验层同步排除已禁用选项可结合getEnabledOptions()与in()校验规则use Filament\Forms\Components\Radio; Radio::make(status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -disableOptionWhen(fn (string $value): bool $value published) -in(fn (Radio $component): array array_keys($component-getEnabledOptions()))getEnabledOptions()CanDisableOptions.php会过滤掉所有被禁用规则命中的选项返回[值 标签]数组测试 RadioTest.php 验证了禁用archived后仅返回active与inactive。实际上Radio组件对选项校验做了更强的自动化默认状态无需显式调用in()。Radio重写了getInValidationRuleValues()Radio.php当没有手动指定校验值时会自动以「未禁用选项的键集合」作为in校验白名单。测试 RadioTest.php 与 L272-L284 均验证提交被禁用选项值会触发in校验错误而提交合法值或空值null可通过校验。布尔单选框boolean()快捷模式如果只是需要一个简单的「是/否」单选组boolean()可以直接生成带 Yes / No 两个选项的单选框use Filament\Forms\Components\Radio; Radio::make(feedback) -label(Like this post?) -boolean()可通过命名参数自定义两个选项的标签Radio::make(feedback) -label(Like this post?) -boolean(trueLabel: Absolutely!) Radio::make(feedback) -label(Like this post?) -boolean(falseLabel: Not at all!)boolean()的实现非常巧妙Radio.php自动把选项设为[1 trueLabel, 0 falseLabel]默认文案取自语言包filament-forms::components.radio.boolean.true / false同时注册一个BooleanStateCastisStoredAsInt true状态转换器使得存储层使用整数1 / 0而组件状态层暴露布尔值true / false。配套的状态细节getDefaultState()Radio.php会把布尔型默认值统一转换为1 / 0测试见 RadioTest.phphasNullableBooleanState()恒返回true表示该布尔状态允许为null未选择未显式设置状态转换器且未绑定枚举时getDefaultStateCasts()默认返回OptionStateCastisNullable true即选项值可空Radio.php测试 RadioTest.php 验证了fillForm([is_active 1])后组件状态为true的整数与布尔双向转换。渲染原理与无障碍Radio实现了HasEmbeddedView通过toEmbeddedHtml()Radio.php以内嵌视图方式输出 HTML无需额外 Blade 模板文件。其渲染结构要点容器div带roleradiogroup、aria-labelledby以及fi-fo-radio类内联时追加fi-inline每个选项是label包裹的原生input typeradioname统一使用字段 idvalue为选项值选项文本与描述若存在分别渲染为.fi-fo-radio-label-text与.fi-fo-radio-label-description字段整体禁用、单选项禁用、错误状态分别通过disabled属性与fi-valid/fi-invalid类体现。浏览器级渲染测试RadioTest.php会对/radio-test页面执行冒烟测试与无障碍检查含暗色模式并验证含双引号的选项值如1/2 wrench能被正确转义渲染。完整示例一个可运行的资源表单字段将以上能力组合起来即可得到一个功能完整的单选字段定义use Filament\Forms\Components\Radio; use Filament\Schemas\Schema; public function form(Schema $form): Schema { return $form -schema([ Radio::make(status) -label(Post status) -options([ draft Draft, scheduled Scheduled, published Published, ]) -descriptions([ draft Not visible to visitors., scheduled Will become visible on the scheduled date., published Immediately visible to visitors., ]) -default(draft) -inline(), Radio::make(notify_subscribers) -label(Notify subscribers?) -boolean(trueLabel: Yes, notify them, falseLabel: No, keep it quiet), ]) -statePath(data); }小结Radio是 Filament 表单中最常用的单选输入组件之一围绕它文档与源码共同构成了五个核心能力静态/动态options()选项、descriptions()选项描述、inline()内联布局、disableOptionWhen()单选项禁用配合自动化的getInValidationRuleValues()校验白名单以及内置整数存储与布尔状态转换的boolean()快捷模式。结合 Radio.php 及其 Trait 与 RadioTest.php 中的测试断言你可以放心地将其接入资源表单、弹窗表单或 Livewire 自定义表单并获得完整的无障碍与校验保障。如需了解更多校验规则如in()的其它用法可继续阅读 23-validation.md。【免费下载链接】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），仅供参考