Filament Section 组件完全指南：用 `＜x-filament::section＞` 组织后台界面内容区块

Filament Section 组件完全指南用x-filament::section组织后台界面内容区块【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 提供的 Section区块Blade 组件是后台面板中最常用的内容组织工具之一它可以把一组相关的内容如表单字段、操作按钮、说明文字收拢进一个带标题的卡片式容器中并支持图标、折叠、状态持久化、侧边布局等高级能力。本文将基于官方文档 Section Blade component 并结合仓库源码带你掌握 Section 组件全部属性、插槽与底层实现让你能直接复制代码构建出结构清晰、体验良好的管理界面。Section 组件简介Section 组件用于将内容分组展示并支持一个可选的标题heading。其最基础的用法如下x-filament::section x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section渲染结果是一个语义化的section标签标题位于顶部正文内容包裹在带fi-section样式的卡片容器中。从源码 index.blade.php 的props声明可以看到Section 组件内置了heading、description、afterHeader、footer、icon、collapsible、collapsed、aside、compact、secondary、divided、contained等一整套可配置项下文逐一展开。注意本文介绍的是 Blade 组件x-filament::section适用于任何 Blade 视图如自定义页面。如果你正在编写表单Form或 Schema则应使用 PHP API 版本的Filament\Schemas\Components\Section详见 schemas 文档中的 Sections 章节下文也会做对应介绍。为区块添加描述文字通过description插槽可以在标题下方追加一段描述常用于说明该区块内信息的用途x-filament::section x-slot nameheading User details /x-slot x-slot namedescription This is all the information we hold about the user. /x-slot {{-- Content --}} /x-filament::section在渲染时描述文字会被放入一个p classfi-section-header-description段落中见 description.blade.php位于标题正下方。为区块标题添加图标使用icon属性可以在标题左侧添加一个图标x-filament::section iconheroicon-o-user x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section图标名称支持 Filament 的图标别名体系如heroicon-o-*、heroicon-m-*等 Heroicons 图标。关于图标命名与自定义图标的完整说明可参考 图标文档。修改图标颜色图标颜色默认为gray灰色你可以通过icon-color属性改为danger、info、primary、success或warningx-filament::section iconheroicon-o-user icon-colorinfo x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section从源码看iconColor的默认值正是grayindex.blade.php颜色会通过IconComponent类作用于图标渲染。修改图标大小图标大小默认为large大可通过icon-size属性设置为sm小或md中x-filament::section iconheroicon-m-user icon-sizesm x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section x-filament::section iconheroicon-m-user icon-sizemd x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section大小值在内部会映射到Filament\Support\Enums\IconSize枚举IconSize.php该枚举定义了xs、sm、md、lg、xl、2xl六档Section 未指定时默认使用IconSize::Large即lg渲染逻辑见 index.blade.php 的generate_icon_html()调用。在标题末尾插入附加内容通过afterHeader插槽可以在标题与描述文字的右侧头部末尾渲染任意附加内容例如一个用于选择用户 ID 的输入框x-filament::section x-slot nameheading User details /x-slot x-slot nameafterHeader {{-- Input to select the users ID --}} /x-slot {{-- Content --}} /x-filament::section该插槽的内容会被放入fi-section-header-after-ctn容器中index.blade.php。注意当区块可折叠时点击afterHeader区域不会触发折叠切换——这正是源码中x-on:click判断! $event.target.closest(.fi-section-header-after-ctn)的原因保证了头部附加区域内的交互控件如下拉选择可以正常使用index.blade.php。制作可折叠区块使用collapsible属性可以让区块内容可折叠标题栏右侧会出现一个展开/收起的图标按钮x-filament::section collapsible x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section折叠状态由 Alpine.js 的x-data管理默认展开。源码中的折叠按钮是一个带aria-expanded与aria-controls属性的图标按钮并通过x-on:click.stop与标题栏的点击事件协同工作保证无障碍可访问性index.blade.php。默认折叠同时使用collapsed属性可以让区块默认处于折叠状态x-filament::section collapsible collapsed x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section持久化折叠状态使用persist-collapsed属性可以把折叠状态保存到浏览器 localStorage 中用户刷新页面后仍保持之前的折叠/展开状态。同时你需要提供一个唯一的id属性让浏览器区分不同区块各自的折叠状态x-filament::section collapsible collapsed persist-collapsed iduser-details x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section持久化的底层实现是 Alpine 的$persist插件存储键形如section-{id}-isCollapsedindex.blade.php。当没有显式指定id时collapseId会回退到元素的 DOM id$el.id。此外源码还暴露了四个可在页面任意位置触发的自定义窗口事件均通过事件detail.id与区块 id 匹配后生效index.blade.php事件作用collapse-section折叠指定 id 的区块expand-section/open-section展开指定 id 的区块toggle-section切换指定 id 区块的折叠状态例如在任意 Livewire 或 Alpine 代码中执行window.dispatchEvent(new CustomEvent(expand-section, { detail: { id: user-details } }))即可展开对应区块。将标题置于内容左侧默认情况下标题位于内容上方。使用aside属性可以把标题与描述放到左侧内容显示在右侧x-filament::section aside x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section让内容出现在标题之前在aside布局基础上再使用content-before属性可以让内容与标题的位置互换——内容在左、标题在右x-filament::section aside content-before x-slot nameheading User details /x-slot {{-- Content --}} /x-filament::section该布局通过fi-section-has-content-before与fi-aside两个 CSS 类组合实现index.blade.php。另外当区块使用aside布局时collapsible的折叠按钮不会渲染源码中$collapsible的有效性判断见 Section.php。更多进阶属性compact、secondary、divided、footer 等除了文档重点介绍的插槽与属性外从 index.blade.php 的 props 声明中还可以看到以下实用选项属性默认值说明compactfalse紧凑样式嵌套区块时减少内边距让布局更密实secondaryfalse次级样式背景对比度更低适合嵌套在其他区块内部dividedfalse在标题与内容之间绘制分隔线containedtrue是否包裹在卡片容器中设为false后区块将不呈现卡片背景footernull底部插槽可在区块末尾渲染操作按钮或附加内容headingTagh2标题的 HTML 标签可改为h1~h6以符合页面层级语义示例——一个嵌套在表单里、带底部操作按钮的次级紧凑区块x-filament::section secondary compact divided x-slot nameheading Notes /x-slot x-slot namefooter {{-- Action buttons --}} /x-slot {{-- Content --}} /x-filament::section标题标签的语义化在子组件 heading.blade.php 中处理它接收level参数默认 2自动生成h1~h6或p标签level 超过 6 时回退为段落便于屏幕阅读器与 SEO 正确识别页面结构。与 Schema 版 Section 的关系如果你在使用 Filament 的 Schema表单 / Infolist 的 PHP 构建器应当使用Filament\Schemas\Components\SectionSection.php它是同一视觉组件的 PHP API 形态所有上述能力都有对应方法use Filament\Schemas\Components\Section; Section::make(Rate limiting) -description(Prevent abuse by limiting the number of requests per period) -icon(heroicon-o-shield-exclamation) -iconColor(warning) -collapsible() -collapsed() -persistCollapsed() -aside() -schema([ // 表单字段... ]);两者的视觉结构与 CSS 类完全同源Schema 版通过toEmbeddedHtml()渲染出同样的fi-section结构见 Section.php。Schema 版还额外支持afterHeader()、footer()插入 Action 与 Prime 组件、columns()网格布局、deferLoading()延迟加载折叠内容等高级能力完整用法可参考 Sections 布局文档。源码与测试佐证想要深入理解 Section 组件的行为可以在仓库中查看以下文件组件实现packages/support/resources/views/components/section/index.blade.php —— 全部属性、折叠状态管理、Alpine 事件与可访问性细节标题/描述子组件heading.blade.php 与 description.blade.phpSchema 版 PHP 实现packages/schemas/src/Components/Section.php单元测试tests/src/Schemas/Components/SectionTest.php —— 覆盖了aside()、formBefore()、getHeadingsCount()以及 Section 与HasOne关系表单的状态加载等行为图标大小枚举packages/support/src/Enums/IconSize.php小结x-filament::section是 Filament 面板中组织界面内容的基础组件一个heading插槽定义标题、description插槽补充说明、icon/icon-color/icon-size增强视觉层级、afterHeader容纳头部交互控件、collapsible/collapsed/persist-collapsed处理长内容的折叠与记忆而aside、compact、secondary等属性则提供了多种布局与嵌套场景的适配能力。无论是自定义页面、资源详情页还是复杂表单Section 组件都能帮助你快速构建出结构清晰、可访问性良好的管理界面。【免费下载链接】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），仅供参考