react-admin 软删除数据获取实战useGetListDeleted Hook 完整指南与源码解析【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin本文是 react-admin 软删除Soft Delete体系中专门用于拉取已删除记录列表的核心数据获取 Hook 技术指南。useGetListDeleted在组件挂载时调用dataProvider.getListDeleted()完整支持过滤filter、排序sort与分页pagination是构建回收站归档列表已删除记录管理页等功能的基石。读完本文你将掌握该 Hook 的完整签名与参数语义、与useGetList的异同、TypeScript 泛型用法、底层 Data Provider 契约以及上层组件DeletedRecordsList的协同方式。什么是 useGetListDeleteduseGetListDeleted是一个数据获取 Hook它在组件挂载mount时调用dataProvider.getListDeleted()用于获取已被软删除Soft Delete的记录列表。所谓软删除是指在数据库中并不真正物理删除记录而是通过deleted_at、deleted_by等字段将记录标记为已删除从而安全地归档记录而不是永久删除在专门界面中浏览、过滤所有已删除记录单独或批量恢复归档条目追踪谁在何时删除了什么。详见仓库内 SoftDeleteDataProvider 文档。useGetListDeleted就是这套软删除数据访问层中面向读取已删除列表的查询 Hook与useGetOneDeleted读取单条已删除记录、useRestoreOne/useRestoreMany恢复、useHardDelete/useHardDeleteMany永久删除等配套使用。注意useGetListDeleted属于 react-admin 的Enterprise Edition企业版附加功能需要有效的企业版订阅才能使用。函数签名与参数详解Hook 的完整调用签名如下出自 useGetListDeleted 文档const { data, total, isPending, error, refetch, meta } useGetListDeleted( { pagination: { page, perPage }, sort: { field, order }, filter, meta }, options );第一个参数查询参数对象参数类型说明pagination{ page: number, perPage: number }分页参数page从 1 开始perPage为每页条数sort{ field: string, order: ASC \| DESC }排序参数指定排序字段与方向filterobject过滤条件直接透传给 Data Provider 作为查询条件metaany可选任意你想传给 Data Provider 的额外参数例如要求返回结果中包含的字段列表一个关键的语义区别需要强调参数里的meta与响应中的meta属性是两个完全不同的东西。请求参数meta是你想传给数据提供方的东西例如meta: { embed: [author] }这类后端扩展指令而返回值中的meta是数据提供方随记录一起返回的附加元数据。二者虽然同名但互不相关。第二个参数react-query options第二个参数options同样可选它会原样传给 react-query 的useQueryHook。这意味着你可以使用 react-query 的全部查询选项例如enabled控制查询是否启用staleTime/gcTime控制缓存过期与垃圾回收时间onSuccess/onError/onSettled查询成功、失败、结束时的副作用回调select对返回数据进行投影转换refetchInterval轮询刷新。query key查询键该 Hook 的 react-query query key 为[getListDeleted, { pagination, sort, filter, meta }]这意味着只要分页、排序、过滤、meta 参数完全一致react-query 就会命中同一份缓存重复挂载组件或参数未变时不会重复请求反之任何一项参数变化都会产生新的查询条目。你可以利用这一点理解缓存失效行为也可以通过 react-query 的 Query Client 手动失效invalidateQueries对应键来刷新已删除列表。安装该 Hook 位于react-admin/ra-core-ee包中安装方式npm install --save react-admin/ra-core-ee # or yarn add react-admin/ra-core-ee安装后需要在src/App.tsx中把实现了软删除方法的 Data Provider 传给Admin组件即可开始使用// in src/App.tsx import { Admin } from react-admin; import { dataProvider } from ./dataProvider; const App () Admin dataProvider{dataProvider}{/* ... */}/Admin;基础用法展示最近删除的帖子在实际业务中最常见的场景是在自定义页面通常通过CustomRoutes注册中拉取某个资源或全部资源的已删除记录。下面是文档给出的完整示例import { useGetListDeleted } from react-admin/ra-core-ee; const LatestDeletedPosts () { const { data, total, isPending, error } useGetListDeleted( { filter: { resource: posts }, pagination: { page: 1, perPage: 10 }, sort: { field: deleted_at, order: DESC } } ); if (isPending) { return Loading /; } if (error) { return pERROR/p; } return ( h1Latest deleted posts/h1 ul {data.map(deletedRecord li key{deletedRecord.id}{deletedRecord.data.title}/li )} /ul p{data.length} / {total} deleted posts/p / ); };注意观察两点资源名通过filter.resource传递而不是像useGetList那样作为第一个参数传入详见下文对比。useGetListDeleted的参数对象没有独立的resource字段当需要限定某一资源的已删除记录时就在 filter 中带上resource。返回的每条记录是一个已删除记录Deleted Record对象而不是普通记录。其结构如下详见 SoftDeleteDataProvider 文档{ id: 123, // 已删除记录的标识 resource: products, // 原资源名 deleted_at: 2025-06-06T15:32:22Z, // 删除时间ISO 8601 deleted_by: johndoe, // 可选删除人标识 data: { // 删除前的原始记录数据 id: 456, title: Lorem ipsum, teaser: Lorem ipsum dolor sit amet, body: Lorem ipsum dolor sit amet, consectetur adipiscing elit, }, }所以渲染时访问原始字段要用deletedRecord.data.title而非deletedRecord.title。返回值中还包含total当前过滤条件下、不含分页的已删除记录总数用于构建分页控件、refetch手动重新拉取以及meta响应附加元数据等字段。与 useGetList 的关系同款的分页/排序/过滤语义文档明确说明useGetListDeleted对分页、排序、过滤参数的实现方式与useGetList完全一致。因此如果你已经熟悉 useGetList 文档那么这几个参数的语义可以直接复用pagination{ page, perPage }。在 react-admin 的列表场景中默认值通常是{ page: 1, perPage: 25 }useGetList源码中的默认值见 packages/ra-core/src/dataProvider/useGetList.ts。不过对于软删除列表上层组件DeletedRecordsList的默认perPage是10。sort{ field, order }order取ASC或DESC。已删除列表的默认排序字段通常是deleted_at删除时间例如sort{{ field: deleted_at, order: DESC }}用于把最新删除的记录排在最前。filter普通对象作为过滤条件传给 Data Provider。在软删除场景中最常用的过滤条件就是{ resource: posts }这类资源限定。需要特别指出的是useGetListDeleted与useGetList的一个关键差异——query key 的形态useGetList的 query key 是[resource, getList, { pagination, sort, filter, meta }]其中资源名是独立的第一项见 useGetList.tsuseGetListDeleted的 query key 是[getListDeleted, { pagination, sort, filter, meta }]资源名不单独占位而是通过 filter 中的resource字段体现。从 useGetList.ts 源码还可以观察到 react-admin 查询 Hook 的通用模式底层统一通过useQuery执行dataProvider方法把{ data, total, pageInfo, meta }作为查询结果返回并在成功后将小批量记录MAX_DATA_LENGTH_TO_CACHE 100见 useGetList.ts乐观地写入getOne缓存以便后续单条读取命中缓存。useGetListDeleted作为企业版 Hook 遵循同样的 react-query 封装范式这也是它的options参数可以直接对接useQuery全部选项的原因。TypeScript 泛型类型安全的已删除记录useGetListDeleted接受一个泛型参数指定记录类型。传入泛型后返回数组的元素类型为DeletedRecordTypePost[]即每个元素都带有data: Post属性的已删除记录类型系统会自动推断deletedRecord.data.title是stringimport { useGetListDeleted } from react-admin/ra-core-ee; const LatestDeletedPosts () { const { data, total, isPending, error } useGetListDeletedPost( { filter: { resource: posts }, pagination: { page: 1, perPage: 10 }, sort: { field: deleted_at, order: DESC } } ); if (isPending) { return Loading /; } if (error) { return pERROR/p; } return ( h1Latest deleted posts/h1 ul {/* TypeScript knows that data is of type DeletedRecordTypePost[] */} {data.map(deletedRecord li key{deletedRecord.id}{deletedRecord.data.title}/li )} /ul p{data.length} / {total} deleted posts/p / ); };泛型参数让data、total、error等字段的推断更精确在重构和多人协作时能显著减少低级错误。底层契约Data Provider 的 getListDeleted 方法useGetListDeleted只是数据层的消费者真正干活的是 Data Provider 上的getListDeleted方法。软删除要求你的 Data Provider 实现一组专用方法接口形如详见 SoftDeleteDataProvider 文档const dataProviderWithSoftDelete: SoftDeleteDataProvider { ...dataProvider, softDelete: (resource, params: SoftDeleteParams): SoftDeleteResult { const { id, authorId } params; // ... return { data: deletedRecord }; }, // ... getListDeleted: (params: GetListDeletedParams): GetListDeletedResult { const { filter, sort, pagination } params; // ... return { data: deletedRecords, total: deletedRecords.length }; }, restoreOne: (params: RestoreOneParams): RestoreOneResult { /* ... */ }, restoreMany: (params: RestoreManyParams): RestoreManyResult { /* ... */ }, hardDelete: (params: HardDeleteParams): HardDeleteResult { /* ... */ }, hardDeleteMany: (params: HardDeleteManyParams): HardDeleteManyResult { /* ... */ }, };也就是说useGetListDeleted({ pagination, sort, filter, meta })最终会把{ pagination, sort, filter, meta }打包后调用dataProvider.getListDeleted()并期望返回{ data: DeletedRecord[], total: number }。如果你的后端没有现成的软删除能力react-admin/ra-soft-delete提供了两个开箱即用的 Data Provider 构建器BuilderaddSoftDeleteBasedOnResource把所有资源的已删除记录集中存放到一个单独资源中默认资源名为deleted_records。软删除时记录从原资源消失被重建到deleted_records资源中。addSoftDeleteInPlace已删除记录保留在原资源中仅通过deleted_at、deleted_by字段标记为已删除普通查询方法getList、getOne等自动过滤掉这些记录。使用该构建器时需要在配置中列出所有可软删除的资源让getListDeleted知道去哪里找已删除记录// in src/dataProvider.ts import { addSoftDeleteInPlace } from react-admin/ra-soft-delete; import baseDataProvider from ./baseDataProvider; export const dataProvider addSoftDeleteInPlace( baseDataProvider, { posts: {}, comments: { deletedAtFieldName: deletion_date, }, accounts: { deletedAtFieldName: disabled_at, deletedByFieldName: disabled_by, } } );性能提示使用addSoftDeleteInPlace时尽量避免不带resource过滤条件直接调用getListDeleted因为其内部实现是多次getList调用的组合naive 实现可能带来较差性能。建议每个资源各建一个列表通过DeletedRecordsList resource属性限定详见 DeletedRecordsListBase 文档。上层组件与无头控制器useGetListDeleted是底层数据 Hook通常你不会只在一个裸列表里用它。react-admin 软删除体系还提供了一整套上层设施DeletedRecordsList组件直接调用dataProvider.getListDeleted()获取数据并在DataTable中渲染已删除记录内置分页、过滤、排序以及恢复永久删除按钮和点击行查看详情弹窗。它需要手动通过CustomRoutes注册路由// in src/App.js import { Admin, CustomRoutes } from react-admin; import { Route } from react-router-dom; import { DeletedRecordsList } from react-admin/ra-soft-delete; export const App () ( Admin ... CustomRoutes Route path/deleted element{DeletedRecordsList /} / /CustomRoutes /Admin );useDeletedRecordsListControllerHookDeletedRecordsList背后的无头headless控制器。它从 URL 读取列表参数、调用dataProvider.getListDeleted()、准备好修改分页/过滤/排序/选择的回调并返回与ListContext形状一致的控制器对象适合用其他 UI 组件库构建自定义已删除列表页。其参数默认值可供参考debounce 500过滤防抖毫秒数、perPage 10、sort { field: deleted_at, order: DESC }、storeKey undefined详见 useDeletedRecordsListController 文档。此外每个 Data Provider 动词都对应一个独立 Hook供自定义组件直接使用详见 SoftDeleteDataProvider 文档 的 Query and Mutation Hooks 一节Data Provider 方法HookgetListDeleteduseGetListDeleted本文主角getOneDeleteduseGetOneDeletedsoftDelete/softDeleteManyuseSoftDelete / useSoftDeleteManyrestoreOne/restoreManyuseRestoreOne / useRestoreManyhardDelete/hardDeleteManyuseHardDelete / useHardDeleteMany访问控制与安全性与 react-admin 的整体安全模型一致查看已删除记录是受权限管控的操作。当你的authProvider实现了访问控制Access Control时useDeletedRecordsListController以及DeletedRecordsList会以如下参数调用authProvider.canAccess(){ resource: ra-soft-delete, action: list_deleted_records }没有权限的用户会被重定向到 Access Denied 页面恢复按钮对应的权限动作是restore永久删除按钮对应的权限动作是delete调用时会带上当前记录。如果希望允许匿名访问可以设置disableAuthentication属性。这些细节在 useDeletedRecordsListController 文档 中有完整说明。小结useGetListDeleted是 react-admin 软删除体系中读已删除列表的入口 Hook用法上传入{ pagination, sort, filter, meta }参数对象资源通过filter.resource指定第二个可选参数透传给 react-queryuseQueryquery key 为[getListDeleted, { pagination, sort, filter, meta }]。语义上分页/排序/过滤与useGetList完全一致但返回元素是带data字段的已删除记录对象请求meta与响应meta不要混淆。生态上底层依赖 Data Provider 的getListDeleted方法可以通过addSoftDeleteBasedOnResource/addSoftDeleteInPlace构建器快速启用上层可搭配DeletedRecordsList、useDeletedRecordsListController构建完整的管理界面。如果你需要在应用中构建回收站删除记录审计归档恢复等能力useGetListDeleted就是最直接、最符合 react-admin 数据层规范的起点。【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址: https://gitcode.com/gh_mirrors/re/react-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考