Filament 资源记录删除与软删除完整指南：DeleteAction、TrashedFilter 与授权控制

Filament 资源记录删除与软删除完整指南DeleteAction、TrashedFilter 与授权控制【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament本文围绕 Filament基于 Laravel Livewire 的开源 UI 框架资源系统中删除记录这一核心操作展开系统讲解在 列表页删除记录、为资源启用软删除soft-deletes、恢复Restore与强制删除Force Delete的完整配置方式并结合本仓库 packages/actions 与 packages/tables 源码深入剖析各 Action 的默认行为、TrashedFilter 的查询逻辑以及基于模型 Policy 的授权机制。读完本文你将能够独立为自己的 Filament 资源接入删除 → 回收站筛选 → 恢复/强制删除的完整生命周期并精确控制单条删除与批量删除的权限边界。概述Filament 中的删除操作体系在 Filament 中删除记录不是一个单一功能而是一组由 packages/actions 提供的 Action 类组成的完整体系包括Action 类默认名称典型用途底层调用DeleteActiondelete删除单条记录软删除模型则软删除$record-delete()DeleteBulkActiondelete批量场景表格中批量删除多条记录批量查询-delete()或逐条删除ForceDeleteActionforceDelete强制物理删除软删除记录$record-forceDelete()RestoreActionrestore恢复已软删除的记录$record-restore()TrashedFiltertrashed表格筛选含回收站 / 仅回收站withTrashed()/onlyTrashed()默认情况下应用不会展示已删除记录的交互入口只有当模型使用 Laravel 的SoftDeletestrait 且资源显式接入软删除相关组件后恢复、强制删除与回收站筛选才会生效。处理软删除Soft-deletes创建带软删除能力的资源如果希望资源具备恢复、强制删除、筛选回收站记录的能力最简单的方式是在生成资源时使用--soft-deletes标志php artisan make:filament-resource Customer --soft-deletes该标志由 MakeResourceCommand 定义InputOptionVALUE_NONE类型其描述为 Indicate if the model uses soft-deletes。命令执行时会自动检测模型是否使用SoftDeletes并把删除/恢复/强制删除相关的表格动作、筛选器与编辑页头部动作一并生成到资源中。为已有资源添加软删除功能对于已经存在的资源可以按下面步骤手动接入软删除能力。首先更新资源的table()方法。需要引入相关 Action 与筛选器类注册TrashedFilter、单条记录动作与批量动作use Filament\Actions\BulkActionGroup; use Filament\Actions\DeleteAction; use Filament\Actions\DeleteBulkAction; use Filament\Actions\ForceDeleteAction; use Filament\Actions\ForceDeleteBulkAction; use Filament\Actions\RestoreAction; use Filament\Actions\RestoreBulkAction; use Filament\Tables\Filters\TrashedFilter; use Filament\Tables\Table; use Illuminate\Database\Eloquent\Builder; use Illuminate\Database\Eloquent\SoftDeletingScope; public static function table(Table $table): Table { return $table -columns([ // ... ]) -filters([ TrashedFilter::make(), // ... ]) -recordActions([ // 使用 simple resource单页资源或希望不离开表格直接删除记录时 // 可以把这些动作挂在表格行上。 DeleteAction::make(), ForceDeleteAction::make(), RestoreAction::make(), // ... ]) -toolbarActions([ BulkActionGroup::make([ DeleteBulkAction::make(), ForceDeleteBulkAction::make(), RestoreBulkAction::make(), // ... ]), ]); }接着覆盖资源的路由绑定查询移除SoftDeletingScope全局作用域否则已删除的记录将无法通过路由绑定被解析public static function getRecordRouteBindingEloquentQuery(): Builder { return parent::getRecordRouteBindingEloquentQuery() -withoutGlobalScopes([ SoftDeletingScope::class, ]); }最后如果存在编辑页Edit page在其getHeaderActions()中加入对应动作use Filament\Actions; protected function getHeaderActions(): array { return [ Actions\DeleteAction::make(), Actions\ForceDeleteAction::make(), Actions\RestoreAction::make(), // ... ]; }动作的可见性逻辑源码剖析从源码看Filament 会根据记录的软删除状态自动控制上述动作的显隐无需手工visible()DeleteAction 通过hidden()判断若模型存在trashed()方法且记录处于已删除状态则隐藏删除按钮——即已删除的记录不能再普通删除。ForceDeleteAction 与 RestoreAction 通过visible()判断仅当记录存在trashed()方法且确实处于已删除状态时才显示。这保证了强制删除/恢复按钮只出现在回收站记录上。DeleteBulkAction 则根据TrashedFilter的当前状态隐藏自身当回收站筛选被激活且选择的是仅回收站时批量删除按钮被隐藏此时应改用批量强制删除。三个 Action 均默认使用danger色Restore 为gray、要求二次确认弹窗requiresConfirmation()并提供成功/失败通知。另外 DeleteAction 还注册了modd键盘快捷键方便桌面端快速操作。TrashedFilter 的查询行为源码剖析TrashedFilter 继承自TernaryFilter三态筛选器提供了三个选项包含已删除记录with trashed$query-withTrashed()仅已删除记录only trashed$query-onlyTrashed()默认不含已删除$query-withoutTrashed()其baseQuery()会调用$query-withoutGlobalScopes([SoftDeletingScope::class])确保筛选器本身能读取到回收站数据。同时它实现了indicateUsing()当筛选生效时会在表格上方生成对应的状态指示器帮助用户明确当前视图是含回收站还是仅回收站。在列表页删除记录表格默认支持批量删除toolbarActions中的DeleteBulkAction。如果还需要在表格行上直接删除单条记录可以在recordActions中加入DeleteActionuse Filament\Actions\DeleteAction; use Filament\Tables\Table; public static function table(Table $table): Table { return $table -columns([ // ... ]) -recordActions([ // ... DeleteAction::make(), ]); }点击行上的删除按钮后Filament 会弹出确认模态框modal确认后执行$record-delete()。若模型启用了软删除delete()实际执行的是软删除若未启用则是物理删除。删除成功后显示成功通知失败则显示失败通知。对于批量删除DeleteBulkAction 的底层实现有两种路径当不需要逐条授权默认时直接对选中记录的查询执行-delete()一条 SQL 完成性能最优当启用逐条授权时则遍历每条记录调用$record-delete()并对失败计数最终通过通知区分全部成功 / 部分成功 / 全部失败三种结果对应语言包中的deleted、deleted_partial、deleted_none文案。批量删除完成后会自动取消已选记录deselectRecordsAfterCompletion()。授权AuthorizationFilament 的删除操作会遵循应用中注册的 Laravel 模型策略Model Policies无需额外配置。单条删除与批量删除当策略的delete()方法返回true时用户允许删除单条记录。批量删除bulk delete则检查策略的deleteAny()方法。Filament 之所以使用deleteAny()而非逐条检查delete()是因为对多条记录逐一调用策略方法性能开销过大。如果业务上确实需要批量删除时逐条校验delete()可以在DeleteBulkAction上调用authorizeIndividualRecords()DeleteBulkAction::make()-authorizeIndividualRecords()该方法定义在 CanBeAuthorized trait 中支持布尔值、字符串能力名Gate::inspect或闭包三种形式启用后批量删除将进入逐条授权与逐条处理模式未通过授权的记录会被跳过并计入失败通知。需要说明的是逐条授权会牺牲批量删除的部分性能仅在严格权限场景下推荐使用。软删除的授权针对软删除的三个阶段Filament 使用了独立的策略方法操作单条记录策略方法批量操作策略方法强制删除forceDelete()forceDeleteAny()恢复restore()restoreAny()forceDelete()用于阻止单条已软删除记录被强制物理删除forceDeleteAny()用于阻止批量强制删除。restore()用于阻止单条已软删除记录被恢复restoreAny()用于阻止批量恢复。与deleteAny()同理批量场景使用forceDeleteAny()和restoreAny()也是出于性能考虑避免逐条迭代检查。因此只要在对应模型的 Policy 中定义好这六个方法或其中需要约束的部分Filament 的删除、强制删除、恢复及对应的批量操作就会自动遵循授权结果未授权时按钮会被隐藏或操作被拦截。实战建议与常见陷阱路由绑定必须移除全局作用域为已有资源添加软删除时务必覆盖getRecordRouteBindingEloquentQuery()并withoutGlobalScopes([SoftDeletingScope::class])否则访问已删除记录的编辑页会直接 404。动作显隐是自动的DeleteAction在记录已删除时自动隐藏ForceDeleteAction/RestoreAction仅在已删除记录上显示不要手动设置互相冲突的visible()/hidden()。批量删除性能取舍默认deleteAny()授权 查询级删除是最快路径authorizeIndividualRecords()会逐条授权与逐条删除仅在需要严格行级权限时启用。配合回收站筛选使用TrashedFilter的三态设计含回收站 / 仅回收站 / 默认与批量动作的显隐联动是构建完整回收站体验的关键详见 tables 包文档 与 表格动作文档。测试验证本仓库在 tests/src/Actions 目录下提供了DeleteActionTest.php、DeleteBulkActionTest.php、ForceDeleteActionTest.php、RestoreActionTest.php等测试用例可作为理解各 Action 行为边界与编写自身测试的参考。通过本文的配置与源码分析你可以为任何 Filament 资源快速落地完整的删除生命周期并确保权限模型与 UI 行为严格一致。【免费下载链接】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），仅供参考