基于 react-admin Soft Delete 生态的 useGetOneDeleted:查询单个已删除记录的数据获取 Hook

原创2026-09-21 23:20:081,348 阅读
文章标签:前端UI组件

基于 react-admin Soft Delete 生态的 useGetOneDeleted:查询单个已删除记录的数据获取 Hook

导读

useGetOneDeleted 是 react-admin Soft Delete(软删除)企业级扩展套件中用于按 id 查询单个已删除记录的数据获取 Hook。它建立在 react-admin 核心 useGetOne 的数据获取模型之上,在组件挂载时调用 dataProvider.getOneDeleted(),并将结果缓存在 react-query 的 Query 缓存中。读完本文你将掌握该 Hook 的安装方式、调用签名、返回值、TypeScript 泛型用法,以及它与 SoftDeleteDataProvider、DeletedRecordsList 等软删除生态组件的协作关系。

什么是 useGetOneDeleted

在启用 Soft Delete 的 react-admin 应用中,"删除"并不等于从数据库中物理移除记录。被软删除的记录会被打上删除标记、记录删除人和删除时间,存入一个独立的"已删除记录"存储(详见 SoftDeleteDataProvider 文档)。此时,普通的 dataProvider.getOne() 已经无法再取到这些记录——需要专门的数据提供者方法 getOneDeleted() 来读取它们。

useGetOneDeleted 正是这一方法的 Hook 封装。它从 @react-admin/ra-core-ee 包中导出(该包是 react-admin 的企业版扩展,需要有效的 Enterprise Edition 订阅授权才能使用),其职责与核心包的 useGetOne 完全对称:挂载时发起请求、返回数据与加载/错误状态、并支持手动刷新。

说明:文档中给出的导入示例为 @react-admin/ra-core-ee。在部分历史版本文档中,该 Hook 也曾从 @react-admin/ra-soft-delete 包中导入,两处示例可参见 docs/useGetOneDeleted.md 与 docs_headless 版本。请以你所安装的企业版包的实际导出为准。

安装

由于 useGetOneDeleted 属于企业版扩展,首先需要安装 @react-admin/ra-core-ee:

npm install --save @react-admin/ra-core-ee
# 或者使用 yarn
yarn add @react-admin/ra-core-ee

安装后仍需持有有效的 Enterprise Edition 授权(license)才能使用该包。需要提醒的是:仅仅安装这个 Hook 还不够——要让 getOneDeleted 真正可用,你的 data provider 必须实现完整的软删除方法集,详见下文"与 SoftDeleteDataProvider 的协作"一节。

调用签名

useGetOneDeleted 的调用方式与核心包中的 useGetOne 高度一致:

const { data, isPending, error, refetch } = useGetOneDeleted(
    { id, meta },
    options
);

各参数说明如下:

参数 是否必填 说明
id 必填 要查询的已删除记录的标识符
meta 可选 任意你想透传给 data provider 的数据,例如希望返回结果中包含的字段列表,或自定义查询指令
options 可选 透传给 react-query useQuery 的选项对象

返回值的核心成员:

  • data:data provider 返回的已删除记录对象(结构见下文"已删除记录的结构"),请求未完成时为 undefined;
  • isPending:请求是否仍在进行中(等价于 react-query v5 中 status === 'pending');
  • error:请求失败时的错误对象,成功时为 null/undefined;
  • refetch:手动重新发起查询的函数,可用于"恢复记录后刷新已删除列表"等场景。

底层机制:复用 useGetOne 的数据获取模型

useGetOneDeleted 并非独立发明一套机制,而是复用了 react-admin 核心 useGetOne 的完整数据获取模型。在 packages/ra-core/src/dataProvider/useGetOne.ts 中可以看到这一模型的关键实现:

// packages/ra-core/src/dataProvider/useGetOne.ts
const result = useQuery<RecordType, ErrorType>({
    // 有时 id 来自 URL(如 Show 视图),是字符串;
    // 有时 id 来自 getList 返回的记录,是数字。
    // 由于 react-query 缓存是类型敏感的,这里始终把 id 转为字符串以保证命中同一缓存条目
    queryKey: [resource, 'getOne', { id: String(id), meta }],
    queryFn: queryParams =>
        id == null
            ? Promise.reject('useGetOne: id cannot be null')
            : dataProvider
                  .getOne<RecordType>(resource, { id, meta, signal })
                  .then(({ data }) => data),
    enabled: enabled ?? id != null,
    ...queryOptions,
});

从这段源码可以提炼出与 useGetOneDeleted 直接相关的事实:

  1. id 被强制转为字符串用于构建 query key——这与 useGetOneDeleted 文档中"query key 为 ['getOneDeleted', { id: String(id), meta }]"的约定一脉相承,保证无论是从 URL 读出的字符串 id 还是从记录对象取出的数字 id,都能命中同一条 react-query 缓存;
  2. id == null 时查询会被拒绝(Promise.reject),且 enabled 默认与 id != null 绑定,即没有 id 时查询不会发起;
  3. 透传 signal 支持请求取消——只要 dataProvider.supportAbortSignal === true,组件卸载或查询失效时底层请求会被 AbortSignal 中止,这一能力同样适用于已删除记录查询。

useGetOneDeleted 在这些约定上仅替换了方法名为 getOneDeleted、query key 前缀为 getOneDeleted,并同样通过 options 支持 onSuccess / onError / onSettled 副作用回调(见 useGetOne.ts 中 UseGetOneOptions 的类型定义)。

options 与 query key

options 参数可选,原样透传给 react-query 的 useQuery,因此所有标准 react-query 选项(如 enabled、staleTime、gcTime、select、refetchInterval 等)都可用。常见的两个注意点:

  • 避免在组件内联传入对象字面量作为 options,否则每次渲染都会生成新引用,可能触发不必要的重新请求;如果确实需要,请用 useMemo 或抽出到模块级常量。
  • query key 唯一性:本 Hook 的 react-query query key 为 ['getOneDeleted', { id: String(id), meta }]。这意味着 id 相同但 meta 不同的两次查询会命中不同的缓存条目;反过来,meta 中若包含对象,请保持其引用/序列化稳定,以免缓存碎片化。

基本用法

在任意组件中调用 useGetOneDeleted,即可按 id 查询一条已删除记录:

import { useGetOneDeleted } from '@react-admin/ra-core-ee';

const DeletedUser = ({ deletedUserId }) => {
    const { data: deletedUser, isPending, error } = useGetOneDeleted({
        id: deletedUserId,
    });
    if (isPending) {
        return <Loading />;
    }
    if (error) {
        return <p>ERROR</p>;
    }
    return (
        <div>
            User {deletedUser.data.username} (deleted by {deletedUser.deleted_by})
        </div>
    );
};

注意 deletedUser.data 中的 data 是原始记录本体:已删除记录是一个"包裹对象",其外层携带删除元信息(deleted_at、deleted_by),内层 data 才是删除前的记录内容。因此读取用户名要写 deletedUser.data.username,而删除人是 deletedUser.deleted_by。

已删除记录的结构

要正确消费 data,需要理解"已删除记录"这一数据结构的约定。根据 SoftDeleteDataProvider 文档,一条已删除记录包含以下属性:

字段 说明
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",
    },
}

使用 meta 透传字段

meta 可以携带任何你希望 data provider 理解的信息。最常见的用途是指定返回结果包含哪些字段,减少不必要的数据传输:

const { data } = useGetOneDeleted({
    id: deletedUserId,
    meta: { fields: ['username', 'deleted_by', 'deleted_at'] },
});

meta 的具体语义由你的 data provider 实现决定(例如 GraphQL 数据源可以借此生成字段选择集),Hook 本身只负责透传。

TypeScript 泛型

useGetOneDeleted 接受一个泛型参数来标注原始记录的类型。传入后,data.data 会被推导为该类型,获得完整的类型检查与自动补全:

import { useGetOneDeleted } from '@react-admin/ra-core-ee';

const DeletedUser = ({ deletedUserId }) => {
    const { data: deletedUser, isPending, error } = useGetOneDeleted<User>({
        id: deletedUserId,
    });
    if (isPending) {
        return <Loading />;
    }
    if (error) {
        return <p>ERROR</p>;
    }
    // TypeScript 知道 deletedUser.data 的类型是 User
    return (
        <div>
            User {deletedUser.data.username} (deleted by {deletedUser.deleted_by})
        </div>
    );
};

这里 User 是原始记录(即删除前 data 字段内的对象)的类型。外层包裹对象(含 id、resource、deleted_at、deleted_by、data)的类型由 @react-admin/ra-core-ee 提供。这与核心包 useGetOne 的泛型设计一致——在 useGetOne.ts 中,Hook 签名即为 useGetOne = <RecordType extends RaRecord = any, ErrorType = Error>(...),第二个泛型参数(默认 Error)可用于自定义错误类型。

与 SoftDeleteDataProvider 的协作

前置条件:data provider 必须实现 getOneDeleted

useGetOneDeleted 只是调用 dataProvider.getOneDeleted() 的封装,它能否工作完全取决于 data provider 是否实现了软删除方法集。Soft Delete 特性要求 data provider 至少实现:

  • softDelete / softDeleteMany:执行软删除;
  • getOneDeleted:按 id 获取单条已删除记录(本 Hook 依赖的方法);
  • getListDeleted:获取已删除记录列表(配合 useGetListDeleted);
  • restoreOne / restoreMany:恢复已删除记录(配合 useRestoreOne);
  • hardDelete / hardDeleteMany:物理删除记录(配合 useHardDelete)。

getOneDeleted 在 data provider 上的签名形如:

getOneDeleted: (params: GetOneDeletedParams): GetOneDeletedResult => {
    const { id } = params;
    // 按 id 查找已删除记录……
    return { data: deletedRecord };
},

关于软删除的完整方法论(SoftDeleteDataProvider 接口、删除/恢复/物理删除的流程、authorId 自动填充等),请参阅 SoftDeleteDataProvider.md。

免写后端的两种内置实现

如果不想为软删除编写后端接口,@react-admin/ra-core-ee 提供了两个开箱即用的 data provider 构建器,会为 getOneDeleted 提供默认实现:

  1. addSoftDeleteBasedOnResource:把所有资源的已删除记录集中存放到单个资源(默认名为 deleted_records)。软删除后记录从原资源消失、被重新创建到该集中资源中,getOneDeleted 从其中按 id 取回。
  2. addSoftDeleteInPlace:已删除记录仍留在原资源中,但被打上 deleted_at / deleted_by 标记;查询方法(getList、getOne 等)会自动过滤掉已删除记录。使用时需要把可软删除的资源列表作为配置对象传入,以便 getListDeleted 知道去哪里查找。

两种构建器的配置示例与注意事项(尤其是 addSoftDeleteInPlace 下应避免不带 resource 过滤地调用 getListDeleted)见 SoftDeleteDataProvider.md。

典型的应用场景

useGetOneDeleted 最常见的落地场景是回收站 / 已删除列表的详情查看:在 DeletedRecordsList 展示已删除记录列表后,点击某条记录进入详情页,用 useGetOneDeleted 按 id 加载其完整内容(含删除前的原始数据),并在页面上提供 useRestoreOne 恢复按钮和 useHardDelete 物理删除按钮。完整的最小实现可参考 SoftDeleteDataProvider.md 中的 Trash 示例页面。

小结

  • useGetOneDeleted 是 react-admin 软删除体系中的"单条已删除记录查询"Hook,调用 dataProvider.getOneDeleted(),query key 为 ['getOneDeleted', { id: String(id), meta }];
  • 它完全复用核心 useGetOne 的 react-query 数据获取模型(id 字符串化、enabled 绑定、AbortSignal 取消、onSuccess/onError/onSettled 回调),实现可对照 packages/ra-core/src/dataProvider/useGetOne.ts;
  • 返回值中 data 是含删除元信息的包裹对象,原始记录位于 data.data,读取字段时注意层级;
  • 使用前必须由 data provider 实现 getOneDeleted,或通过 addSoftDeleteBasedOnResource / addSoftDeleteInPlace 构建器获得默认实现;
  • 该 Hook 属于企业版 @react-admin/ra-core-ee,需要有效的 Enterprise Edition 授权。
登录后查看全文
react-admin