TanStack Query for AngularCreateQueryOptions 查询选项接口深度解析【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query本文以 docs/framework/angular/reference/interfaces/CreateQueryOptions.md 参考文档为主体结合tanstack/angular-query-experimental与tanstack/query-core的源码实现讲清CreateQueryOptions这一 Angular Query 核心查询选项接口的类型继承链、泛型参数含义、全部可用配置项及默认值以及它在injectQuery、queryOptions等实际 API 中的消费方式。读完本文你可以准确理解该接口为何移除suspense选项、如何编写类型安全的查询选项并掌握各配置项的语义与默认行为。一、CreateQueryOptions 的定位与定义位置CreateQueryOptions是 Angular Query包名tanstack/angular-query-experimental中描述“一个可创建create查询全部配置项”的类型接口。参考文档明确给出其定义位置与继承关系Defined in: packages/angular-query-experimental/src/types.ts:35 Extends:OmitKeyofCreateBaseQueryOptionsTQueryFnData,TError,TData,TQueryFnData,TQueryKey,suspense在源码中可以逐字印证这一点types.ts 第 35–43 行即export interface CreateQueryOptions TQueryFnData unknown, TError DefaultError, TData TQueryFnData, TQueryKey extends QueryKey QueryKey, extends OmitKeyof CreateBaseQueryOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey, suspense {}注意两个关键实现细节继承的是OmitKeyofCreateBaseQueryOptions..., suspense即在父类型基础上精确剔除了suspense一个属性。OmitKeyof工具类型定义在 query-core/src/types.ts与标准Omit不同它额外允许对“任意字符串键”做安全省略TStrictly extends safely分支这是为了兼容泛型展开后键类型不完全确定的场景。继承链上父接口的第 4 个类型参数被固定填充为TQueryFnData。对照 types.ts 第 21–33 行CreateBaseQueryOptions有 5 个泛型参数其中第 4 个是TQueryData而CreateQueryOptions只有 4 个因此在向下传递时把TQueryData直接写死为TQueryFnData——这意味着对普通非无限滚动查询而言“缓存中的数据形状”与“queryFn 返回的原始数据形状”是同一个。为什么移除suspensesuspense是 React 特有的挂起机制。在 query-core 的 QueryObserverOptions 定义 中其注释为“If set totrue, the query will suspend whenstatus pendingand throw errors whenstatus error. Defaults tofalse.”。Angular 的查询通过injectQuery返回信号Signal化的结果对象来消费状态并不存在 React 式 Suspense 边界因此 Angular 包在类型层面直接移除该选项避免开发者误以为可用。从源码结构看CreateInfiniteQueryOptionstypes.ts 第 75–90 行对InfiniteQueryObserverOptions同样做了OmitKeyof..., suspense处理二者保持一致的设计策略。二、完整类型继承链CreateQueryOptions并非孤立接口其能力来自一条清晰的继承链每一环均可在仓库源码中查证CreateQueryOptions (angular-query-experimental/src/types.ts:35) └─ OmitKeyofCreateBaseQueryOptions..., suspense └─ CreateBaseQueryOptions (angular-query-experimental/src/types.ts:21) └─ QueryObserverOptions (query-core/src/types.ts:315) └─ WithRequiredQueryOptions, queryKey └─ QueryOptions (query-core/src/types.ts:231)CreateBaseQueryOptions定义在 types.ts 第 21–33 行extends QueryObserverOptionsTQueryFnData, TError, TData, TQueryData, TQueryKey本身不添加成员。参考文档 CreateBaseQueryOptions.md 描述了它与本接口唯一的不同保留 5 个泛型参数多出TQueryData且不剔除suspense。QueryObserverOptions定义在 query-core/src/types.ts 第 315 行起在QueryOptions基础上要求queryKey必填WithRequiredQueryOptions, queryKey并补充了enabled、staleTime、refetchInterval等观察层选项。QueryOptions定义在 query-core/src/types.ts 第 231–281 行承载retry、gcTime、queryFn、initialData等基础配置。这条链也解释了参考文档中 Extends 一节为何把父类型写成OmitKeyofCreateBaseQueryOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey, suspense的形式——第 4 个实参TQueryFnData就是 Angular 层对TQueryData的固定绑定。三、泛型参数逐一解读参考文档列出了CreateQueryOptions的 4 个类型参数结合 types.ts 第 35–39 行 的默认值与约束类型参数默认值约束含义TQueryFnDataunknown无查询函数queryFn返回的原始数据类型也是缓存中存储的数据类型因TQueryData被固定为TQueryFnDataTErrorDefaultError无错误类型。DefaultError来自 query-coretypes.ts 第 45–49 行未通过模块增强声明Register.defaultError时即为ErrorTDataTQueryFnData无最终对外暴露的数据类型。当配置了select选择器时TData与TQueryFnData不同结果对象上的data即为TDataTQueryKeyQueryKeyextends QueryKey查询键类型默认为ReadonlyArrayunknown允许收窄为具体元组如[post, number]以获得精确推断这些参数并非仅用于展示它们会一路传递到QueryObserverOptions进而约束queryFn、select、enabled、staleTime等选项的签名。例如enabled?: QueryBooleanOptionTQueryFnData, TError, TData, TQueryKeyquery-core/src/types.ts 第 332 行即允许传一个接收Query实例并返回boolean的函数。四、可用配置项全览继承自 QueryObserverOptions / QueryOptionsCreateQueryOptions自身没有任何声明成员extends ... {}为空因此它的“配置项面”完全等于父类型去掉suspense后的集合。按来源分两层列出默认值均以 query-core 源码注释为准4.1 观察层选项来自 QueryObserverOptions选项类型默认值说明摘自源码注释enabledboolean \| (query) booleantrue设为false可禁用挂载/键变化时的自动拉取types.ts:332staleTimenumber \| static \| (query) ...0数据新鲜期毫秒设为Infinity永不过期types.ts:339refetchIntervalnumber \| false \| (query) ...false设置后按该频率毫秒持续后台拉取types.ts:345refetchIntervalInBackgroundbooleanfalse标签页/窗口处于后台时是否继续refetchInterval拉取types.ts:355refetchOnWindowFocusboolean \| always \| (query) ...true窗口聚焦时若数据过期则重新拉取always表示总是拉取types.ts:363refetchOnReconnectboolean \| always \| (query) ...truenetworkMode为always时除外网络重连时的拉取策略types.ts:376refetchOnMountboolean \| always \| (query) ...true实例挂载时对已有查询的后台拉取策略types.ts:389retryOnMountboolean \| (query) booleantrue挂载时若查询带有错误是否自动重试types.ts:400notifyOnChangeProps属性名数组 |all| 函数追踪属性访问控制哪些属性变化才触发结果通知types.ts:408throwOnErrorboolean \| (error, query) booleanfalse是否将错误抛出而非放入error属性。在 Angular 中该机制由createBaseQuery在订阅回调里落地命中shouldThrowError(observer.options.throwOnError, ...)时会ngZone.onError.emit(state.error)并throwcreate-base-query.ts 第 129–139 行select(data: TQueryData) TData无对缓存数据做变换/取子集data的类型随即变为TDatatypes.ts:420placeholderData值或函数无无initialData且处于加载态时占位数据types.ts:430suspense——本接口已剔除见第一节4.2 基础层选项来自 QueryOptions选项类型默认值说明queryKeyTQueryKey必填查询唯一标识由WithRequiredQueryOptions, queryKey强制types.ts:322-L325queryFnQueryFunctionTQueryFnData \| SkipToken无数据获取函数接收{ client, queryKey, signal, meta, pageParam? }上下文QueryFunctionContext 定义retry/retryDelay布尔、数字或函数由QueryClient默认值决定失败重试策略types.ts:244-L245networkModeonline \| always \| offlineFirst由客户端默认值决定网络模式并联动refetchOnReconnect的默认值gcTimenumber由客户端默认值决定缓存数据成为未使用/非活动后在内存中保留的毫秒数Infinity禁用垃圾回收types.ts:253persisterQueryPersister无包装queryFn的持久化钩子types.ts:255queryHash/queryKeyHashFn字符串 / 函数由 key 自动计算自定义缓存哈希types.ts:256-L258initialData值或() T \| undefined无初始数据可结合initialDataUpdatedAttypes.ts:259-L260structuralSharingboolean \| 函数true结果间的结构化共享types.ts:267-L269behaviorQueryBehavior无自定义查询行为metaRecordstring, unknown无附加元数据载荷types.ts:276maxPagesnumber无主要面向无限查询的页数上限普通查询一般不涉及提示QueryClient的defaultQueryOptions会为未显式提供的选项填充默认值。在 Angular 实现中这一步发生在响应式管道里见第五节因此上表“由客户端默认值决定”的项最终取值取决于你在provideAngularQuery中传入的QueryClient配置。五、CreateQueryOptions 的消费方式与运行时机制该接口在 Angular 包中主要服务于两处 APIinjectQuery的第三个重载与queryOptions系列类型。5.1 在injectQuery中的三个重载injectQuery在 inject-query.ts 中提供三个签名对应参考文档 injectQuery.md 的三份调用签名传入DefinedInitialDataOptions必有initialData→ 返回DefinedCreateQueryResult传入UndefinedInitialDataOptionsinitialData可为 undefined→ 返回CreateQueryResult传入CreateQueryOptions无initialData约束→ 返回CreateQueryResult。后两个选项类型的定义位于 query-options.tsUndefinedInitialDataOptions直接CreateQueryOptions { initialData?: ... }UnusedSkipTokenOptions用OmitKeyofCreateQueryOptions, queryFn排除SkipToken后重写queryFn——可见CreateQueryOptions正是这些组合类型的底座。官方文档给出的基础用法示例来自 injectQuery.mdclass ServiceOrComponent { query injectQuery(() ({ queryKey: [repoData], queryFn: () this.#http.getResponse(https://api.github.com/repos/tanstack/query), })) }响应式用法示例——回调中的信号表达式会被追踪filter变化为真值时查询自动启用回退为假值时禁用class ServiceOrComponent { filter signal() todosQuery injectQuery(() ({ queryKey: [todos, this.filter()], queryFn: () fetchTodos(this.filter()), // Signals can be combined with expressions enabled: !!this.filter(), })) }5.2 源码中的运行时链路createBaseQuerycreate-base-query.ts是injectQuery与injectInfiniteQuery的共同底座它展示了选项对象如何被消费用户传入的optionsFn在computed中执行queryClient.defaultQueryOptions(optionsFn())第 58–64 行因此传入的函数会在 Angular 响应式上下文中运行其中读取的每个信号都成为依赖信号变化即触发选项重算默认化后的选项通过effect中的observer.setOptions(defaultedOptions)交给QueryObserver第 89–106 行订阅通过ngZone.runOutsideAngular建立状态变更再用ngZone.run回注到resultFromSubscriberSignal第 108–154 行期间同步维护 Angular 的PENDING_TASKSfetchStatus fetching时pendingTasks.add()使路由导航等机制能正确等待查询。这段实现同时解释了 4.1 表中throwOnError的落地路径以及为何suspense在 Angular 中被移除——错误处理与“等待”分别由错误抛出和 pending tasks 机制承担而非挂起 UI。5.3queryOptions辅助函数跨组件复用选项CreateQueryOptions也是queryOptions()辅助函数三类重载UndefinedInitialDataOptions/UnusedSkipTokenOptions/DefinedInitialDataOptions的共同基类型定义见 query-options.ts 第 76–171 行。该函数运行时只做透传return options价值在于类型层面返回值的queryKey会被打上QueryKeyWithDataTag数据标签query-core/src/types.ts 第 82–88 行从而让queryClient.getQueryData(queryKey)获得精确类型。官方指南 query-options.md 给出的典型用法import { queryOptions, noop } from tanstack/angular-query-experimental Injectable({ providedIn: root }) export class QueriesService { private http inject(HttpClient) post(postId: number) { return queryOptions({ queryKey: [post, postId], queryFn: () { return lastValueFrom( this.http.getPost( https://jsonplaceholder.typicode.com/posts/${postId}, ), ) }, }) } } // 组件/服务中使用 postId input.required({ transform: numberAttribute }) queries inject(QueriesService) postQuery injectQuery(() this.queries.post(this.postId())) queryClient.query(this.queries.post(23)).catch(noop) queryClient.setQueryData(this.queries.post(42).queryKey, newPost)select同样保证类型贯通// query.data 的类型是 select 的返回类型而不是 queryFn 的返回类型 queries inject(QueriesService) query injectQuery(() ({ ...groupOptions(1), select: (data) data.title, }))六、小结CreateQueryOptions定义于 packages/angular-query-experimental/src/types.ts 第 35 行是CreateBaseQueryOptions去除suspense后的收窄版本4 个泛型参数TQueryFnData、TError、TData、TQueryKey分别约束原始数据、错误、选择后数据与查询键的类型推断。它的全部配置能力继承自 query-core 的QueryObserverOptions→QueryOptions涵盖enabled、staleTime、refetchInterval、refetchOnWindowFocus、retry、gcTime、select、initialData、throwOnError等选项及其默认值。它是injectQuery重载与queryOptions辅助函数的类型底座运行时选项在createBaseQuery的computed响应式管道中经queryClient.defaultQueryOptions默认化后交给QueryObserver这也是 Angular Query 支持信号驱动、响应式查询选项的根本机制。如需继续深入可参阅参考文档目录下的 CreateBaseQueryOptions、CreateInfiniteQueryOptions、InjectQueryOptions 以及 injectQuery 等关联页面。【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
