react-admin 软删除系列:`useHardDelete` Hook 彻底删除已删记录实战指南
react-admin 软删除系列:useHardDelete Hook 彻底删除已删记录实战指南
useHardDelete 是 react-admin 软删除(Soft Delete)企业版扩展中用于永久删除单条已删记录的核心 Hook:当回调被触发时,它会调用 dataProvider.hardDelete(),并基于已删记录自身的 id 完成物理删除。本文以官方文档为骨架,结合仓库内的 SoftDeleteDataProvider 文档 与配套 Hook 文档,完整讲解其签名、两种参数传递方式、TypeScript 泛型用法、与批量版本及可撤销版本的区别,并深入剖析 hardDelete 在整个软删除数据流中的位置与边界。
适用前提:本特性属于 Enterprise Edition(企业版)功能,需要安装
@react-admin/ra-core-ee并持有有效的企业版许可证,同时你的 dataProvider 必须实现hardDelete方法。仓库中的 useHardDelete.md 与 useHardDelete.md(headless 文档站版本) 均记录了同一 API。
一、useHardDelete 是什么
从官方文档的定义看,useHardDelete 的核心职责非常单一:
当回调(callback)被执行时调用
dataProvider.hardDelete(),并基于id删除一条已删记录。
在软删除体系里,"已删记录"(deleted record)并不是被 delete 掉的数据,而是被标记归档的元数据记录。根据 SoftDeleteDataProvider.md 的定义,一条已删记录是包含以下字段的对象:
id:已删记录自身的标识符(注意不是原记录的 ID);resource:被删除记录所属的资源名;deleted_at:删除发生的时间(ISO 8601 格式);deleted_by(可选):执行删除操作的用户标识;data:删除前的原始记录数据。
一个典型的已删记录示例:
{
id: 123,
resource: "products",
deleted_at: "2025-06-06T15:32:22Z",
deleted_by: "johndoe",
data: {
id: 456,
title: "Lorem ipsum",
teaser: "Lorem ipsum dolor sit amet",
body: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
},
}
useHardDelete 就是针对这类"已删记录"执行物理级永久删除的 Hook——它不再只是打标记,而是真正从数据源中清除这条记录。
最关键的一条警告
官方文档在开头就用 Warning 强调了最容易踩的坑:
useHardDelete中的id是已删记录(deleted record)的 ID,而不是实际被删除的原记录的 ID。
也就是说,如果你要永久删除一条已删记录,传入的应该是外层那条 deleted_at 包装记录的 id(上例中的 123),而不是 data.id(上例中的 456)。这个语义差异直接决定了你从哪里取 id——通常你应该通过 useRecordContext() 拿到的是已删记录本身,因此直接取 deletedRecord.id 即可。
二、Hook 签名与返回结构
useHardDelete 的调用签名如下:
const [hardDeleteOne, { data, isPending, error }] = useHardDelete(
{ id, previousData, meta },
options,
);
参数说明:
| 参数 | 类型 | 说明 |
|---|---|---|
id |
Identifier |
待永久删除的已删记录 ID(必填,语义见上文警告) |
previousData |
RaRecord |
已删记录删除前的数据,常用于乐观更新或回滚场景 |
meta |
any |
透传给 dataProvider.hardDelete() 的元数据,可携带自定义信息 |
options |
MutationOptions |
react-query 风格的 mutation 选项(onSuccess、onError、onSettled 等) |
返回的元组结构与 react-admin 其他 mutation Hook 一致:
hardDeleteOne:触发删除的回调函数,可以带参数调用(见下节);data:hardDelete成功后的返回值,类型为DeletedRecordType<Product>(泛型由记录类型推导);isPending:布尔值,表示请求是否进行中,通常用于禁用按钮;error:请求失败时的错误对象,非空时应渲染错误提示。
三、两种参数传递方式(重点实战)
hardDeleteOne() 回调可以被调用时传入与 Hook 完全相同的参数:
const [hardDeleteOne, { data, isPending, error }] = useHardDelete();
// ...
hardDeleteOne(
{ id, previousData, meta },
options,
);
因此你面临一个选择:参数放在调用 Hook 时传,还是放在执行回调时传? 官方文档明确给出建议:
两种方式都可以,但如果你有选择权,我们推荐在调用
hardDeleteOne回调时传参(第二种写法)。
推荐理由也很直接:回调时传参让 Hook 保持无状态、可复用——同一个 hardDeleteOne 可以被多个按钮、多条记录共享,而无需为每条记录重新实例化一个 Hook。下面给出官方文档的两个完整示例。
方式一:调用 Hook 时传参
import { useRecordContext } from 'ra-core';
import { useHardDelete } from '@react-admin/ra-core-ee';
const HardDeleteButton = () => {
const deletedRecord = useRecordContext();
const [hardDeleteOne, { isPending, error }] = useHardDelete(
{ id: deletedRecord.id, previousData: record }
);
const handleClick = () => {
hardDeleteOne();
}
if (error) { return <p>ERROR</p>; }
return <button disabled={isPending} onClick={handleClick}>Delete</button>;
};
方式二:调用回调时传参(推荐)
import { useRecordContext } from 'ra-core';
import { useHardDelete } from '@react-admin/ra-core-ee';
const HardDeleteButton = () => {
const deletedRecord = useRecordContext();
const [hardDeleteOne, { isPending, error }] = useHardDelete();
const handleClick = () => {
hardDeleteOne(
{ id: deletedRecord.id, previousData: record }
);
}
if (error) { return <p>ERROR</p>; }
return <button disabled={isPending} onClick={handleClick}>Delete</button>;
};
两个示例的 UI 行为完全一致:error 非空时渲染错误提示,isPending 为真时禁用按钮,点击触发永久删除。区别仅在于参数的绑定时机。注意示例中 deletedRecord 来自 useRecordContext()——它必须处于已删记录列表(如 <DeletedRecordsListBase>,见 DeletedRecordsListBase 文档)的 RecordContext 之中。
四、TypeScript 泛型用法
useHardDelete 接受两个泛型参数:第一个是记录类型,第二个是错误类型。这样可以让 react-query 的 mutation 回调获得完整的类型推断:
useHardDelete<Product, Error>(undefined, undefined, {
onError: (error) => {
// TypeScript 知道 error 是 Error 类型
},
onSettled: (data, error) => {
// TypeScript 知道 data 是 DeletedRecordType<Product> 类型
// TypeScript 知道 error 是 Error 类型
},
});
注意这个示例中 Hook 前两个参数传的是 undefined, undefined——因为参数改为在回调中传递,Hook 本身不需要记录与选项,此时只需提供 mutation 选项 options(第三个参数)。类型推导价值在于:
data被精确推断为DeletedRecordType<Product>,即"已删记录包装 + 原始记录数据"的复合类型,配合上文提到的 deleted record 结构,你可以安全地访问data.resource、data.deleted_at以及data.data(原始记录);error被精确推断为你声明的Error类型,避免在回调里做多余的类型断言。
五、安装与前置条件
在项目中使用 useHardDelete,需要先安装企业版核心包:
npm install --save @react-admin/ra-core-ee
# 或
yarn add @react-admin/ra-core-ee
安装后还需要满足两个运行时前提:
- 有效的 Enterprise Edition 订阅/许可证——官方文档明确标注 "This feature requires a valid Enterprise Edition subscription",未授权使用会无法正常工作;
- dataProvider 实现
hardDelete方法——useHardDelete只是触发端,真正的物理删除发生在数据提供者层。
关于第 2 点,根据 SoftDeleteDataProvider.md,一个完整的软删除数据提供者需要实现以下方法:softDelete、softDeleteMany、getOneDeleted、getListDeleted、restoreOne、restoreMany、hardDelete、hardDeleteMany,其中 hardDelete 的签名形如:
hardDelete: (params: HardDeleteParams): HardDeleteResult => {
const { id } = params;
// ...
return { data: deletedRecordId };
},
useHardDelete 会将该 Hook 收到的 { id, previousData, meta } 与 meta 一并透传给它,驱动这条调用链:useHardDelete → hardDeleteOne() → dataProvider.hardDelete() → 物理删除。
如果不想手写这些方法,ra-soft-delete 还提供了两个开箱即用的构建器:addSoftDeleteBasedOnResource(把已删记录统一存入 deleted_records 资源)和 addSoftDeleteInPlace(在原资源内标记 deleted_at/deleted_by)。在后者模式下,已删记录留在原资源中但被标记,hardDelete 需要据此区分处理。
六、与相关 Hook 的取舍:什么时候用哪个
useHardDelete 不是软删除体系中唯一的"删除"入口,把它放进整个生态对比,才能选对工具:
| Hook | 触发的 dataProvider 方法 | 行为 |
|---|---|---|
useSoftDelete(见 useSoftDelete.md) |
softDelete |
标记删除,记录进入已删状态,数据仍保留 |
useHardDelete(本文) |
hardDelete |
永久物理删除单条已删记录 |
useHardDeleteMany(见 useHardDeleteMany.md) |
hardDeleteMany |
按 ids 数组批量永久删除多条已删记录 |
useRestoreOne(见 useRestoreOne.md) |
restoreOne |
恢复单条已删记录 |
useDeletePermanentlyWithUndoController |
hardDelete(undoable 模式) |
带撤销提示的永久删除控制器 |
需要"撤销"时:useDeletePermanentlyWithUndoController
官方文档在 useHardDelete 开头给出了一个 Tip:
如果你需要可撤销(undoable)的 UI 操作,请看
useDeletePermanentlyWithUndoController。
该控制器以 undoable mutation 模式调用 dataProvider.hardDelete(),同时显示通知并取消选中已删记录列表中的对应记录。它的参数是一个对象:record(必填,被永久删除的已删记录)、mutationOptions(支持 meta)、successMessage(自定义通知消息 key)、onClick(mutation 触发后的回调)。典型用法:
const { isPending, handleDeletePermanently } =
useDeletePermanentlyWithUndoController({ record });
如果你的场景需要先给用户一个反悔窗口,优先选择它;如果只是需要静默物理删除,useHardDelete 更轻量。
需要批量时:useHardDeleteMany
官方同时提供批量版本 useHardDeleteMany,签名与用法几乎一一对应,只是把 { id } 换成 { ids }(数组),返回的 data 类型为 Product['id'][]。它通常配合 useListContext() 的 selectedIds 实现"批量永久删除选中已删记录"按钮。注意:批量版本的警告语义同样成立——ids 是已删记录的 ID 数组,而非原记录 ID 数组。
七、完整链路:从"软删除"到"永久清除"
把 useHardDelete 放回 react-admin 软删除工作流中,一条典型的记录生命周期是:
- 软删除:用户点击删除,
useSoftDelete触发dataProvider.softDelete(),原记录被打上deleted_at/deleted_by标记(或移入deleted_records资源),从常规列表消失; - 查看与管理:
<DeletedRecordsListBase>通过dataProvider.getListDeleted()拉取已删记录列表,配合<DeletedRecordRepresentation>展示每条已删记录的表示(见 DeletedRecordRepresentation.md); - 恢复或永久删除:在已删记录列表中,用户要么用
useRestoreOne恢复,要么用本文的useHardDelete执行不可逆的物理删除——这一步之后,hardDelete从数据源中真正抹除记录,无法再恢复。
因此 useHardDelete 是整条链路的"终结点"操作,UI 上通常需要更醒目的确认交互(例如二次确认或撤销窗口),避免误触造成数据不可逆丢失。
八、最佳实践小结
- id 语义先行:永远确认传入的是"已删记录"的
id(外层记录),而不是data.id(原记录),这是本 Hook 最容易出错的点; - 参数晚绑定:优先在
hardDeleteOne()回调调用时传参,让 Hook 保持可复用; - 类型双泛型:
useHardDelete<Product, Error>能让你在onSettled中安全访问DeletedRecordType<Product>结构; - 按需选型:可撤销选
useDeletePermanentlyWithUndoController,批量选useHardDeleteMany,单条静默删除选useHardDelete; - dataProvider 兜底:确保
hardDelete已在数据提供者中实现,或使用ra-soft-delete提供的addSoftDeleteBasedOnResource/addSoftDeleteInPlace构建器(详见 SoftDeleteDataProvider.md)。
参考资料(仓库内):
- docs/useHardDelete.md:本文对应的原始 Markdown 文档;
- docs_headless/src/content/docs/useHardDelete.md:headless 文档站版本;
- docs/SoftDeleteDataProvider.md:软删除 dataProvider 接口、已删记录结构与构建器详解;
- docs_headless/src/content/docs/useHardDeleteMany.md:批量永久删除 Hook;
- docs_headless/src/content/docs/useDeletePermanentlyWithUndoController.md:可撤销的永久删除控制器。