Elementor Query 包elementor/query基于 TanStack Query 的编辑器数据请求封装与版本演进全解【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor在 Elementor 现代编辑器Editor One的 React 体系中服务端状态管理统一收敛在一个轻量封装包elementor/query上。本文以 packages/packages/libs/query/CHANGELOG.md 的版本演进为主轴结合 包源码、README 与编辑器内的真实调用链完整梳理该包的 API 设计、单例 QueryClient 管理机制、默认请求策略以及如何在业务代码中落地分页、缓存失效与数据更新。读完本文你将掌握 Elementor 内部服务端状态的标准写法和从版本记录反推演进脉络的方法。一、从 CHANGELOG 看包的整体定位elementor/query是一个围绕tanstack/react-query的薄封装wrapper目标是把 TanStack Query 的能力以受控的方式暴露给 Elementor 编辑器。它的完整版本历史记录在 packages/packages/libs/query/CHANGELOG.md采用 Conventional Commits 规范维护日志按时间倒序排列。按时间线梳理版本演进版本日期关键变更0.1.02023-06-28首次发布query包新增对 React Query 的支持issue [ED-11193]PR #620.1.1 ~ 0.1.62023-06 ~ 2023-11仅版本号 bumpVersion bump only无功能性变更0.2.02024-01-29新特性为editor-site-navigation的 pages 面板引入分页pagination能力PR #1540.2.1 ~ 0.2.22024-07 ~ 2024-08版本号 bump0.2.3—修复package.json的exports字段Fix package.json exports field0.2.4—更新依赖Update dependenciesCHANGELOG 揭示出两个事实其一该包是一个平台底座型依赖多数版本只是跟随上游更新其二真正影响业务的是 0.2.0 引入的分页支持和 0.2.3 对exports字段的修复——后者直接关系到包在 ESM/CJS 双格式下的导入稳定性。二、核心 API源码级解读包的实现非常精简全部逻辑集中在 packages/packages/libs/query/src/index.ts 一个文件中import { QueryClient } from tanstack/react-query; export { useQuery, useInfiniteQuery, useMutation, useIsMutating, useQueryClient, QueryClient, QueryClientProvider, type UseQueryResult, } from tanstack/react-query; let queryClient: QueryClient | undefined; export function getQueryClient(): QueryClient { if ( ! queryClient ) { throw new Error( Query client is not created yet. ); } return queryClient; } export function createQueryClient() { if ( queryClient ) { throw new Error( Query client is already created. ); } queryClient new QueryClient( { defaultOptions: { queries: { refetchOnWindowFocus: false, refetchOnReconnect: false, }, }, } ); return queryClient; }2.1 全量复出口Hooks 与类型包直接从tanstack/react-query复出re-export了业务层最常用的 APIuseQuery/useInfiniteQuery查询数据后者支持分页游标useMutation执行写入型操作创建、更新、删除useIsMutating观察当前是否有进行中的 mutationuseQueryClient在组件树中获取当前QueryClient实例QueryClient/QueryClientProvider客户端实例类型与 Provider 组件type UseQueryResult查询返回值的类型。业务代码只需从elementor/query导入而不必直接依赖tanstack/react-query从而将第三方库锁定在包的内部便于统一升级与替换。2.2 单例 QueryClientcreate 与 get 的成对约束模块级变量let queryClient维护了一个进程级单例createQueryClient()首次创建实例若已存在则抛出Query client is already created.保证整个编辑器只存在一个客户端getQueryClient()返回已创建的实例若尚未创建则抛出Query client is not created yet.用于在 React 组件树之外如纯工具函数、事件回调安全访问客户端。这种“创建一次、全局复用”的设计与 React 应用中每个 Provider 各自 new 一个 Client 的常见写法不同目的是在编辑器这种长期存活的 SPA 环境中统一缓存状态、避免多实例导致的缓存数据分叉。2.3 默认策略关闭窗口聚焦与断线重连时的自动刷新createQueryClient()通过defaultOptions.queries为所有查询设置了两个全局默认值refetchOnWindowFocus: false窗口重新获得焦点时不自动重新请求refetchOnReconnect: false网络恢复时不自动重新请求。从源码结构看这是针对编辑器场景的刻意取舍编辑器面板数据以用户主动操作为主关闭自动刷新可避免拖拽、输入过程中因窗口焦点变化引发意外请求。业务层仍可通过useQuery的局部选项覆盖这些默认值例如 use-user.ts 中显式设置了staleTime: 30 * 60 * 1000让用户信息在 30 分钟内直接命中缓存。三、使用指南从 README 示例到完整可运行代码README 给出了最简用法创建客户端 → 用QueryClientProvider注入 → 在组件中调用useQuery。下面将其扩写为完整可复制的示例import { createQueryClient, QueryClientProvider, useQuery } from elementor/query; const queryClient createQueryClient(); const App () ( QueryClientProvider client{ queryClient } MyComponent / /QueryClientProvider ); const MyComponent () { const { data: todos, isLoading } useQuery( { queryKey: todos, queryFn: () fetch( /todos ).then( ( res ) res.json() ), } ); if ( isLoading ) { return divLoading.../div; } return todos.map( ( todo ) div key{ todo.id }{ todo.title }/div ); };要点说明queryKey支持字符串或数组。从编辑器现有代码看团队惯例是使用命名空间数组例如[ site-navigation, posts, postTypeSlug ]见 use-posts.ts便于按前缀批量失效queryFn可以是任意返回 Promise 的函数不限于fetch编辑器内大量使用自定义的getRequest/getSettings/getUser等 API 封装函数包声明了peerDependencies: { react: ^18.3.1 }使用时需确保宿主环境为 React 18.3 及以上。3.1 内部约定__前缀不可依赖README 特别以警告块 [!WARNING]声明凡是以双下划线__开头的函数或变量均视为内部实现可能在任何版本中无通知变更第三方开发者不得访问或依赖。这一约定属于包 API 稳定性的“红线”在升级依赖前应检查代码中是否引用了此类符号。四、编辑器内的真实调用链分页、缓存失效与写入CHANGELOG 0.2.0 提到的“pages 面板分页”特性其实现正落在editor-site-navigation模块中是理解该包实战价值的最佳样本。4.1 无限滚动分页useInfiniteQueryuse-posts.ts 完整演示了分页数据流的四个要素export function usePosts( postTypeSlug: Slug ) { const query useInfiniteQuery( { queryKey: postsQueryKey( postTypeSlug ), queryFn: ( { pageParam 1 } ) getRequest( postTypeSlug, pageParam ), initialPageParam: 1, getNextPageParam: ( lastPage ) { return lastPage.currentPage lastPage.totalPages ? lastPage.currentPage 1 : undefined; }, } ); return { ...query, data: { posts: flattenData( query.data ), total: query.data?.pages[ 0 ]?.totalPosts ?? 0 } }; }initialPageParam: 1声明起始页码getNextPageParam依据当前页与总页数的比较返回下一页返回undefined时表示没有更多数据最后通过flattenData把分页的pages数组拍平为帖子列表并暴露total总数——这是对useInfiniteQuery返回结构的一次典型适配封装。4.2 查询 失效useQuery 与 invalidateQueries 的配对读侧与写侧通过相同的queryKey约定联动use-homepage.ts 用settingsQueryKey() [ site-navigation, homepage ]查询设置use-homepage-actions.ts 在useMutation的onSuccess回调中调用queryClient.invalidateQueries( { queryKey } )使对应缓存失效随后onSuccess里再以{ exact: true }精确刷新——先让旧缓存失效、再按需重取保证界面与服务器状态一致。4.3 编辑器启动时注入客户端editor/src/start.tsx 展示了应用引导流程在编辑器启动入口调用createQueryClient()创建单例并随QueryClientProvider注入根组件树之后所有模块共享同一缓存实例。五、工程化与发布配置package.json 透露了该包的工程化细节构建工具为tsupbuild脚本使用仓库根级的tsup.build.ts配置产物同时输出dist/index.jsCJS、dist/index.mjsESM与dist/index.d.ts类型声明exports字段按types/import/require三路分别映射——这正是 CHANGELOG 0.2.3 修复的内容修复后 Node 与打包器在 ESM/CJS 混用场景下不再解析失败当前版本号 4.4.0包已发布到 npmprivate: falsepublishConfig.access: public许可为 GPL-3.0-or-later。六、总结与升级建议综合 CHANGELOG、源码与消费方代码可以得到三个结论elementor/query是 Elementor 编辑器的服务端状态底座设计哲学是“薄封装 单例客户端 保守默认策略”业务复杂度由各模块自行通过 Hook 适配承担版本日志中的 0.2.0分页与 0.2.3exports 修复是两次实质性变更其余版本均为依赖跟随升级该包时应重点回归分页面板、缓存失效链路以及 ESM 导入场景同时避免使用__前缀的内部符号以保证在依赖更新后代码仍可正常编译运行。若要在自己的业务代码中复刻这套模式建议沿用以[ 模块名, 资源名, 参数 ]组织queryKey、以onSuccess invalidateQueries联动写读两侧、用staleTime控制缓存有效期的既有实践这些范式在仓库的editor-site-navigation模块中均有现成实现可供参考。【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考