#简介

Filament v4 Beta 版本现已发布，带来了一系列强大且实用的更新。它更快、更易用，并让您在构建应用程序时拥有更多控制权。本文将重点介绍新功能以及这些变化如何改进您的工作流程！

要将您的应用升级到 Filament v4 beta，请阅读升级指南。要将 Filament v4 安装到新应用中，请访问安装指南。

您当前正在查看 Filament 4.x 的功能，该版本目前处于 beta 测试阶段，并非 stable (稳定) 版本。在 beta 测试期间，发布版本中可能会引入破坏性变更。请在 GitHub 上报告您遇到的任何问题。

正在寻找当前的稳定版本？请访问 3.x 文档。

#通用更新

#性能

Filament 中的渲染和交互性能得到了显著提升，尤其对于大型表格而言。在内部，许多 Blade 模板都经过了优化，以减少正在渲染的视图数量。通过利用现有的 PHP 对象来渲染 HTML，而不是引入新文件，Filament v4 减少了需要加载的文件数量，从而提高了性能。Blade 视图的大小也通过将 Tailwind CSS 类组提取到专用类中得到了缩减，这些专用类随后在 Blade 模板中使用。这减少了需要渲染的 HTML 量，从而加快了页面加载速度并减小了响应大小。

#Filament v4 现已采用 Tailwind CSS v4

Tailwind CSS v4 是一个专注于性能、灵活性和现代 Web 标准的重大更新。它具有重构的配置系统、改进的自定义功能以及更快的构建速度，使大规模构建您自己的自定义设计系统变得更加容易。有关最新功能和发布说明，请访问 Tailwind CSS 博客。

Tailwind CSS v4 通过从 rgb 切换到 oklch 来实现其色彩系统的现代化，使用更广泛的 P3 色域来产生超越 sRGB 限制的更生动、更准确的色彩。

由于 Filament v4 构建于 Tailwind v4 之上，因此其主题系统也采用了 oklch。

#语义化标题和动态色彩系统

在 v4 更新中，您会注意到整个应用程序中实现了一些可访问性功能：

标题级别现在动态生成，以保持正确的语义化 HTML 结构并提高可访问性。
调色板现在可以从单一基础色更准确地生成。
文本颜色会根据元素的背景色动态计算，以确保更易于访问的对比度并提高可读性。

#认证

#多因素认证

现在，在 Filament v4 中，除了标准的电子邮件/密码认证外，多因素认证 (MFA) 在默认的电子邮件和密码登录之外增加了一个额外的安全步骤。

Filament 支持两种内置的 MFA 方法：

使用 TOTP 应用（如 Google Authenticator、Authy 或 Microsoft Authenticator 应用）进行的应用认证。
向用户电子邮件发送一次性代码的邮件认证。

需要更多 MFA 选项？可以注册额外的自定义 MFA 提供程序以扩展 Filament 的认证功能。

#Heroicons

Filament 内置了 Heroicons 图标集，因此您可以直接使用图标而无需额外安装任何东西。新的 Heroicon 枚举类提供了 IDE 自动补全功能，帮助您快速找到所需的图标——告别魔法字符串！

每个图标都有实心和描边两种变体（Heroicon::Star vs. Heroicon::OutlinedStar）。Filament 会根据上下文自动选择合适的尺寸（16px、20px 或 24px）。

#使用 `FilamentTimezone` 设置默认时区

新的 FilamentTimezone facade 允许您通过 FilamentTimezone::set() 方法为 Filament 全局设置默认时区，从而简化了跨组件的默认时区设置。这使您可以一次控制多个组件，包括 DateTimePicker、TextColumn 和 TextEntry。

#“ISO” 格式

日期和时间现在支持在 TextColumn 和 TextEntry 组件中使用标准的 “ISO” 格式进行格式化。

#资源 (Resources)

#嵌套资源

关联管理器 (Relation managers) 和关联页面 (relation pages) 可以轻松地在资源内显示和管理相关记录。例如，在 CourseResource（课程资源）中，您可能会使用关联管理器或页面来管理属于某个课程的课时。这使您可以直接在表格中使用模态框创建和编辑课时。但是，如果课时更为复杂，模态框可能不够用。在这种情况下，您可以为课时提供其自己的资源，并带有完整的创建和编辑页面视图——这被称为嵌套资源 (nested resource)。

#资源类组织

资源类 (Resource classes) 现在会在其各自专用的命名空间内生成，使您的代码库更有条理。

#代码质量建议

我们还在 v4 中添加了一些更详细的建议，关于如何保持您的 Filament 代码整洁和可维护。以下是我们最喜欢的一些建议：

使用结构类和表格类 (schema and table classes) 将大型的 form() 和 table() 定义分离到各自的文件中。这有助于避免方法臃肿并提高可读性。
当单个表单输入、表格列、筛选器或操作变得复杂时，创建专用的组件类 (dedicated component classes)。这使得每个逻辑片段都保持专注和可复用。
按类型和用途组织组件，例如将表单输入放在 Schemas/Components 下，将表格操作放在 Actions 下。

#创建另一条记录时保留数据

默认情况下，“创建并继续创建另一个”操作 (Create and create another) 在提交后会清除表单。如果您想保留某些值，现在可以在“创建”页面类上使用 preserveFormDataWhenCreatingAnother() 方法，并仅返回您想保留的数据。

使用“创建”操作时，您可以使用 preserveFormDataWhenCreatingAnother() 方法。

#自定义页面内容

在 Filament v4 之前，我们没有一种特别便捷的方式来定制 Filament 面板中的页面布局。现在，Filament 中的每个页面都有其自己的结构 (schema)，它定义了页面的结构和内容。

您可以使用 content() 方法覆盖默认的页面结构，从而完全控制布局。
这使您可以添加、删除或重新排序结构组件 (schema components)，例如表格、选项卡和自定义元素。

#资源创建页面重定向

您现在可以配置创建资源后的默认重定向行为。
通过使用面板配置 (panel configuration)，您可以选择在创建记录后用户是被重定向到列表页、查看页还是编辑页。

这全局适用于面板内的所有资源。

#禁用搜索词拆分

新的 $shouldSplitGlobalSearchTerms 属性允许您禁用将全局搜索词拆分为单个词语的功能，从而提高在大型数据集上的搜索性能。

#关联管理器

#自定义内容选项卡

编辑页和查看页现在支持主内容选项卡的完全自定义。
通过覆盖 getContentTabComponent() 方法，您可以使用任何选项卡自定义选项，包括更改标签、图标，甚至添加自定义行为。

以前，只能自定义图标，但现在整个选项卡组件都是完全可配置的。

#导航

#侧边栏 / 顶部栏

Sidebar (侧边栏) 和 Topbar (顶部栏) 现在是 Livewire 组件，允许它们动态更新。如果您需要刷新它们——例如，在设置或权限更改后——您可以派发一个 refresh-sidebar 或 refresh-topbar 浏览器事件来触发重新加载。

#结构 (Schemas)

结构 (Schemas)构成了 Filament 服务器驱动 UI 方法的基础。它们允许您使用结构化配置对象在 PHP 中构建用户界面——无需手动编写 HTML 或 JavaScript。这些结构定义了您的 UI 的外观和行为，代表了诸如表单字段、信息列表条目 (infolist entries)、布局组件和主要组件 (prime components) 等组件。

每个 Filament UI 组件——无论是表单字段、描述列表，还是像文本或按钮这样的静态元素——都通过一个结构 (schema) 进行配置。组件是模块化、可嵌套和可复用的，使您的界面保持一致且易于维护。

一个结构由一个 Filament\Schemas\Schema 对象表示，您可以在 components() 方法中向其传递一个组件数组。

有关可用组件的完整列表，请参阅结构文档。

#垂直选项卡

选项卡 (Tabs) 通过将组件分组到不同的部分来帮助组织冗长或复杂的结构，减少视觉混乱并使表单更易于导航。

您现在可以通过调用 vertical() 方法切换到垂直选项卡布局。

#容器查询

除了基于视口大小的传统断点之外，您还可以使用容器查询 (container queries) 来创建基于父容器大小的响应式布局。

#表单

#富文本编辑器

富文本编辑器 (Rich editor) 现在使用的是 Tiptap，一个现代、无头、高度可扩展的开源编辑器框架。

#将内容存储为 HTML 或 JSON

默认情况下，富文本编辑器将内容存储为 HTML。如果您希望将内容存储为 JSON，可以使用 json() 方法。

#自定义区块

自定义区块 (Custom blocks) 是用户可以拖放到富文本编辑器中的元素。您可以使用 customBlocks() 方法定义用户可以插入到富文本编辑器中的自定义区块。

#合并标签

合并标签 (Merge tags) 允许用户在富文本内容中插入“占位符”——例如 {{ name }} 或 {{ today }}。这些标签在内容呈现时会被动态值替换，使其非常适用于个性化消息或显示日期等场景。

要启用合并标签，请在配置编辑器时使用 mergeTags() 方法。

用户可以通过输入 {{ 进行搜索，或使用工具栏中的“合并标签”工具来插入标签，该工具会打开一个可用标签面板以便轻松插入。

#扩展富文本编辑器

您可以通过创建自定义插件来扩展 Filament 中的富文本编辑器。这些插件允许您添加自己的 TipTap 扩展、工具栏按钮和渲染行为。

#滑块

滑块组件 (Slider component) 允许用户通过沿轨道拖动滑块来选择一个或多个数值——非常适用于范围、评级或百分比等输入。

#代码编辑器

代码编辑器组件 (code editor component) 允许用户直接在界面中编写和编辑代码。它支持常见的语言，包括 HTML、CSS、JavaScript、PHP 和 JSON。

#表格型重复器

表格型重复器 (Table repeaters) 使用定义的 columns (列) 在表格布局中显示重复器 (repeater) 项目。您可以使用 table() 方法和 TableColumn 对象配置这些列，这些对象映射到重复器结构中的字段。

每一列都可以自定义：

hiddenHeaderLabel() 在视觉上隐藏标签，但保持其可访问性。
markAsRequired() 添加红色星号以指示必填字段。
wrapHeader() 为长标签启用换行。
alignment() 设置表头对齐方式（start、center 或 end）。
width() 定义列的固定宽度。

#从模态框的表格中选择选项

ModalTableSelect 组件允许用户从一个显示完整 Filament 表格的模态框中选择记录——非常适用于拥有许多记录且需要高级搜索和筛选功能的关系。

#使用 JavaScript 最小化网络请求

#`hiddenJs()` 和 `visibleJs()`

您可以使用带有 PHP 回调的 hidden() 或 visible() 方法来有条件地隐藏或显示字段。但是，每当响应式字段发生更改时，这都会触发完整的结构重载和网络请求——可能会影响性能。

为了提高效率，请改用 hiddenJs() 或 visibleJs()。这些方法在客户端评估 JavaScript 表达式，允许您即时切换字段可见性而无需重新加载结构。

#`JsContent`

您可以通过传递 JsContent 对象使用 [JavaScript 动态设置文本内容——例如标签 (labels) 或 belowContent()。这允许像 label() 和 Text::make() 这样的方法根据字段值渲染 HTML。

在 JsContent 内部，您可以使用 $state 和 $get 来访问当前字段的状态或结构中的其他字段，从而实现无需服务器交互的实时、响应式文本更新。

#`afterStateUpdatedJs()`

当您在 afterStateUpdated() 函数中使用 $set() 设置另一个字段的状态时，它会修改状态——但仍会触发网络请求以重新加载结构。

为避免这种情况，您可以使用 afterStateUpdatedJs()，它会在字段值每次更改时运行一个 JavaScript 表达式。

这种方法完全跳过了网络请求，并在客户端即时更新字段。

在此 JavaScript 上下文中，您可以使用 $state、$get() 和 $set() 高效地与字段状态进行交互。

#将字段融合为一个组

FusedGroup 组件允许您将多个字段在视觉上组合成一个紧凑的组。它最适合与兼容的字段类型一起使用，例如文本输入、选择框、日期时间选择器和颜色选择器。

#向字段添加额外内容

字段包含多个插槽 (slots)，可以在子结构中插入内容。插槽可以接受文本、任何结构组件、操作 (actions)或操作组 (action groups)——通常与主要组件 (prime components) 一起使用。

可用的插槽包括：

aboveLabel()、beforeLabel()、afterLabel()、belowLabel()
aboveContent()、beforeContent()、afterContent()、belowContent()
aboveErrorMessage()、belowErrorMessage()

#部分渲染

默认情况下，在字段上使用 live() 会在其值更改时重新渲染整个结构。

Filament 现在提供了更高效的选项：

partiallyRenderComponentsAfterStateUpdated() 在状态更新后仅重新渲染指定的字段。
partiallyRenderAfterStateUpdated() 仅重新渲染字段本身。
skipRenderAfterStateUpdated(): 阻止任何重新渲染，在仅处理逻辑时很有用。

这些工具有助于优化字段交互，尤其是在表单只有一部分需要对更改做出反应时。

#改进的表单字段状态类型转换

表单字段状态现在会自动转换为正确的数据类型。例如，当使用绑定到枚举的选择框 (Select) 字段时，即使通过 $state 或 $get() 访问，状态也将返回枚举的实例——而不是原始字符串。这提高了类型一致性，并减少了在逻辑中手动转换的需要。

#信息列表 (Infolists)

#代码条目

代码条目 (Code entry) 允许您在信息列表 (infolist) 中呈现高亮显示的代码片段。它使用 Phiki 在服务器端进行代码高亮。

#表格

#使用自定义数据的表格

Filament 表格通常由 Eloquent 模型支持，但这并非总是理想选择。当您的数据未存储在数据库中——或者您想渲染外部或计算数据时——您现在可以使用自定义数据 (custom data) 作为数据源。

要使用自定义数据，请向 records() 方法传递一个 array (数组)。这使您可以渲染简单的数据集而无需数据库，同时仍支持列 (columns)、排序 (sorting)、搜索 (searching)、分页 (pagination)和操作 (actions) 等功能。

您还可以从外部 API 获取数据。例如，使用 Laravel 的 HTTP 客户端从 REST API 拉取数据，并在 records() 中将其作为 array 返回。这对于集成第三方服务或远程后端非常有用。

与 API 协作时，请确保实施适当的身份验证、错误处理和速率限制。

#使用选择筛选器处理空关系

您现在可以使用 hasEmptyOption() 方法来包含一个“无”选项，该选项用于筛选没有关联模型的记录。您可以使用 emptyRelationshipOptionLabel() 自定义此选项的标签。

#空表格现在也显示列标题

即使没有记录存在，表格标题现在也会显示，这增强了用户体验——尤其是在使用基于列的搜索和筛选器时。

#批量操作增强

请参阅本文的批量操作部分。

#操作 (Actions)

#统一的操作

操作 (Actions) 现在在表格、表单、信息列表和常规操作中完全统一。

所有操作现在都使用单一的 Filament\Actions 命名空间，而不是为每个上下文设置单独的 Action 类。

#工具栏操作

表格现在支持专用的工具栏操作 (toolbar actions)区域。

您可以将常规操作和批量操作 (bulk actions) 放置在 toolbarActions() 方法中。

这对于像“创建”这样不与特定行绑定的操作，或者使批量操作在表格的工具栏中更显眼和易于访问非常有用。

#批量操作

#提高批量操作性能

批量操作现在支持 chunkSelectedRecords() 方法，允许分小批处理选定的记录，而不是一次性将所有内容加载到内存中——从而在处理大型数据集时提高性能并减少内存使用。

#授权批量操作

您现在可以使用 authorizeIndividualRecords() 为批量操作中的每个选定记录检查策略方法。

只有用户有权操作的记录才会包含在 $records 数组中。

#批量操作通知

您现在可以在批量操作完成后显示通知，以告知用户结果——尤其是在由于授权而跳过某些记录时非常有用。

当所有记录都成功处理时，使用 successNotificationTitle()。
当部分或全部记录失败时，使用 failureNotificationTitle() 显示消息。

这两个方法都可以接受一个函数，以使用 $successCount 和 $failureCount 显示成功和失败记录的数量。

#预构建的批量操作

预构建的批量操作现在可以在不获取和填充所有选定模型的情况下运行，从而显著提升处理大型数据集的性能。

#取消选择的记录

使用“全选”时，现在会跟踪取消选择的记录。这通过最小化需要存储的记录键的数量来提高性能。

#操作速率限制

您现在可以使用 rateLimit() 方法来限制操作可以被触发的频率——按用户 IP、每分钟计算。

#授权

授权消息现在可以显示在操作的 tooltips (提示) 和 notifications (通知) 中。

#导入操作

#导入关系

BelongsToMany 关系现在可以通过操作导入。

#导出操作

#设置 XLSX 列样式

您现在可以使用导出器类中的 makeXlsxRow() 和 makeXlsxHeaderRow() 方法自定义 XLSX 导出中单个单元格的样式。

#自定义 XLSX 写入器

您现在可以在导出器类中配置 OpenSpout XLSX 写入器：

使用 getXlsxWriterOptions() 设置导出选项，如列宽。
覆盖 configureXlsxWriterBeforeClosing() 以在写入器实例最终确定之前对其进行修改。

#禁用按钮的提示

您现在可以在禁用按钮上显示 tooltip() (提示)。

#测试操作

在 v4 中测试操作现在更简单、更 streamlined。有关完整详细信息，请参阅测试操作部分。

#小部件 (Widgets)

#使图表可折叠

通过在小部件类上将 $isCollapsible 属性设置为 true，现在可以使图表可折叠。

#图表小部件的自定义筛选器

图表小部件 (Chart widgets) 现在支持使用 HasFiltersSchema trait 的自定义筛选器结构。您可以使用结构组件 (schema components) 通过 filtersSchema() 定义筛选器，并通过 $this->filters 属性访问提交的筛选器值。

#仪表盘

仪表盘小部件现在支持完整的响应式网格布局系统。

#多租户

多租户 (Multi-tenancy) 现在会自动应用全局作用域和生命周期事件。

#`unique` 和 `exists` 验证

Laravel 默认的 unique 和 exists 验证规则会绕过 Eloquent 模型，这意味着它们会忽略多租户中使用的全局作用域。这可能导致跨租户的错误验证失败。

为确保租户之间适当的数据隔离，您可以使用 scopedUnique() 和 scopedExists() 方法。

#面板配置

#Inter 字体现在本地加载

Filament 现在默认从本地加载 Inter 字体，而不是从 CDN 加载。您可以在配置文件中使用 font() 方法更改字体。

#子导航位置

默认情况下，子导航出现在每个页面的起始位置。您可以使用 subNavigationPosition() 方法为整个面板全局覆盖此设置。

可用选项有：

Start – 默认位置
End – 渲染在底部
Top – 显示为选项卡

#严格授权模式

默认情况下，如果不存在策略或策略方法，Filament 允许访问资源——假定不需要授权。

要强制执行更严格的安全性，您可以使用 strictAuthorization() 启用严格授权模式。如果缺少策略或方法，这将引发异常，确保所有访问都得到明确定义。

#邮箱更改验证

当使用带有 emailChangeVerification() 的 profile() 功能时，用户必须验证其新邮箱地址才能使其生效。验证链接会发送到新邮箱（有效期为 60 分钟），并且在点击该链接之前，数据库中的地址不会更新。为增加安全性，取消链接也会发送到用户的旧邮箱，以阻止未经授权的更改。

#错误通知

您现在可以自定义错误消息在您的 Filament 面板中的显示方式。

当 Laravel 的调试模式关闭时，Filament 会用闪现通知替换 Livewire 的全屏错误模态框。您可以：

使用 errorNotifications(false) 全局禁用此行为。
使用 registerErrorNotification(title, body) 自定义默认错误消息。
使用 statusCode 参数为特定的 HTTP 状态码设置自定义消息。
通过 $hasErrorNotifications 属性在每个页面上启用或禁用错误通知。

这使您可以完全控制出现问题时的用户体验。

#结论

Filament v4 Beta 带来了广泛的改进，旨在使您的开发体验更快、更一致且更易于维护。由于它仍处于 beta 测试阶段，现在是探索新功能并分享反馈的最佳时机。如果您需要 stable (稳定) 版本，请参阅 3.x 文档。