injectQuery
概述
TypeScript
1function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): DefinedCreateQueryResult<TData, TError>;2function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): CreateQueryResult<TData, TError>;3function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): CreateQueryResult<TData, TError>;() => DefinedInitialDataOptions→DefinedCreateQueryResult：当injectQueryFn返回的选项中已知定义了initialData时，将选用此重载，因此生成的data信号永远不会为undefined（除非某个select修改了TData，使其包含undefined）。() => UndefinedInitialDataOptions→CreateQueryResult：注入一个查询：一种声明式依赖，用于绑定到唯一键的异步数据源。() => CreateQueryOptions→CreateQueryResult：此重载接受通用的 CreateQueryOptions 类型，而非上述与initialData相关的重载，因此无法从调用位置推断data是否已定义——当你在自定义辅助函数中封装injectQuery并转发调用方提供的选项时，该重载非常有用。
调用签名
TypeScript
1function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): DefinedCreateQueryResult<TData, TError>;定义于：packages/angular-query-experimental/src/inject-query.ts:72
当 injectQueryFn 返回的选项中已知定义了 initialData 时，将选用此重载，因此生成的 data 信号永远不会为 undefined（除非某个 select 修改了 TData，使其包含 undefined）。
类型参数
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
参数
injectQueryFn
() => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
返回要使用的 DefinedInitialDataOptions 的函数——即所有可传入 injectQuery 的参数，且其中 initialData 已知已定义。该函数类似于 Angular 中的 computed，它在响应式上下文中运行，因此其内部读取的信号（如 queryKey、enabled 等）会驱动查询。
options?
额外配置项
返回值
DefinedCreateQueryResult<TData, TError>
查询结果，其类型确保 data 永远不会为 undefined（除非某个 select 修改了 TData，使其包含 undefined）。
参见
- https://tanstack.com/query/latest/docs/framework/angular/guides/queries
- queryOptions，用于在
injectQuery和queryClient.fetchQuery等命令式 API 之间共享这些选项。
示例
angular-ts
1@Component({2 selector: 'posts',3 template: `4 <!-- `postsQuery.data()` is `Post[]`, never `undefined`, thanks to `initialData` — even if a5 refetch fails, so the list stays visible alongside the error. -->6 @if (postsQuery.isError()) {7 <span>Error: {{ postsQuery.error()?.message }}</span>8 }9 <ul>10 @for (post of postsQuery.data(); track post.id) {11 <li>{{ post.title }}</li>12 }13 </ul>14 `,15})16export class Posts {17 readonly postsQuery = injectQuery(() => ({18 queryKey: ['posts'],19 queryFn: fetchPosts,20 initialData: [],21 }))22}调用签名
TypeScript
1function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): CreateQueryResult<TData, TError>;定义于：packages/angular-query-experimental/src/inject-query.ts:158
注入一个查询：一种声明式依赖，用于绑定到唯一键的异步数据源。
类型参数
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
参数
injectQueryFn
() => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
返回要使用的 UndefinedInitialDataOptions 的函数——即所有可传入 injectQuery 的参数。该函数类似于 Angular 中的 computed，它在响应式上下文中运行，因此其内部读取的信号（如 queryKey、enabled 等）会驱动查询。
options?
额外配置项
返回值
CreateQueryResult<TData, TError>
查询结果。若无缓存数据可供显示，则 status() 为 'pending'；若上一次拉取尝试失败，则为 'error'；若查询已有数据可供显示，则为 'success'。isPending/isSuccess/isError 是为方便起见提供的类型守卫方法。
参见
- https://tanstack.com/query/latest/docs/framework/angular/guides/queries
- queryOptions，用于在
injectQuery和queryClient.fetchQuery等命令式 API 之间共享这些选项。
示例
angular-ts
1@Component({2 selector: 'posts',3 template: `4 @if (postsQuery.isPending()) {5 Loading...6 } @else if (postsQuery.isError()) {7 <span>Error: {{ postsQuery.error()?.message }}</span>8 } @else {9 <ul>10 @for (post of postsQuery.data(); track post.id) {11 <li>{{ post.title }}</li>12 }13 </ul>14 }15 `,16})17export class Posts {18 readonly postsQuery = injectQuery(() => ({19 queryKey: ['posts'],20 queryFn: fetchPosts,21 }))22}与 Angular 中的 computed 类似，传给 injectQuery 的函数在响应式上下文中运行。在下方示例中，当 filter 信号变为真值时，查询将自动启用并执行；当 filter 信号再次变为假值时，查询将被禁用。
angular-ts
1@Component({2 selector: 'posts',3 template: `4 <input [ngModel]="filter()" (ngModelChange)="filter.set($event)" />5 @if (postsQuery.isPending()) {6 Loading...7 } @else if (postsQuery.isError()) {8 <span>Error: {{ postsQuery.error()?.message }}</span>9 } @else {10 <ul>11 @for (post of postsQuery.data(); track post.id) {12 <li>{{ post.title }}</li>13 }14 </ul>15 }16 `,17})18export class Posts {19 readonly filter = signal('')20 21 readonly postsQuery = injectQuery(() => ({22 queryKey: ['posts', this.filter()],23 queryFn: () => fetchPosts(this.filter()),24 // Signals can be combined with expressions25 enabled: !!this.filter(),26 }))27}调用签名
TypeScript
1function injectQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(injectQueryFn: () => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>, options?: InjectQueryOptions): CreateQueryResult<TData, TError>;定义于：packages/angular-query-experimental/src/inject-query.ts:184
此重载接受通用的 CreateQueryOptions 类型，而非上述与 initialData 相关的重载，因此无法从调用位置推断 data 是否已定义——当你在自定义辅助函数中封装 injectQuery 并转发调用方提供的选项时，该重载非常有用。
类型参数
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
参数
injectQueryFn
() => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>
返回查询选项的函数。该函数类似于 Angular 中的 computed，它在响应式上下文中运行，因此其内部读取的信号（如 queryKey、enabled 等）会驱动查询。
options?
额外配置项
返回值
CreateQueryResult<TData, TError>
查询结果。
参见
https://tanstack.com/query/latest/docs/framework/angular/guides/queries
参数
injectQueryFn
() => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>
返回查询选项的函数。该函数类似于 Angular 中的 computed，它在响应式上下文中运行，因此其内部读取的信号（如 queryKey、enabled 等）会驱动查询。
injectQueryFn 的属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled? |
| false | true | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean) |
true |
将其设为 false 或返回 false 的函数，可禁用查询挂载或查询键变更时的自动重新拉取。如需重新拉取查询，请使用 refetch 实例返回的 refetch 方法。接受布尔值或返回布尔值的函数。 |
gcTime? |
number |
undefined |
未使用/非活跃缓存数据在内存中保留的毫秒数。当某个查询的缓存变为未使用或非活跃状态后，该缓存数据将在该持续时间后被垃圾回收。若指定了多个垃圾回收时间，则采用最长的那个。设为 Infinity 将禁用垃圾回收。默认为 5 * 60 * 1000（5 分钟），服务端渲染（SSR）期间则为 Infinity。注意：受 setTimeout 的 32 位有符号整数延迟限制，最大允许时间为约 24 天——参见 timeoutManager.setTimeoutProvider 获取变通方案。 |
initialData? |
TQueryFnData | (() => TQueryFnData | undefined) |
undefined |
若设置该值，它将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，该函数将在共享/根查询初始化期间仅执行一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 staleTime。initialData 会被持久化到缓存中。 |
initialDataUpdatedAt? |
number | (() => number | undefined) |
undefined |
若设置该值，它将作为 initialData 本身最后更新的时间（毫秒）。 |
maxPages? |
number |
undefined |
无限查询数据中最多存储的页数。 |
meta? |
Record<string, unknown> |
undefined |
存储在每个查询上的额外负载。使用此属性传递可在其他位置使用的附加信息。 |
networkMode? |
"online" | "always" | "offlineFirst" |
'online' |
控制查询是否可在当前网络连接状态下运行。详见 网络模式。 |
notifyOnChangeProps? |
| ( | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | "all" | (() => | "all" | ( | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | undefined) |
undefined |
若设置该值，组件仅在所列属性发生变更时重新渲染。设为 ['data', 'error'] 时，组件仅在 data 或 error 属性变更时重新渲染；设为 'all' 时，组件将在任意查询更新时重新渲染；设为函数时，该函数将用于计算需监听的属性列表。默认为 undefined，此时会自动追踪属性访问，并仅在被追踪属性变更时重新渲染。 |
persister? |
(queryFn: (context: object) => TQueryFnData | Promise<TQueryFnData>, context: object, query: Query) => TQueryFnData | Promise<TQueryFnData> |
undefined |
此选项可用于将查询结果持久化至外部存储，从而绕过实际调用 queryFn 的需要。适用于跨服务端/客户端边界持久化查询数据等场景。 |
placeholderData? |
| NonFunctionGuard<TQueryFnData> | ((previousData: NonFunctionGuard<TQueryFnData> | undefined, previousQuery: | Query<NonFunctionGuard<TQueryFnData>, TError, NonFunctionGuard<TQueryFnData>, TQueryKey> | undefined) => NonFunctionGuard<TQueryFnData> | undefined) |
undefined |
若设置该值，它将作为此特定查询观察者在查询仍处于 loading 数据状态且未提供 initialData 时的占位数据。 |
queryFn? |
| typeof skipToken | ((context: object) => TQueryFnData | Promise<TQueryFnData>) |
undefined |
查询用于请求数据的函数。必需，除非已通过 queryClient.setQueryDefaults 或 queryClient.setDefaultOptions 设置了默认查询函数。接收一个 QueryFunctionContext。必须返回一个 Promise，该 Promise 要么解析出数据，要么抛出错误。数据不能为 undefined。 |
queryHash? |
string |
undefined |
queryKey 的哈希形式，由 queryKeyHashFn（或默认哈希函数）计算得出。内部用作实际缓存键。 |
queryKey |
TQueryKey & object |
undefined |
此查询所用的查询键。查询键将被哈希为稳定哈希值。更多信息请参阅 查询键。只要 enabled 未设为 false，该键变更时查询将自动更新。 |
queryKeyHashFn? |
(queryKey: TQueryKey) => string |
undefined |
若指定，该函数将用于将 queryKey 哈希为字符串。 |
refetchInterval? |
| number | false | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => number | false | undefined) |
false |
若设为数字，查询将以该毫秒频率持续重新拉取。若设为函数，该函数将使用最新数据和查询来计算频率。 |
refetchIntervalInBackground? |
boolean |
false |
若设为 true，查询将在标签页/窗口处于后台时继续重新拉取。 |
refetchOnMount? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean | "always") |
true |
若设为 true，当数据过期时，查询将在挂载时重新拉取。若设为 false，将禁用同一查询的额外实例触发后台重新拉取。若设为 'always'，查询将在挂载时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。 |
refetchOnReconnect? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean | "always") |
undefined |
若设为 true，当数据过期时，查询将在重新连接网络时重新拉取。若设为 false，查询将不在重新连接时重新拉取。若设为 'always'，查询将在重新连接时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。默认为 true，除非 networkMode 为 'always'。 |
refetchOnWindowFocus? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean | "always") |
true |
若设为 true，当数据过期时，查询将在窗口获得焦点时重新拉取。若设为 false，查询将不在窗口获得焦点时重新拉取。若设为 'always'，查询将在窗口获得焦点时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。 |
retry? |
| number | false | true | ((failureCount: number, error: TError) => boolean) |
undefined |
若为 false，失败的查询默认不重试。若为 true，失败的查询将无限重试。若设为整数（例如 3），失败的查询将重试直至失败次数达到该数值。若设为函数 (failureCount, error) => boolean，失败的查询将重试直至该函数返回 false。客户端默认为 3，服务端默认为 0。 |
retryDelay? |
number | ((failureCount: number, error: TError) => number) |
undefined |
此函数接收一个 retryAttempt 整数和实际的 Error，并返回下次尝试前应延迟的毫秒数。类似 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 的函数应用指数退避策略；类似 attempt => attempt * 1000 的函数应用线性退避策略。默认为一个应用指数退避策略的函数，上限为 30 秒。 |
retryOnMount? |
| false | true | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean) |
true |
若设为 false，包含错误的查询在挂载时将不会重试。若设为函数，该函数将接收查询并计算该值。 |
select? |
(data: TQueryFnData) => TData |
undefined |
此选项可用于转换或选取查询函数返回数据的一部分。它会影响返回的 data 值，但不影响存储在查询缓存中的内容。select 函数仅在 data 发生变更，或 select 函数自身引用发生变更时执行。为优化性能，请对函数进行记忆化处理，使其引用在多次调用间保持稳定。 |
staleTime? |
| number | "static" | ((query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => number | "static") |
0 |
数据被视为过期前的毫秒数。若设为 Infinity，数据将永不被视为过期。若设为 'static'，数据将永不被视为过期。若设为函数，该函数将接收查询并计算 staleTime。 |
structuralSharing? |
boolean | ((oldData: unknown, newData: unknown) => unknown) |
true |
设为 false 可禁用查询结果间的结构共享。设为接收新旧数据并返回同类型解析后数据的函数，可实现自定义结构共享逻辑。 |
throwOnError? |
| false | true | ((error: TError, query: Query<TQueryFnData, TError, TQueryFnData, TQueryKey>) => boolean) |
false |
是否应抛出错误而非设置 error 属性。若设为 true 或 suspense 为 true，所有错误都将抛出至错误边界。若设为 false 且 suspense 为 false，错误将作为状态返回。若设为函数，该函数将接收错误和查询，并应返回一个布尔值，指示是否在错误边界中显示错误（true）或作为状态返回错误（false）。 |
选项？
其他配置项
options 属性
| 属性 | 类型 | 描述 |
|---|---|---|
injector? |
Injector |
创建查询所用的 Injector。若未提供此选项，则将使用当前注入上下文（通过 inject 获取）。 |
返回值
CreateQueryResult<TData, TError>
查询结果。