基于 react-admin Soft Delete 生态的 useGetOneDeleted:查询单个已删除记录的数据获取 Hook
基于 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 直接相关的事实:
- id 被强制转为字符串用于构建 query key——这与
useGetOneDeleted文档中"query key 为['getOneDeleted', { id: String(id), meta }]"的约定一脉相承,保证无论是从 URL 读出的字符串 id 还是从记录对象取出的数字 id,都能命中同一条 react-query 缓存; id == null时查询会被拒绝(Promise.reject),且enabled默认与id != null绑定,即没有 id 时查询不会发起;- 透传
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 提供默认实现:
addSoftDeleteBasedOnResource:把所有资源的已删除记录集中存放到单个资源(默认名为deleted_records)。软删除后记录从原资源消失、被重新创建到该集中资源中,getOneDeleted从其中按 id 取回。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 授权。