Filament Schema 空状态组件（Empty State）完全指南：用 EmptyState 构建引导用户行动的空白界面

Filament Schema 空状态组件Empty State完全指南用 EmptyState 构建引导用户行动的空白界面【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 的 Schema 体系Server-Driven UI允许开发者用 PHP 配置对象声明式地构建表单、信息列表与页面布局。当界面暂时没有可展示的内容时Filament\Schemas\Components\EmptyState组件提供了一种规范化的空状态表达方式它不仅能向用户传达当前没有内容的信息更能通过标题、描述、图标与操作按钮的组合主动引导用户完成下一步操作。读完本文你将掌握 EmptyState 的完整配置能力heading、description、icon、footer、contained 等并理解其底层渲染原理与测试验证方式能够直接在表单、信息列表或自定义页面中落地可复用的空状态方案。什么是 Schema 空状态在 Filament 的 Schema 布局组件体系中EmptyState 是与 Grid、Section、Tabs、Wizard、Callout 并列的布局组件之一参见 Schema 总览文档。它的职责非常聚焦传达信息明确告诉用户这里还没有任何内容引导行动通过可点击的操作按钮引导用户走向创建数据、调整筛选条件等下一步行为。一个空状态至少需要一个标题heading除此之外还可以组合以下三块可选内容description()——补充说明文字icon()——图标增强视觉辨识度footer()——操作按钮或其他 Schema 组件。最基础的用法如下来自 官方文档use Filament\Actions\Action; use Filament\Schemas\Components\EmptyState; use Filament\Support\Icons\Heroicon; EmptyState::make(No users yet) -description(Get started by creating a new user.) -icon(Heroicon::OutlinedUser) -footer([ Action::make(createUser) -icon(Heroicon::Plus), ])这段代码即可渲染出一个包含用户图标、标题文案、说明文字以及新建用户按钮的空状态卡片。组件构造函数与工厂方法从源码看EmptyState 组件 的构造函数接收string | Htmlable | Closure类型的$heading并通过静态工厂方法make()创建实例final public function __construct(string | Htmlable | Closure $heading) { $this-heading($heading); } public static function make(string | Htmlable | Closure $heading): static { $static app(static::class, [heading $heading]); $static-configure(); return $static; }需要注意三点make()的标题参数是必填的这保证了空状态永远不会出现有容器没标题的残缺 UI标题既可以是静态字符串也可以是Htmlable如HtmlString还可以是闭包Closuremake()内部调用了configure()这意味着你可以使用 Filament 全局配置机制configureUsing()批量定制所有 EmptyState 的默认行为。getHeading()会通过evaluate()解析闭包结果因此所有接受闭包的配置方法都遵循 Filament 的Utility Injection工具注入机制——你可以在闭包参数中注入$livewire、$record、$operation、$get、$component等运行时上下文详见 Schema 总览的 Utility Injection 章节例如EmptyState::make(fn (?Model $record): string $record null ? No record selected : No related records)为空状态添加图标icon()方法用于为空状态添加图标提升视觉传达效率use Filament\Schemas\Components\EmptyState; use Filament\Support\Icons\Heroicon; EmptyState::make(No users yet) -description(Get started by creating a new user.) -icon(Heroicon::OutlinedUser)结合源码EmptyState.php可知图标的渲染细节图标默认渲染在圆形/圆角背景容器中fi-empty-state-icon-bg图标颜色默认回退为primarygetIconColor() ?? primary你同样可以使用iconColor()调整颜色图标尺寸默认使用IconSize::Large大型图标也可通过iconSize()覆盖当$icon为空时整个图标容器会被完全跳过不会残留空的占位元素。图标与颜色的完整定制能力来自HasIcon、HasIconColor、HasIconSize这三个 trait它们统一了 Filament 各组件的图标行为。图标风格可以参考 图标样式文档。在空状态底部插入操作按钮与其他组件footer()方法允许你在空状态的底部区域插入两类内容Actions 操作如Action::make(createUser)支持弹出 Modal、执行 PHP 函数等任意 Schema 组件通常是 Prime 组件文本、图标、图片、无序列表。use Filament\Actions\Action; use Filament\Schemas\Components\EmptyState; EmptyState::make(No users yet) -description(Get started by creating a new user.) -footer([ Action::make(createUser) -icon(Heroicon::Plus), ])关于footer()的底层实现源码 揭示了它的本质footer 并不是一个简单的 HTML 占位而是一个完整的子 Schemaconst FOOTER_SCHEMA_KEY footer; public function footer(array | Schema | Component | Action | ActionGroup | string | Htmlable | Closure | null $components): static { $this-childComponents($components, static::FOOTER_SCHEMA_KEY); return $this; } protected function configureChildSchema(Schema $schema, string $key): Schema { $schema parent::configureChildSchema($schema, $key); if (in_array($key, [static::FOOTER_SCHEMA_KEY])) { $schema -inline() -embeddedInParentComponent(); } return $schema; }这意味着 footer 区域内的按钮、文本等组件拥有完整的 Schema 渲染能力并且被标记为inline行内布局与embeddedInParentComponent内嵌于父组件因此会自动继承外层 Schema 的状态与上下文。footer 的渲染还支持闭包动态计算你可以根据当前记录、操作类型等条件决定是否展示、展示哪些按钮。移除空状态的容器样式默认情况下空状态组件带有一个卡片外观背景色、阴影与边框。如果你希望它融入页面、只渲染内容本身而不带容器可以使用contained(false)use Filament\Schemas\Components\EmptyState; EmptyState::make(No users yet) -description(Get started by creating a new user.) -contained(false)从实现上看contained()来自Filament\Support\Concerns\CanBeContainedtrait源码protected 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同一请求内重复读取不会重复求值渲染时contained(false)会为组件根元素添加fi-empty-state-not-containedCSS 类见 EmptyState.php通过样式类实现去容器化而不是删除 DOM 结构。紧凑模式compact()除了官方文档中的四个方法从源码还可以发现 EmptyState 继承了CanBeCompacttrait支持紧凑布局EmptyState::make(No records found) -compact()compact()接受布尔值或闭包为组件添加fi-compactCSS 类用于缩小内边距、缩小标题字号等。这一特性在将空状态嵌入较窄的布局区域如弹窗、侧栏时非常实用测试用例中也对其进行了覆盖见下文。动态计算所有配置方法都支持闭包EmptyState 的所有核心配置方法——make()、description()、icon()、footer()、contained()、compact()——都同时接受静态值与闭包。闭包内可以使用 Filament 的 Utility Injection 机制注入运行时工具实现完全动态化的空状态。例如根据当前筛选条件是否生效来决定展示不同的空状态文案use Filament\Schemas\Components\EmptyState; use Filament\Schemas\Components\Utilities\Get; EmptyState::make(fn (Get $get): string filled($get(search)) ? No results found for your search : No records yet) -description(fn (Get $get): string filled($get(search)) ? Try adjusting your search terms or filters. : Create your first record to get started.)这种内容即状态的动态能力让同一个 Schema 可以在不同数据条件下自适应地切换引导文案无需编写任何前端逻辑。底层渲染结构解析EmptyState实现了HasEmbeddedView接口通过toEmbeddedHtml()源码直接输出 HTML。其渲染结构如下div.fi-sc-empty-state ← 外层容器可合并 extraAttributes └── section.fi-empty-state ← 卡片主体compact / not-contained 类在此生效 └── div.fi-empty-state-content ├── div.fi-empty-state-icon-bg ← 图标容器可选 │ └── 图标默认 IconSize::Large ├── div.fi-empty-state-text-ctn │ ├── h2.fi-empty-state-heading ← 标题默认 h2 标签 │ ├── p.fi-empty-state-description ← 描述可选 │ └── footer.fi-empty-state-footer ← 底部操作区可选值得注意的实现细节标题使用getHeadingTag()决定标签名默认h2在 Blade 组件 中可见headingTag h2的默认值保证语义化标题与描述均经过e()转义输出默认防御 XSS如需渲染富文本可传入Htmlable类型参考 Prime 文本组件的 HTML 用法 中的 XSS 警告外层容器支持extraAttributes()可合并自定义 HTML 属性与 CSS 类官方同时维护了独立的 Blade 组件x-filament::empty-state视图文件props 包括compact、contained、description、footer、heading、headingTag、icon、iconColor、iconSizeSchema 组件与 Blade 组件保持一致的视觉与行为。测试验证组件行为有据可查Filament 仓库为 EmptyState 提供了完整的测试套件tests/src/Schemas/Components/EmptyStateTest.php其中验证了本文介绍的全部行为heading字符串标题、闭包标题均可正确解析getHeading()description默认返回null支持字符串与闭包icon默认返回null支持Heroicon枚举与闭包containmentisContained()默认为truecontained(false)后为falsecompactnessisCompact()默认为falsecompact()及闭包形式均生效footerfooter([])返回$this保证链式调用渲染通过 Livewire 组件RenderEmptyState系列逐一验证了上述所有配置在真实渲染中均能成功输出对应文案。这些测试可以直接作为你接入 EmptyState 时的行为参考EmptyState::make(No records)在description()、icon()未设置时会安全地跳过对应 DOM 区块不会产生空白元素。使用场景建议综合官方文档与源码EmptyState 的典型落地场景包括表单/信息列表的空数据提示在Schema的components()数组中放置 EmptyState配合$record、$operation等注入工具按数据状态渲染不同引导筛选结果为空当表格或表单经过筛选后无匹配记录时用闭包动态切换无结果与创建首个记录两种文案引导式空状态利用footer()放入创建类 Action甚至直接触发 Modal 表单把空转化为转化入口嵌入窄空间在弹窗、侧栏或紧凑表单区域使用compact()与contained(false)组合避免视觉冗余。小结EmptyState是 Filament Schema 布局组件中轻量但高频的一环它用最少的学习成本一个必填的make() 四个可选方法覆盖了空状态的全部表达维度并且与 Actions、Prime 组件、Utility Injection、全局配置等 Filament 核心机制无缝打通。结合其源码中的子 Schema 设计、CanBeContained/CanBeCompacttrait 以及完整的测试覆盖你可以放心地在任何 Schema 驱动的界面中使用它构建信息明确、引导自然的空状态体验。相关资源索引官方文档Empty states组件源码packages/schemas/src/Components/EmptyState.php容器开关 traitpackages/support/src/Concerns/CanBeContained.phpBlade 实现packages/support/resources/views/components/empty-state.blade.php测试用例tests/src/Schemas/Components/EmptyStateTest.php关联阅读Schema 总览、Prime 组件、Actions 文档、图标样式【免费下载链接】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），仅供参考