企业官网建设流程全解析

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/filament

Filament 提供的 Section（区块）Blade 组件是后台面板中最常用的内容组织工具之一，它可以把一组相关的内容（如表单字段、操作按钮、说明文字）收拢进一个带标题的卡片式容器中，并支持图标、折叠、状态持久化、侧边布局等高级能力。本文将基于官方文档 Section Blade component 并结合仓库源码，带你掌握 Section 组件全部属性、插槽与底层实现，让你能直接复制代码构建出结构清晰、体验良好的管理界面。

Section 组件简介

Section 组件用于将内容分组展示，并支持一个可选的标题（heading）。其最基础的用法如下：

<x-filament::section> <x-slot name="heading"> 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 name="heading"> User details </x-slot> <x-slot name="description"> This is all the information we hold about the user. </x-slot> {{-- Content --}} </x-filament::section>

在渲染时，描述文字会被放入一个<p class="fi-section-header-description">段落中（见 description.blade.php），位于标题正下方。

为区块标题添加图标

使用icon属性可以在标题左侧添加一个图标：

<x-filament::section icon="heroicon-o-user"> <x-slot name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section>

图标名称支持 Filament 的图标别名体系（如heroicon-o-*、heroicon-m-*等 Heroicons 图标）。关于图标命名与自定义图标的完整说明，可参考 图标文档。

修改图标颜色

图标颜色默认为gray（灰色），你可以通过icon-color属性改为danger、info、primary、success或warning：

<x-filament::section icon="heroicon-o-user" icon-color="info" > <x-slot name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section>

从源码看，iconColor的默认值正是'gray'（index.blade.php），颜色会通过IconComponent类作用于图标渲染。

修改图标大小

图标大小默认为large（大），可通过icon-size属性设置为sm（小）或md（中）：

<x-filament::section icon="heroicon-m-user" icon-size="sm" > <x-slot name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section> <x-filament::section icon="heroicon-m-user" icon-size="md" > <x-slot name="heading"> 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 name="heading"> User details </x-slot> <x-slot name="afterHeader"> {{-- Input to select the user's 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 name="heading"> 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 name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section>

持久化折叠状态

使用persist-collapsed属性可以把折叠状态保存到浏览器 localStorage 中，用户刷新页面后仍保持之前的折叠/展开状态。同时你需要提供一个唯一的id属性，让浏览器区分不同区块各自的折叠状态：

<x-filament::section collapsible collapsed persist-collapsed id="user-details" > <x-slot name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section>

持久化的底层实现是 Alpine 的$persist插件，存储键形如section-{id}-isCollapsed（index.blade.php）。当没有显式指定id时，collapseId会回退到元素的 DOM id（$el.id）。

此外，源码还暴露了四个可在页面任意位置触发的自定义窗口事件，均通过事件detail.id与区块 id 匹配后生效（index.blade.php）：

例如在任意 Livewire 或 Alpine 代码中执行window.dispatchEvent(new CustomEvent('expand-section', { detail: { id: 'user-details' } }))即可展开对应区块。

将标题置于内容左侧

默认情况下，标题位于内容上方。使用aside属性可以把标题与描述放到左侧，内容显示在右侧：

<x-filament::section aside> <x-slot name="heading"> User details </x-slot> {{-- Content --}} </x-filament::section>

让内容出现在标题之前

在aside布局基础上，再使用content-before属性可以让内容与标题的位置互换——内容在左、标题在右：

<x-filament::section aside content-before > <x-slot name="heading"> 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 声明中还可以看到以下实用选项：

示例——一个嵌套在表单里、带底部操作按钮的次级紧凑区块：

<x-filament::section secondary compact divided> <x-slot name="heading"> Notes </x-slot> <x-slot name="footer"> {{-- 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\Section（Section.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.php
• Schema 版 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