Filament 中文文档

主题

全部文档

什么是 Filament？ ​

简介 ​

Filament 是面向 Laravel 的服务端驱动 UI（SDUI）框架。 它让你用结构化的 PHP 配置对象定义用户界面，而不是传统模板。Filament 基于 Livewire、Alpine.js 与 Tailwind CSS，帮助你构建管理后台、仪表盘、表单类应用等完整界面，且无需编写自定义 JavaScript 或前端代码。

What is Server-Driven UI?

SDUI 是 Meta、Airbnb、Shopify 等公司已验证的架构：把 UI 控制权放到服务端，从而更快迭代、更一致，并把逻辑集中管理。Filament 将这一模式用于 Web 开发：用 PHP 类声明式定义界面，再由服务端渲染为 HTML。

需要区分服务端驱动 UI（SDUI）与服务端渲染 UI（Server-Rendered UI）。两者都会在服务端渲染内容，但后者依赖静态模板（如传统 Blade 视图），界面结构与行为事先写在 HTML/PHP 中；而 SDUI 让服务端能依据实时配置与业务逻辑动态生成界面，更灵活、可响应，且不必直接改前端模板。

成千上万的开发者用 Filament 为 Laravel 应用添加管理后台，但它远不止于此。你可以用它构建自定义仪表盘、用户门户、CRM，甚至带多面板的完整应用。它能与任意前端技术栈无缝集成，与 Inertia.js、Livewire、Blade 搭配尤为合适。

若 Laravel 应用已在使用 Blade 视图，Filament 组件同样可以增强它们：把由 Filament 驱动的 Livewire 组件放入任意 Blade 视图或路由，并用同一套基于 schema 的构建器处理表单、表格等，无需更换整套技术栈。

包 ​

Filament 核心由多个包组成：

  • filament/filament - 用于构建面板（如管理后台）的核心包。面板通常会用到其他包的许多功能，因此会依赖其余包。
  • filament/tables - 数据表格构建器，可渲染带筛选、排序、分页等功能的交互式表格。
  • filament/schemas - 用「组件」PHP 对象数组作为配置来构建 UI 的包。Filament 许多功能用它渲染界面，并内置一组用于展示内容的基础组件。
  • filament/forms - filament/schemas 组件集合，覆盖大量表单输入（字段），并集成校验。
  • filament/infolists - filament/schemas 组件集合，用于渲染「描述列表」。Infolist 由「条目（entries）」组成，即展示只读信息（文本、图标、图片等）的键值 UI；数据可来自任意来源，常见于单条 Eloquent 记录。
  • filament/actions - Action 对象封装按钮 UI、可由按钮打开的交互式模态框，以及提交模态框时要执行的逻辑。可在界面任意位置使用，常用于删除记录、发邮件，或根据模态表单输入更新数据库等一次性操作。
  • filament/notifications - 在应用 UI 中向用户发送通知的简便方式。可发送请求后立即出现的「flash」通知、存入数据库并由用户按需打开侧滑模态查看的「database」通知，或通过 WebSocket 实时推送的「broadcast」通知。
  • filament/widgets - 仪表盘「小部件」集合，可渲染任意内容（多为统计数据）。可用该包在仪表盘中展示图表、数字、表格及完全自定义小部件。
  • filament/support - 包含其他包共用的 UI 组件与工具。用户通常不必直接安装，它是其余包的依赖。

插件 ​

Filament 高度可扩展，可向框架添加自己的 UI 组件与功能。仅限本应用的扩展可放在代码库内；通用能力则可作为 Composer 包分发。在 Filament 生态中，这类 Composer 包称为「插件」，社区已有数百个。Filament 团队也官方维护若干插件，用于对接 Laravel 生态中流行的第三方包。

生态中绝大多数插件开源免费。也有部分付费高级插件，通常提供更好的支持与质量。

WARNING

非 Filament 团队维护的插件由独立作者创建与管理。它们可能提升体验，但 Filament 无法保证其质量、安全、兼容性或持续维护。安装前建议审阅代码、文档与用户反馈。

可在 Filament 网站 浏览大量官方与社区插件。

自定义外观 ​

Tailwind CSS 是基于工具类的 CSS 框架，Filament 将其用作基于 token 的设计系统。组件渲染出的 HTML 并不直接使用 Tailwind 工具类，而是把 Tailwind 工具类编译成语义化 CSS。你可以用自己的 CSS 针对这些语义类修改组件外观，在默认设计之上形成一层薄覆盖。

一个简单例子是修改 Filament 中所有按钮的圆角。Filament 代码库默认用如下 CSS（含 Tailwind 工具类）样式化按钮：

css
.fi-btn {
    @apply rounded-lg px-3 py-2 text-sm font-medium outline-none;
}

若要减小 Tailwind CSS 圆角，可在自己的 CSS 中为 .fi-btn 应用 rounded-sm（小圆角）工具类：

css
.fi-btn {
    @apply rounded-sm;
}

这会把 Filament 中所有按钮的默认 rounded-lg 覆盖为 rounded-sm，同时保留按钮其他样式。该体系让你能灵活自定义组件外观，无需写完整自定义样式表，也无需为每个组件维护 HTML 副本。

更多外观自定义说明见 自定义样式文档。

测试 ​

Filament 核心包会做单元测试，以保证各版本稳定。作为用户，你也可以为基于该框架的应用编写测试。Filament 提供用于测试功能与 UI 组件的工具，兼容 Pest 或 PHPUnit。在自定义框架或实现自定义功能时测试尤为重要；验证基础功能是否按预期工作同样有价值。

更多说明见 测试文档。

Filament 的替代方案 ​

若读到这里觉得 Filament 可能不适合你的项目，完全没问题！Laravel 生态里还有许多优秀项目可能更合适。以下是我们喜欢的一些选择：

Filament 听起来太复杂 ​

Laravel Nova 是为 Laravel 应用构建管理后台的简便方式。它是 Laravel 团队维护的官方项目，购买也能支持 Laravel 框架的开发。

不想用 Livewire 做任何自定义 ​

Filament 很多部分根本不需要碰 Livewire，但构建自定义组件时可能需要。

Laravel Nova 基于 Vue.js 与 Inertia.js；若项目需要大量自定义且你熟悉这些技术，它可能更合适。

我需要开箱即用的 CMS ​

Statamic 是基于 Laravel 的 CMS。若你需要易搭建、易用的 CMS，且不必自建管理后台，它是很好的选择。

我只想写 Blade 视图并自己处理后端 ​

Flux 是官方 Livewire UI 套件，以预构建、预样式的 Blade 组件形式提供。由维护 Livewire 与 Alpine.js 的同一团队维护，购买也能支持这些项目的开发。