react-admin 软删除系列:`useHardDelete` Hook 彻底删除已删记录实战指南

原创2026-09-21 19:47:521,749 阅读
文章标签:前端UI组件

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

安装后还需要满足两个运行时前提:

  1. 有效的 Enterprise Edition 订阅/许可证——官方文档明确标注 "This feature requires a valid Enterprise Edition subscription",未授权使用会无法正常工作;
  2. 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 软删除工作流中,一条典型的记录生命周期是:

  1. 软删除:用户点击删除,useSoftDelete 触发 dataProvider.softDelete(),原记录被打上 deleted_at/deleted_by 标记(或移入 deleted_records 资源),从常规列表消失;
  2. 查看与管理:<DeletedRecordsListBase> 通过 dataProvider.getListDeleted() 拉取已删记录列表,配合 <DeletedRecordRepresentation> 展示每条已删记录的表示(见 DeletedRecordRepresentation.md);
  3. 恢复或永久删除:在已删记录列表中,用户要么用 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)。

参考资料(仓库内):

登录后查看全文
react-admin