Important Defaults

要点（模型写的）

模型写的

背景主张方法设置结果分析局限

Out of the box, TanStack Query is configured with aggressive but sane defaults. Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user. Keep them in mind as you continue to learn and use TanStack Query:Out of the box, TanStack Query is configured with aggressive but sane defaults. Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user.TanStack Query 配有激进但合理的默认值不了解这些默认值会让新用户意外，或让学习和调试变得困难，因此需牢记TanStack Query 配有激进但合理的默认值激进但合理

Query instances via useQuery or useInfiniteQuery by default consider cached data as stale.
Query instances via useQuery or useInfiniteQuery by default consider cached data as stale.
useQuery 和 useInfiniteQuery 默认视缓存数据为过期过期状态会驱动查询在挂载、窗口聚焦或重连时进行后台重新获取
useQuery 和 useInfiniteQuery 默认视缓存数据为过期
缓存数据

To change this behavior, you can configure your queries both globally and per-query using the staleTime option. Specifying a longer staleTime means queries will not refetch their data as often
To change this behavior, you can configure your queries both globally and per-query using the staleTime option. Specifying a longer staleTime means queries will not refetch their data as often
用 staleTime 全局或按查询改变过期行为更长的 staleTime 意味着查询重新获取数据的频率更低
用 staleTime 全局或按查询改变过期行为
staleTime

A Query that has a staleTime set is considered fresh until that staleTime has elapsed.
A Query that has a staleTime set is considered fresh until that staleTime has elapsed.
设置 staleTime 的查询在到期前保持新鲜 staleTime 过后查询变为过期，正常的后台重新获取随之恢复
设置 staleTime 的查询在到期前保持新鲜
staleTime 设置
- set staleTime to e.g. 2 * 60 * 1000 to make sure data is read from the cache, without triggering any kinds of refetches, for 2 minutes, or until the Query is invalidated manually.
  set staleTime to e.g.
  staleTime 设为 2 分钟可从缓存读取，直至手动失效手动失效仍会覆盖新鲜期并触发重新获取
  staleTime 设为 2 分钟可从缓存读取，直至手动失效
  staleTime 设为 2 分钟
- set staleTime to Infinity to never trigger a refetch until the Query is invalidated manually.
  set staleTime to Infinity to never trigger a refetch until the Query is invalidated manually.
  staleTime 为 Infinity 时直到手动失效才重新获取手动失效仍是刷新查询数据的唯一途径
  staleTime 为 Infinity 时直到手动失效才重新获取
  staleTime Infinity
- set staleTime to 'static' to never trigger a refetch, even if the Query is invalidated manually.
  set staleTime to 'static' to never trigger a refetch, even if the Query is invalidated manually.
  staleTime 为 static 时即使手动失效也从不重新获取一旦设置为 static，任何失效途径都无法强制重新获取
  staleTime 为 static 时即使手动失效也从不重新获取
  staleTime static

'static' and Infinity both prevent staleness-based refetches, but 'static' is stricter: queryClient.invalidateQueries() can invalidate a query with staleTime: Infinity, but has no effect on staleTime: 'static'. refetchOnMount, refetchOnWindowFocus, and refetchOnReconnect set to "always" are also blocked by 'static'. Use 'static' for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use Infinity when you still want manual invalidation to work.
'static' and Infinity both prevent staleness-based refetches, but 'static' is stricter: queryClient.invalidateQueries() can invalidate a query with staleTime: Infinity, but has no effect on staleTime: 'static'. Use 'static' for data that cannot change while the app is running: feature flags fetched at boot, user permissions loaded at login, static reference tables. Use Infinity when you still want manual invalidation to work.
static 比 Infinity 更严格，也阻止手动失效应用运行时不变的数据用 static，仍需手动失效时用 Infinity
static 比 Infinity 更严格，也阻止手动失效
static

Stale queries are refetched automatically in the background when:
Stale queries are refetched automatically in the background when:
过期查询会自动在后台重新获取三个触发点是：查询挂载、窗口聚焦和网络重连
过期查询会自动在后台重新获取
过期查询
- New instances of the query mount
- The window is refocused
- The network is reconnected

Setting staleTime is the recommended way to avoid excessive refetches, but you can also customize the points in time for refetches by setting options like refetchOnMount, refetchOnWindowFocus and refetchOnReconnect.
Setting staleTime is the recommended way to avoid excessive refetches, but you can also customize the points in time for refetches by setting options like refetchOnMount, refetchOnWindowFocus and refetchOnReconnect.
staleTime 是避免过多重新获取的推荐方式重新获取时机也可用 refetchOnMount、refetchOnWindowFocus 和 refetchOnReconnect 自定义
staleTime 是避免过多重新获取的推荐方式
staleTime

Queries can optionally be configured with a refetchInterval to trigger refetches periodically, which is independent of the staleTime setting. See Polling for details.

Queries can optionally be configured with a refetchInterval to trigger refetches periodically, which is independent of the staleTime setting.
refetchInterval 独立于 staleTime 定期触发重新获取轮询行为不受过期设置影响
refetchInterval 独立于 staleTime 定期触发重新获取
refetchInterval
Query results that have no more active instances of useQuery, useInfiniteQuery or query observers are labeled as "inactive" and remain in the cache in case they are used again at a later time.

Query results that have no more active instances of useQuery, useInfiniteQuery or query observers are labeled as "inactive" and remain in the cache in case they are used again at a later time.
无活跃实例的查询变为非活跃并保留在缓存中它们会保留下来，以备稍后再次使用
无活跃实例的查询变为非活跃并保留在缓存中
活跃实例
By default, "inactive" queries are garbage collected after 5 minutes.

By default, "inactive" queries are garbage collected after 5 minutes.
非活跃查询默认在 5 分钟后被垃圾回收缓存窗口让后续使用有机会在移除前复用数据
非活跃查询默认在 5 分钟后被垃圾回收
非活跃查询
To change this, you can alter the default gcTime for queries to something other than 1000 * 60 * 5 milliseconds.
Queries that fail are silently retried 3 times, with exponential backoff delay before capturing and displaying an error to the UI.

Queries that fail are silently retried 3 times, with exponential backoff delay before capturing and displaying an error to the UI.
失败的查询会被静默重试 3 次并采用指数退避只有所有重试耗尽后错误才会显示到 UI
失败的查询会被静默重试 3 次并采用指数退避
静默重试 3 次
To change this, you can alter the default retry and retryDelay options for queries to something other than 3 and the default exponential backoff function.

Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
结构共享默认保持未变数据的引用稳定稳定引用有助于 useMemo 和 useCallback，几乎没人需要禁用
结构共享默认保持未变数据的引用稳定
结构共享

Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the config.structuralSharing flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function as config.structuralSharing to compute a value from the old and new responses, retaining references as required.
Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the config.structuralSharing flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function as config.structuralSharing to compute a value from the old and new responses, retaining references as required.
结构共享仅适用于 JSON 兼容的值其他类型总被视为已变化，可按需禁用或提供自定义函数
结构共享仅适用于 JSON 兼容的值
JSON 兼容的值

要点（模型写的）

Further Reading

要点（模型写的）