从 v2.x 升级
如果你发现本指南中有任何遗落,请发起 PR 到官方仓库!
新的要求
- Laravel v10.0+
- Livewire v3.0+
请在升级到 Livewire v3 前先升级 Filament。升级 Livewire 说明请查看此处。
Livewire v3 最近发布了!
Livewire 团队在使其稳定方面做得很好,不过它是完全重写 Livewire v2。你可能会碰到问题,因此,我们建议在将 Filament v3 使用到生产环境之前对应用进行全面的测试。
自动升级
升级应用的最简单方式是,运行自动升级脚本。该脚本会自动升级应用到 Filament 的最新版本,并修改你的代码,处理大多数破坏性更新。
composer require filament/upgrade:"^3.2" -W --dev
vendor/bin/filament-v3
请确保仔细按照说明进行操作,并查看脚本所做的更改。之后,您可能需要对代码进行一些手动更改,不过脚本应该已经为您处理了大部分重复性工作。
最后,您必须运行 php artisan filament:install
来完成 Filament v3 的安装。所有新的 Filament 项目都必须运行此命令。
然后,你可以运行 composer remove filament/upgrade
,因为你不在需要它了。
你所使用的部分插件可能还没有适配 v3。你可以暂时将其移除出
composer.json
文件中直到这些插件升级,替换成另一个兼容 v3 的类似 插件。或者等到插件更新再升级应用,甚至可以发起 PR 帮助作者升级插件。
手动升级
通过 Composer 升级完依赖后,你应该执行 php artisan filament:upgrade
命令,以清理 Laravel 缓存并发布新的前端资源。
高影响更新
配置文件重命名并与其他 Filament 包合并
现在所有的 Filament 包共有一个配置文件。大部分配置已经转移到代码库的其他位置,只留下了少数。在替换您修改过的配置选项时,应该使用 v3 文档作为参考。要发布新配置文件并删除旧配置文件,请运行:
php artisan vendor:publish --tag=filament-config --force
rm config/forms.php
FORMS_FILESYSTEM_DRIVER
.env 环境变量
FORMS_FILESYSTEM_DRIVER
.env 环境变量被重命名为 FILAMENT_FILESYSTEM_DISK
。这个更新是为了使之与 Laravel 更加一致,因为 Laravel 9 也引入了这一更新。请确保相应地更新 .env 文件,同时别忘记生产环境!
新增 @filamentScripts
及 @filamentStyles
Blade 模板指令
@filamentScripts
和 @filamentStyles
模板指令必须添加到 Blade 布局文件中。由于 Livewire 3 不再使用类似的指令,你可以将 @livewireScripts
替换为 @filamentScripts
,将 @livewireStyles
替换为 @filamentStyles
。
CSS 文件移除
表单组件的 CSS 文件 - module.esm.css
- 已经被移除。查看 resources/css/app.css
。那个 CSS 现在由 @filamentStyles
自动加载。
JavaScript 文件移除
你不再需要在 JavaScript 文件中引入 FormsAlpinePlugin
。Alpine 插件现在由 @filamentScripts
自动加载。
Heroicons 已经升级到 v2
Heroicons 库已经升级到了 v2。也就是说你应用中使用的任何图标都已经改名了。你可以点击此处查看更新列表。
中等影响更新
日期时间选择器
日期时间选择器表单字段现在使用了浏览器默认的本机日期选择器。它通常比旧的日期选择器有更好的用户体验,但你可能会注意到功能缺失、浏览器兼容性差或行为错误。如果要恢复到旧的日期选择器,可以使用 native(false)
方法:
use Filament\Forms\Components\DateTimePicker;
DateTimePicker::make('published_at')
->native(false)
Secondary 颜色
Filament v2 的 secondary
在许多组件中是灰色。所有 secondary
的引用都应该替换成 gray
,以保持相同的外观。这一更新释放了 secondary
使之可以注册成你需要的自定义颜色。
$get
和 $set
闭包参数
$get
和 $set
参数现在使用了 \Filament\Forms\Get
或 \Filament\Forms\Set
类型,而不再是 \Closure
类型。这使得每个函数的 IDE 自动补全支持更加良好。
快速升级此类代码的简单方法是,查找和替换:
Closure $get
替换为\Filament\Forms\Get $get
Closure $set
替换为\Filament\Forms\Set $set
TextInput
masks now use Alpine.js' masking package
Filament v2 拥有一个流畅的 mask 对象语法,用于管理输入遮罩。在 v3 中,你可以使用 Alpin.js 的 masking 语法替代。更多详情请查看输入遮罩文档。
低影响更新
Rule 修改回调参数重命名
修改 Rule 对象的参数已被重命名为 modifyRuleUsing
,影响:
exists()
unique()