Filament Fieldset 组件完全指南用x-filament::fieldset优雅分组表单字段【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 是构建在 Laravel Livewire 之上的开源 UI 框架其Fieldset组件用于把多个表单字段组织到带可选标题legend的分组容器中让地址、联系信息等成组字段在表单与详情展示页中结构清晰、语义完整。阅读本文后你将掌握FieldsetBlade 组件的全部属性、与 Schema 体系中Fieldset::make()的配合方式以及如何通过contained、labelHidden、required等参数精细控制分组外观与可访问性。快速上手一个最简 Fieldset在 Filament 的 Blade 视图中Fieldset 是一个匿名 Blade 组件使用方式如下摘自 docs/12-components/03-fieldset.mdx-filament::fieldset x-slot namelabel Address /x-slot {{-- Form fields --}} /x-filament::fieldset将上面的{{-- Form fields --}}替换为任意表单字段即可例如x-filament::fieldset x-slot namelabel Address /x-slot x-filament::input.wrapper labelStreet x-filament::input typetext wire:modeladdress.street / /x-filament::input.wrapper x-filament::input.wrapper labelCity x-filament::input typetext wire:modeladdress.city / /x-filament::input.wrapper /x-filament::fieldset渲染后Filament 会输出一个标准的 HTMLfieldset元素并把label渲染为legend浏览器与屏幕阅读器都能正确识别这组字段属于同一分组。属性总览与逐项说明从组件实现 packages/support/resources/views/components/fieldset.blade.php 可以看到该组件接收四个 propsprops([ contained true, label null, labelHidden false, required false, ])属性类型默认值作用labelstring | nullnull分组标题渲染为legend为空时不输出 legendlabelHiddenboolfalse为true时隐藏 label视觉隐藏但仍对屏幕阅读器可见见下文sr-onlycontainedbooltrue是否显示边框与内边距的容器样式false时去掉边框requiredboolfalse为true时在 label 后追加红色的必填星号*其中label也支持通过具名 slot 传入即最简示例中的x-slot namelabel两种写法等价当同时提供属性与 slot 时以 slot 内容为准。必填标记required当分组内字段整体为必填时可通过required属性在 legend 上渲染星号无需手写x-filament::fieldset labelContact details required {{-- form fields --}} /x-filament::fieldset星号由fi-fieldset-label-required-mark类控制颜色源码 packages/support/resources/css/components/fieldset.css 中定义为text-danger-600 dark:text-danger-400与 Filament 的危险色语义保持一致。隐藏标题labelHidden有时分组标题只用于辅助屏幕阅读器、无需视觉呈现此时使用label-hiddenx-filament::fieldset labelPayment label-hidden {{-- form fields --}} /x-filament::fieldset底层实现会在legend上添加sr-only类见 fieldset.css 中.fi-fieldset-label-hidden规则即视觉隐藏但保留在无障碍树中这是表单可访问性的推荐做法。容器外观contained默认contained为true分组会渲染为带圆角、边框和内边距的卡片式容器rounded-xl border border-gray-200 p-6 dark:border-white/10若希望分组紧贴页面、不显示边框例如嵌套在卡片内层时设置:containedfalse即可去掉边框并仅保留顶部内边距pt-6避免与上层容器视觉冲突。向 Fieldset 传递任意 HTML 属性Blade 组件会将未声明的属性合并到根元素fieldset上$attributes因此可以透传id、class、wire:key等任意属性x-filament::fieldset labelShipping address classfi-address-fieldset wire:keyshipping-address-group {{-- form fields --}} /x-filament::fieldset在 Schema 中使用 FieldsetFilament v4 进阶用法在 Filament v4 的 Schema 体系中Fieldset同时是一个 Schema 组件类位于 packages/schemas/src/Components/Fieldset.php可在表单Form、详情页Infolist等任何 Schema 中通过静态工厂方法使用use Filament\Schemas\Components\Fieldset; Fieldset::make(Address) -schema([ TextInput::make(street), TextInput::make(city), TextInput::make(postcode), ])值得注意的源码细节默认双列布局setUp()中调用$this-columns(2)即 Fieldset 默认让子字段以两列网格排布相比普通 Section 更紧凑。单数关系绑定Fieldset 实现了CanEntangleWithSingularRelationships接口并引入EntanglesStateWithSingularRelationship配合-relationship(profile)即可把子字段直接映射到关联模型的单数关系上正如 tests/src/Forms/RelationshipsTest.php 中Fieldset::make(Profile)-relationship(profile)-schema([...])的用法。支持标签与必填标记它同时引入HasLabel与CanBeMarkedAsRequired因此label()、markAsRequired()等方法可直接使用。Schema 版 Fieldset 最终通过嵌入式视图toEmbeddedHtml()或 packages/schemas/resources/views/components/fieldset.blade.php 渲染为与 Blade 组件完全一致的fieldset/legend结构并自动带上fi-sc-fieldset类名——Blade 组件与 Schema 组件共享同一套样式与语义保证视觉一致。运行时控制外观与 Blade 版本一致Schema 版支持通过contained()、labelHidden()动态控制且这些方法接受Closure实现基于状态的运行时决策Fieldset::make(Address) -contained(fn (ComponentContainer $livewire): bool $livewire-compactMode) -schema([...]);contained()的底层逻辑位于 packages/support/src/Concerns/CanBeContained.phpprotected bool | Closure $isContained true; public function contained(bool | Closure $condition true): static { $this-isContained $condition; return $this; } public function isContained(): bool { return $this-isContainedCache ?? (bool) $this-evaluate($this-isContained); }可见其默认值为true支持闭包求值并对结果做了缓存isContainedCache同一请求周期内多次调用不会重复计算。测试佐证行为即契约仓库在 tests/src/Schemas/Components/FieldsetTest.php 中对 Fieldset 的行为做了系统化验证可以作为 API 契约参考支持字符串标签与Closure标签Fieldset::make(static fn (): string Dynamic)也支持无标签构造label 为nullisRequired()恒返回false——Fieldset 本身不参与校验必填语义交由内部字段各自声明isContained()默认truecontained(false)与闭包形式均可正确求值渲染测试通过 Livewire 组件断言 label 文本正确输出。这些测试同时印证了 Fieldset.php 的构造函数签名make(string | Htmlable | Closure | null $label null)即标签可为字符串、Htmlable或闭包。使用建议与最佳实践语义优先只要多个字段在语义上属于同一组地址、联系人、支付信息等就用fieldset而非普通Section因为legend能显著提升表单对屏幕阅读器的可读性。避免嵌套滥用Fieldset 默认自带边框容器若在 Section 或卡片内再套 Fieldset建议设置contained(false)减少视觉层级。必填星号交给组件不要手写*字符使用required属性可自动获得与主题一致的危险色样式。Schema 场景用Fieldset::make()在 Filament v4 的Form/Infolist定义中直接使用 Schema 组件版可同时获得双列布局与单数关系绑定能力。通过 Blade 版与 Schema 版两个入口Filament 的 Fieldset 让表单字段分组这一高频需求同时兼顾了页面模板的灵活性、Schema 定义的可组合性与无障碍语义的完整性是构建复杂表单时值得优先考虑的基础组件。【免费下载链接】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），仅供参考