Filament Restore 恢复操作完整指南软删除记录的单个恢复、批量恢复与性能优化【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filamentFilament 内置的 Restore 操作RestoreAction/RestoreBulkAction专为 Laravel 的软删除soft delete机制设计能够在弹窗确认后一键将已删除的 Eloquent 记录恢复原状并自动处理重定向、成功通知与失败兜底。本文以packages/actions/docs/10-restore.md为骨架结合本仓库packages/actions/src的源码实现与tests/src/Actions下的测试用例系统讲解如何在 Filament 4.x 中接入单条恢复、批量恢复以及在大批量场景下通过chunkSelectedRecords()与fetchSelectedRecords(false)优化内存占用和查询效率。一、前置准备模型需要启用软删除Restore 操作面向的是「已软删除」的 Eloquent 记录因此在接入该操作前模型必须使用 Laravel 的SoftDeletestrait并通过迁移为数据表添加deleted_at时间戳列use Illuminate\Database\Eloquent\Model; use Illuminate\Database\Eloquent\SoftDeletes; class Post extends Model { use SoftDeletes; }从源码角度看RestoreAction在setUp()中通过visible()回调对记录做了两道守卫见 RestoreAction.php$this-visible(static function (Model $record): bool { if (! method_exists($record, trashed)) { return false; } return $record-trashed(); });也就是说只有模型实现了trashed()方法即启用了软删除且当前记录确实处于已删除状态时恢复按钮才会渲染非软删除模型或未删除记录上不会出现恢复动作。测试 RestoreActionTest.php 也专门验证了「恢复动作只出现在软删除记录上」这一行为。二、单条记录的恢复RestoreAction在最简单的场景下只需一行代码即可在资源页面、关系管理器或自定义页面中挂载恢复操作use Filament\Actions\RestoreAction; RestoreAction::make()点击触发按钮后Filament 会弹出确认模态框requiresConfirmation()在setUp()中默认启用用户确认后才真正执行恢复。2.1 恢复动作的底层执行逻辑RestoreAction继承自Action并使用了CanCustomizeProcesstrait其核心动作回调见 RestoreAction.php做了完整的防御式处理$this-action(function (Model $record): void { if (! method_exists($record, restore)) { $this-failure(); return; } $result $this-process(static fn (): ?bool $record-restore()); if (! $result) { $this-failure(); return; } $this-success(); });首先检查记录是否具备restore()方法不具备则直接标记为失败通过process()包装真实的$record-restore()调用CanCustomizeProcess允许你用-using()覆盖默认的恢复逻辑恢复结果非真时调用$this-failure()成功则调用$this-success()随后触发成功通知与重定向。2.2 默认外观与文案setUp()中还为动作配置了默认的标签、颜色和图标见 RestoreAction.php按钮标签、模态框标题、确认按钮文案、成功通知标题均取自国际化文件 restore.php如Restore :label、Restored默认颜色为灰色defaultColor(gray)图标为 Heroicon 的ArrowUturnLeft恢复箭头模态框图标使用OutlinedArrowUturnLeft。这些默认值都可以通过-label()、-modalHeading()、-color()等方法按需覆盖。三、表格批量恢复RestoreBulkAction如果希望用户在表格中勾选多行、再统一恢复应使用Filament\Actions\RestoreBulkAction。在 Filament 4.x 中将其加入表格的工具栏动作toolbarActions()即可use Filament\Actions\RestoreBulkAction; use Filament\Tables\Table; public function table(Table $table): Table { return $table -toolbarActions([ RestoreBulkAction::make(), ]); }3.1 批量恢复的可见性控制RestoreBulkAction默认是隐藏的只有当用户通过表格的 Trashed 过滤器TrashedFilter位于 packages/tables/src/Filters/TrashedFilter.php显式筛选「仅看已删除记录」时才会显示见 RestoreBulkAction.php$this-hidden(function (HasTable $livewire): bool { $trashedFilterState $livewire-getTableFilterState(TrashedFilter::class) ?? []; if (! array_key_exists(value, $trashedFilterState)) { return false; } return blank($trashedFilterState[value]); });这保证了批量恢复按钮只在「回收站」视图下出现避免用户在主列表中误操作。3.2 批量恢复的执行与失败统计批量动作的内部处理见 RestoreBulkAction.php支持两种模式默认逐条恢复遍历选中的记录集合逐条调用$record-restore()任何一条失败都会调用reportBulkProcessingFailure()计数并只上报第一条异常避免刷爆错误日志单查询批量恢复当关闭「预取记录」时直接对选中的记录查询调用restore()一次性完成。同时批量恢复完成后会自动取消勾选deselectRecordsAfterCompletion()见 RestoreBulkAction.php避免已恢复的记录继续停留在选中状态。测试 RestoreBulkActionTest.php 还验证了「只恢复被勾选的记录、未勾选的软删除记录保持原状」这一关键行为。四、恢复后的重定向successRedirectUrl()恢复操作成功后默认停留在当前页面。若希望提交后跳转到其他页面可使用successRedirectUrl()use Filament\Actions\RestoreAction; RestoreAction::make() -successRedirectUrl(route(posts.list))successRedirectUrl()除了接受字符串还接受一个闭包闭包中可注入$record等工具参数实现基于当前记录的动态跳转其签名定义见 CanRedirect.php。与之配套的还有failureRedirectUrl()用于在恢复失败时跳转到指定地址。五、自定义恢复成功通知记录恢复成功后Filament 会默认发送一条成功通知标题为国际化文案中的Restored。5.1 只改标题successNotificationTitle()use Filament\Actions\RestoreAction; RestoreAction::make() -successNotificationTitle(User restored)该方法同样接受闭包可在闭包内注入$record等参数动态生成标题。5.2 整体替换successNotification()若需要更丰富的通知内容正文、图标、持续时间、跳转动作等可传入一个完整的Notification实例use Filament\Actions\RestoreAction; use Filament\Notifications\Notification; RestoreAction::make() -successNotification( Notification::make() -success() -title(User restored) -body(The user has been restored successfully.), )闭包形式的successNotification()还能注入一个默认通知对象$notification作为定制起点。在底层sendSuccessNotification()会先构造Notification::make()-success()-title(...)再用闭包计算结果替换或扩展它且仅当通知存在有效标题时才会发送见 CanNotify.php。5.3 完全禁用通知successNotification(null)use Filament\Actions\RestoreAction; RestoreAction::make() -successNotification(null)传入null会在successNotification()内部将isSuccessNotificationDisabled置为true见 CanNotify.php后续sendSuccessNotification()会直接短路返回不发任何通知。六、生命周期钩子before() / after()与 Filament 其他动作一致恢复动作支持在执行前后插入自定义逻辑use Filament\Actions\RestoreAction; RestoreAction::make() -before(function () { // 记录恢复前执行例如审计日志 }) -after(function () { // 记录恢复后执行例如清理缓存、发送邮件 })钩子闭包中可以注入$record、$action等工具参数。例如在after()中读取刚恢复的记录并触发相关业务流程。七、批量恢复的性能优化7.1 默认行为与内存隐患默认情况下RestoreBulkAction会把选中的所有 Eloquent 记录一次性加载进内存再逐条循环调用restore()。当选择了几千甚至上万条记录时这会显著抬高应用的内存峰值。Filament 之所以默认这样做有两个明确的设计考量文档与源码共同印证逐条策略授权可以在恢复前用authorizeIndividualRecords(restore)对集合中的每条记录做模型策略Policy鉴权未授权的记录会被过滤并计入失败统计保证模型事件逐条调用$record-restore()会触发模型观察者的restoring/restored事件而这些事件在单条 SQL 批量恢复时不会触发。7.2 分批加载chunkSelectedRecords()如果记录数量较大但不希望一次性占满内存可以开启分批加载use Filament\Actions\RestoreBulkAction; RestoreBulkAction::make() -chunkSelectedRecords(250)chunkSelectedRecords()的签名定义在 CanFetchSelectedRecords.php默认块大小为 100可传整型或闭包。开启后Filament 会通过getSelectedTableRecords()/getSelectedTableRecordsQuery()按块拉取记录见 InteractsWithSelectedRecords.php在保持逐条restore()策略授权与模型事件仍然生效的前提下把内存占用控制在块大小量级。7.3 单查询恢复fetchSelectedRecords(false)如果你不需要逐条策略授权也不在乎模型事件的触发可以完全跳过记录加载让批量恢复在一条 SQL 查询内完成use Filament\Actions\RestoreBulkAction; RestoreBulkAction::make() -fetchSelectedRecords(false)fetchSelectedRecords(bool|Closure $condition true)见 CanFetchSelectedRecords.php关闭预取后RestoreBulkAction会走「单查询」分支直接执行$action-getSelectedRecordsQuery()-restore()并一次性上报成功条数见 RestoreBulkAction.php。这是吞吐量最高、内存占用最低的批量恢复方式适用于海量回收站的清理式恢复场景。八、批量恢复的失败文案体系RestoreBulkAction的setUp()中还配置了完善的失败通知体系见 RestoreBulkAction.php部分成功Restored :count of :total并区分「无权限恢复 :count 条」与「:count 条无法恢复」两种失败原因全部失败Failed to restore同样细分授权失败与处理失败文案。以上文案全部来自 restore.php 国际化文件你可以通过发布语言包或覆盖翻译来本地化这些提示。九、用测试验证恢复行为本仓库在tests/src/Actions下提供了两个针对恢复动作的完整测试套件可作为接入时的验收依据RestoreActionTest.php验证单条恢复动作只在软删除记录上渲染、确认模态框可挂载、恢复后assertNotSoftDeleted通过、成功通知发送、恢复后记录重新出现在常规表格视图以及getDefaultName()返回restoreRestoreBulkActionTest.php验证批量动作渲染与模态框挂载、勾选记录批量恢复、成功通知、只恢复选中记录未选中记录保持软删除以及默认动作名为restore。这些测试使用的是Pest Livewire 测试辅助TestAction::make()、callTableBulkAction()等当你为自己的资源接入 Restore 操作后可以参照它们编写回归测试确保回收站流程始终符合预期。总结Filament 的恢复动作把 Laravel 软删除能力封装成了开箱即用的 UI 交互RestoreAction负责单条记录的确认式恢复RestoreBulkAction负责表格批量恢复并默认提供重定向、成功通知、生命周期钩子、逐条策略授权与模型事件保障。面对大批量恢复chunkSelectedRecords()与fetchSelectedRecords(false)分别对应「受控内存 完整事件」和「单查询极致吞吐」两种优化路线你可以根据业务对授权与事件的需求灵活取舍。相关实现与测试均可在本仓库的 packages/actions/src/RestoreAction.php、RestoreBulkAction.php 及 tests/src/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），仅供参考