前端UI组件【免费下载链接】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 官方仓库中的examples/ra-offline示例应用为主线完整讲解如何为基于 REST/GraphQL API 的 react-admin 单页应用构建离线优先offline-first能力。文章将带你理解两条核心技术路径——用vite-plugin-pwa将应用编译为可离线加载的 Progressive Web App以及通过配置 TanStack Query 的 QueryClient 把查询缓存与待处理的 mutation 持久化到 localStorage从而在网络中断时仍能浏览数据、提交变更并在恢复联网后自动重放。读完本文你将掌握一个可复制的离线方案npm install安装依赖、npm run build npm run preview运行生产构建、用浏览器 DevTools 或手机飞行模式验证离线行为并理解底层源码addOfflineSupportToQueryClient、Service Worker 注入等的工作原理与适用范围。一、示例概览一个演示 offline-first 能力的完整应用examples/ra-offline是 react-admin 官方仓库中专门用于演示离线优先能力的示例应用见 examples/ra-offline/README.md。它做了两件关键的事情使用vite-plugin-pwa将应用构造成一个 Progressive Web AppPWA使应用外壳HTML、JS、CSS、图标等静态资源可以被 Service Worker 预缓存从而在离线环境下也能加载配置 TanStack Query 的QueryClient将查询缓存query cache和待处理的 mutationpending mutations持久化到本地存储localStorage中实现断网可读、断网可写、恢复后重放的离线体验。该示例在功能上是一个极简的博客管理后台只有一个posts资源列表使用ListGuesser自动推断列编辑页使用自定义的PostEdit见 src/App.tsx 与 src/PostEdit.tsx。示例的数据源指向 JSONPlaceholder 这类公共假 REST API因此它更适合作为架构验证与行为演示而非真实数据持久化方案这一点会在局限性一节展开。从目录结构看应用由以下几部分组成src/App.tsx应用入口QueryClient离线配置、持久化 provider 与Admin组件的组装src/sw.ts自定义 Service Worker配合injectManifest策略负责预缓存与离线路由回退src/PostEdit.tsxpost 编辑表单包含ReferenceInput、TextInput等表单控件src/Layout.tsx自定义布局在 react-admin 默认布局上追加 TanStack Query DevToolssrc/index.tsxReact 根节点渲染入口vite.config.tsVite 构建配置含VitePWA插件与 monorepo 内packages/*源码别名public/PWA 所需的图标pwa-192x192.png、pwa-512x512.png、maskable-icon-512x512.png、apple-touch-icon-180x180.png、favicon.ico。二、安装与运行构建生产版本是离线能力生效的前提按照 README 的说明首先安装依赖npm install需要特别注意的是离线模式在 dev 模式下不生效这是vite-plugin-pwa的已知限制。因此必须构建生产版本并用本地服务器预览npm run build npm run preview从 package.json 可以看到构建与预览分别对应 Vite 的vite build和vite preview脚本。生产构建会把 Service Worker 注入到dist产物中浏览器首次访问时完成资源预缓存之后刷新即可在断网环境下加载应用。补充说明虽然vite.config.ts的VitePWA({ devOptions: { enabled: true, type: module, navigateFallback: index.html } })开启了开发模式的 Service Worker 支持但正如 README 明确指出的离线能力仍需以生产构建为验证基线日常调试请直接使用build preview的组合。验证离线行为时可以使用浏览器 DevToolsNetwork 面板勾选 Offline或手机开启飞行模式来模拟断网。README 特别提醒不要试图用 TanStack Query DevTools 来模拟离线——它并不具备这一能力。同时该示例已在 src/Layout.tsx 中通过ReactQueryDevtools initialIsOpen{false} /嵌入了 Query DevTools便于观察缓存状态但离线模拟请一律使用浏览器自身的网络控制。三、离线能力第一支柱vite-plugin-pwa 与自定义 Service Worker3.1 PWA 插件配置解读离线加载应用外壳的能力由VitePWA插件提供vite.config.ts 第 30–70 行关键配置如下registerType: autoUpdateService Worker 更新后自动接管页面用户无需手动刷新确认strategies: injectManifest使用自定义 Service Worker 文件而非 Workbox 生成的默认逻辑配合srcDir: src与filename: sw.ts指定自定义 SW 源码位置injectManifest: { minify: false }关闭注入产物压缩便于调试时阅读生成后的 SW 代码注释中还保留了enableWorkboxModulesLogs的开关样例devOptions: { enabled: true, type: module, navigateFallback: index.html }开发模式启用模块类型 SW并将路由导航回退到index.htmlworkbox: { globPatterns: [**/*.{js,css,html,ico,png,svg}] }预缓存构建产物中的静态资源类型includeAssets额外把favicon.ico、apple-touch-icon-180x180.png、maskable-icon-512x512.png一并预缓存manifest声明 PWA 应用名React-Admin Offline、短名RA Offline、主题色#ffffff以及 192x192 与 512x512 两种尺寸的图标来自public/下的pwa-192x192.png与pwa-512x512.png。index.htmlexamples/ra-offline/index.html中对应的link relapple-touch-icon、link relmask-icon与theme-color元信息与 manifest 中的图标、主题色声明保持了一致共同构成 PWA 的安装与展示要素。3.2 自定义 Service Worker 的离线逻辑injectManifest策略下src/sw.tsexamples/ra-offline/src/sw.ts是应用离线行为的核心import { cleanupOutdatedCaches, createHandlerBoundToURL, precacheAndRoute } from workbox-precaching; import { NavigationRoute, registerRoute } from workbox-routing; declare let self: ServiceWorkerGlobalScope; self.addEventListener(message, (event) { if (event.data event.data.type SKIP_WAITING) self.skipWaiting(); }); // self.__WB_MANIFEST is default injection point precacheAndRoute(self.__WB_MANIFEST); // clean old assets cleanupOutdatedCaches(); // to allow work offline registerRoute(new NavigationRoute(createHandlerBoundToURL(index.html)));其工作方式可以拆解为三点预缓存self.__WB_MANIFEST是 Workbox 注入清单的默认注入点构建时会被替换为需要预缓存的资源列表precacheAndRoute同时完成安装阶段的资源预缓存与请求阶段的缓存命中分发清理旧缓存cleanupOutdatedCaches()会在 SW 更新时删除不属于当前清单的过期缓存避免磁盘膨胀导航路由回退NavigationRoute(createHandlerBoundToURL(index.html))将一切页面导航请求HTML 文档请求回退到index.html。这是 SPA 离线运行的关键——用户无论访问哪个前端路由都能加载应用外壳再由 react-router/react-admin 接管页面渲染自动更新监听SKIP_WAITING消息并调用self.skipWaiting()配合registerType: autoUpdate实现新版本 SW 的自动接管。四、离线能力第二支柱TanStack Query 缓存与 mutation 的本地持久化如果只预缓存了静态资源应用虽能离线打开但数据请求与保存操作依然会因网络失败而报错。ra-offline 的第二个支柱是把 TanStack Query 这一数据层搬到本地。4.1 QueryClient 的离线语义配置在 src/App.tsx 中首先创建了一个带有离线语义的QueryClientconst baseQueryClient new QueryClient({ defaultOptions: { queries: { gcTime: 1000 * 60 * 60 * 24, // 24 hours networkMode: offlineFirst, }, }, });gcTime: 1000 * 60 * 60 * 2424 小时缓存的数据在内存/存储中被垃圾回收前保留一天保证离线期间刷新页面后查询缓存仍可恢复networkMode: offlineFirst这是 TanStack Query 5 提供的网络模式允许查询在无法建立网络连接时先读取本地缓存离线优先而不是直接判失败对于需要写入的操作mutation则进入暂停paused状态等待网络恢复。4.2 为指定资源的 mutation 注册默认函数随后调用 react-admin 5 提供的辅助函数把离线支持挂到指定资源上export const queryClient addOfflineSupportToQueryClient({ queryClient: baseQueryClient, dataProvider, resources: [posts, comments, users], });从 packages/ra-core/src/dataProvider/addOfflineSupportToQueryClient.ts 的实现可以看到它的作用是为每个资源注册 react-admin 默认 mutation 的默认执行函数export const addOfflineSupportToQueryClient ({ dataProvider, resources, queryClient, }: { dataProvider: DataProvider; resources: string[]; queryClient: QueryClient }) { resources.forEach(resource { DATAPROVIDER_MUTATIONS.forEach(mutation { queryClient.setMutationDefaults([resource, mutation], { mutationFn: async (params: any) { const dataProviderFn dataProvider[mutation] as Function; return dataProviderFn.apply(dataProviderFn, ...params); }, }); }); }); return queryClient; };其中DATAPROVIDER_MUTATIONS在 packages/ra-core/src/dataProvider/dataFetchActions.ts 中定义即 react-admin 的五个写操作export const DATAPROVIDER_MUTATIONS [ create, delete, update, updateMany, deleteMany, ];为什么必须注册默认 mutation 函数react-query 官方指南指出要支持持久化离线 mutation例如用户在离线时触发了 mutation、随后离开触发该 mutation 的组件等网络恢复后仍要重放该操作QueryClient 必须知道该 mutation 对应的执行函数mutationFn。addOfflineSupportToQueryClient正是按[resource, mutation]这一组合键把这些默认函数预注册到 QueryClient 上这样即使组件已卸载暂停的 mutation 在恢复后依然能被正确重放。需要理解的一点是resources: [posts, comments, users]是哪些资源参与离线写支持的声明。示例虽然只渲染了posts资源但把数据源中存在的comments、users也一并纳入保证后续扩展资源时无需改动配置。4.3 持久化 provider 与恢复暂停的 mutation接下来把 QueryClient 的缓存与暂停的 mutation 落到 localStorageconst localStoragePersister createAsyncStoragePersister({ storage: window.localStorage, }); export const App () ( PersistQueryClientProvider client{queryClient} persistOptions{{ persister: localStoragePersister }} onSuccess{() { // resume mutations after initial restore from localStorage is successful queryClient.resumePausedMutations(); }} Admin layout{Layout} dataProvider{dataProvider} queryClient{queryClient} disableTelemetry Resource nameposts list{ListGuesser} edit{PostEdit} / /Admin /PersistQueryClientProvider );这一段组装了三层职责createAsyncStoragePersister({ storage: window.localStorage })来自tanstack/query-async-storage-persister负责把缓存序列化写入 localStoragePersistQueryClientProvider来自tanstack/react-query-persist-client在应用启动时从 localStorage 恢复 query 缓存与暂停的 mutation并持续把新缓存写回存储onSuccess回调只有首次从 localStorage 恢复成功后才调用queryClient.resumePausedMutations()把离线期间暂停的写操作重新派发给 dataProvider。这里恢复成功后再重放 mutation的顺序很重要必须先还原完整的缓存状态再重放写操作避免重放时依赖的上下文如关联记录尚未就绪。最后Admin组件通过queryClientprop 显式接收这个已配置好的 QueryClient确保 react-admin 内部的所有查询与变更都走同一份离线语义配置disableTelemetry则关闭了运行时遥测上报。4.4 编辑表单的离线友好设置在 src/PostEdit.tsx 中还有一个值得注意的细节Edit redirectOnError{false}redirectOnError{false}表示当保存请求失败例如离线时 mutation 处于暂停状态、或网络异常时不自动跳转回列表页而是停留在编辑页。这保证了离线编辑场景下的用户路径可控——失败不丢页面配合 mutation 的暂停机制等待网络恢复后自动重放。五、端到端验证如何确认离线方案确实生效在本地完成npm run build npm run preview后按以下步骤即可验证 offline-first 行为首次在线访问打开preview提供的地址等待 Service Worker 完成资源预缓存DevTools → Application → Service Workers 可确认 SW 已激活Cache Storage 中出现预缓存条目模拟断网打开 DevTools → Network 面板勾选 Offline或直接在手机上开启飞行模式并重新加载页面验证可读性断网状态下刷新页面应用外壳与已缓存的数据应正常渲染networkMode: offlineFirst保证查询优先命中本地缓存而非直接报错验证可写性离线状态下编辑一条 post 并保存。由于缓存与暂停的 mutation 已被持久化此时 mutation 会进入 paused 状态写入操作不会立即触发网络错误恢复联网关闭 DevTools 的 Offline或关闭飞行模式PersistQueryClientProvider.onSuccess与resumePausedMutations()会把暂停的写操作重新派发给 dataProvider在 Network 面板中可以看到这些请求随后被真正发出。README 对验证预期做了明确界定由于示例连接的是 JSONPlaceholder 这类公共假 API变更不会被真实持久化但可以在 Network 面板观察到 mutation 请求被发出并且不会触发错误——这正是离线排队、恢复重放行为的可观测证据。六、局限性说明与使用前提README 在最后明确了两条局限使用时必须心中有数开发模式不生效离线能力依赖生产构建产出的 Service Worker 与预缓存清单npm run dev下的体验并不代表真实离线行为请始终以build preview或部署后的站点为验证环境后端不持久化本示例的 dataProvider 指向 JSONPlaceholderjsonDataProvider(https://jsonplaceholder.typicode.com)见 src/App.tsx公共假 API 不会真的保存数据因此离线写入成功只体现在请求重放层面。若要在真实业务中落地 offline-first需要使用支持真实持久化的 dataProvider 与后端如自建 REST/GraphQL 服务合理选择资源清单resources数组与gcTime本示例为 24 小时权衡缓存体积与离线时长需求关注多标签页/多设备场景下的缓存一致性与冲突处理策略。七、把离线方案迁移到自己的 react-admin 项目结合本示例在你自己的项目中复刻 offline-first 的最小步骤是安装相关依赖对应 package.json 中的版本组合如react-admin、tanstack/react-query、tanstack/query-async-storage-persister、tanstack/react-query-persist-client、vite-plugin-pwa在vite.config.ts中引入VitePWA插件配置injectManifest策略与自定义sw.ts可直接参考 examples/ra-offline/vite.config.ts 与 examples/ra-offline/src/sw.ts并补齐public/下的 PWA 图标与index.html的元信息在应用入口组装QueryClientnetworkMode: offlineFirst 合理的gcTime→addOfflineSupportToQueryClient({ queryClient, dataProvider, resources })→createAsyncStoragePersister→PersistQueryClientProvider并在onSuccess中调用queryClient.resumePausedMutations()完整写法见 examples/ra-offline/src/App.tsx对需要失败不跳走的编辑/创建页面设置redirectOnError{false}以生产构建npm run build部署后用浏览器 Offline 模式与飞行模式完成端到端验证。这套方案的关键思想可以概括为一句话Service Worker 解决离线能不能打开应用TanStack Query 的缓存持久化与 mutation 重放解决离线能不能继续用数据、能不能延迟写入。两者结合才构成完整的 offline-first 体验。赞分享前端UI组件【免费下载链接】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点击查看免费下载相关推荐使用 TanStack DB 与 RxDB 构建离线优先Offline-First应用使用 TanStack DB 与 RxDB 构建离线优先Offline First应用 TanStack DB 是内存态响应式客户端存储提供实时查询li数据库NoSQL嵌入式数据库实时数据库Gatsby 离线支持实战用 gatsby-plugin-offline 与 Service Worker 打造 PWAGatsby 离线支持实战用 gatsby plugin offline 与 Service Worker 打造 PWA 如果你用 Lighthouse 审计前端静态站点Web框架oh-my-hermes 审批层级完整指南高危操作的分级审批安全设计oh my hermes 审批层级完整指南高危操作的分级审批安全设计 oh my hermes 的审批层级approval tier是内置于这款 Herm人工智能AI 技能AI 插件AI 评测Agent 工作流创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考