Svelte Query CreateQueryOptions 类型指南createQuery 全部选项的 TypeScript 权威解读【免费下载链接】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/queryCreateQueryOptions是 TanStack Svelte Query 中createQuery组合式函数hook的参数类型它描述了如何声明一次数据请求的全部行为从queryKey、queryFn这类必填核心字段到enabled、staleTime、retry、select等数十个用于控制缓存、重试、自动刷新与派生数据的可选配置。本文以该类型的源码定义为主体完整解析其类型参数、继承链上的全部字段及其默认值与底层实现帮助你写出类型安全、行为可控的 Svelte 数据获取代码。一、类型定义一行别名背后的继承链CreateQueryOptions定义在 packages/svelte-query/src/types.ts 中其完整声明如下/** Options for createQuery */ export type CreateQueryOptions TQueryFnData unknown, TError DefaultError, TData TQueryFnData, TQueryKey extends QueryKey QueryKey, CreateBaseQueryOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey从源码结构看这是一个层层转发的类型别名CreateQueryOptions→CreateBaseQueryOptions定义于 packages/svelte-query/src/types.ts 第 24-31 行CreateBaseQueryOptions→QueryObserverOptions来自tanstack/query-core即CreateQueryOptions最终等价于QueryObserverOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey。注意其中TQueryData观测器内部缓存的原始数据类型被固定为TQueryFnData这保证了select变换前的数据形态与查询函数返回的数据形态一致。QueryObserverOptions定义于 packages/query-core/src/types.ts它通过WithRequiredQueryOptions..., queryKey强制要求queryKey必填并在此之上补充了观测器observer层面的行为选项。因此CreateQueryOptions的字段空间 QueryOptions的全部字段 QueryObserverOptions的全部字段。二、四个类型参数从数据形态到错误类型的完整约束原文档声明了 4 个泛型参数理解它们之间的默认值联动关系是掌握该类型的关键类型参数约束默认值含义TQueryFnData无unknownqueryFn返回的原始数据类型即缓存中存储的数据类型TError无DefaultError查询失败时error的类型默认是unknown的包装TData无TQueryFnData组件实际读取到的数据类型设置select后TData为选择器返回值TQueryKeyextends QueryKeyQueryKey查询键类型必须是QueryKeyreadonly unknown[]的子类型关键联动逻辑若不传TData它默认等于TQueryFnData因此普通查询的query.data类型就是queryFn的返回类型一旦使用select: (data) ...TData会被推断为选择器的返回类型见下文实战示例TQueryKey默认是宽泛的QueryKey但显式传入字面量类型如[post, postId]可获得更精确的查询键类型推导配合queryOptions还能让queryKey携带数据类型标签QueryKeyWithDataTag。这四个参数贯穿整个 Svelte Query 的类型体系CreateQueryResultTData, TError、DefinedCreateQueryResultTData, TError等结果类型都与之对应保证选项类型 → 结果类型的完全一致。三、完整选项字段清单全部配置项、默认值与作用以下字段是CreateQueryOptions可接受的全部配置分为两层列出来源packages/query-core/src/types.ts。3.1 QueryObserverOptions 层控制组件观测行为字段类型默认值作用enabledboolean \| (query) booleantrue设为false时挂载或查询键变化不会自动请求需手动调用refetchstaleTimenumber \| (query) number0数据被视为过期的时间毫秒Infinity表示永不过期refetchIntervalnumber \| false \| (query) number \| false \| undefinedfalse定时轮询频率毫秒函数形式可根据最新数据动态计算refetchIntervalInBackgroundbooleanfalsetrue时标签页/窗口在后台也继续轮询refetchOnWindowFocusboolean \| always \| (query) ...true窗口聚焦且数据过期时自动重新请求always无条件刷新refetchOnReconnectboolean \| always \| (query) ...truenetworkMode: always时为false网络重连时自动重新请求refetchOnMountboolean \| always \| (query) ...true组件挂载时若数据过期则刷新false阻止同一查询的额外实例触发后台刷新retryOnMountboolean \| (query) booleantrue挂载时若查询曾失败是否再次重试notifyOnChangePropsstring[] \| all \| (() string[])跟踪访问属性仅当列出的属性变化时触发组件重渲染默认按访问追踪throwOnErrorboolean \| (error, query) booleanfalsetrue或配合suspense时把错误抛给错误边界而不是放入error状态select(data: TQueryData) TData无从缓存数据变换出组件需要的部分数据不改变缓存内容suspensebooleanfalsetrue时status pending挂起、status error抛错placeholderDataTQueryData \| 函数无无initialData且数据加载中时显示的占位数据如keepPreviousData_optimisticResultsoptimistic \| isRestoring无内部使用的乐观结果标记3.2 QueryOptions 层查询本身的运行与缓存策略字段类型默认值作用queryKeyTQueryKey必填无默认查询的唯一标识用于缓存命中与失效queryFnQueryFunction \| SkipToken无实际发起请求的函数使用skipToken可跳过请求retryboolean \| number \| (failureCount, error) boolean3失败重试次数true无限重试false不重试retryDelaynumber \| (retryAttempt, error) number指数退避重试间隔毫秒默认按重试次数指数递增networkModeonline \| always \| offlineFirstonline控制网络不可用时的行为gcTimenumber5 分钟默认缓存变为未使用/非活动后保留在内存的时间毫秒Infinity关闭垃圾回收queryHashstring由键哈希生成查询哈希用于内部定位查询queryKeyHashFn(queryKey) string默认哈希自定义查询键哈希函数initialDataTData \| () TData无首次渲染即有的初始数据可避免 loading 状态initialDataUpdatedAtnumber \| () number \| undefined无initialData的时间戳影响 stale 判断structuralSharingboolean \| (oldData, newData) unknowntrue结构共享数据形状未变时复用旧引用避免多余重渲染persisterQueryPersister无自定义查询持久化器behaviorQueryBehavior无查询行为扩展metaQueryMeta无附加到查询上的任意负载供其他地方读取maxPagesnumber无无限查询最大缓存页数注意以上默认值如retry: 3、gcTime: 5 分钟为 Query 核心的常规默认实际生效值还取决于QueryClient构造时的全局默认配置二者会合并。四、响应式 Accessor 包裹Svelte 5 特有的选项声明方式createQuery的选项参数被包装为AccessorT即() T这是 Svelte Query 适配 Svelte 5 runes 响应式系统的核心设计。createQuery的最终实现见 packages/svelte-query/src/createQuery.tsexport function createQuery( options: AccessorCreateQueryOptions, queryClient?: AccessorQueryClient, ) { return createBaseQuery(options, QueryObserver, queryClient) }这意味着在.svelte组件中你需要把选项包在一个函数里任何$state/$props的变化都会让选项重新求值script langts import { createQuery } from tanstack/svelte-query let { postId }: { postId: number | undefined } $props() const query createQuery(() ({ queryKey: [post, postId], queryFn: () fetchPost(postId!), enabled: postId ! null, })) /scriptqueryClient同样是可选的AccessorQueryClient不传时使用最近上下文中的客户端。五、initialData 重载类型上消灭undefinedcreateQuery依据是否提供initialData选择了不同重载packages/svelte-query/src/queryOptions.ts未提供initialData时使用UndefinedInitialDataOptions此时TQueryFnData被NonUndefinedGuard约束提供initialData时使用DefinedInitialDataOptions返回DefinedCreateQueryResult其中data保证永不为undefinedstatus不会解析为pending除非请求失败且保留旧数据。script langts import { createQuery } from tanstack/svelte-query // data 是 Post[]绝不会是 undefined const query createQuery(() ({ queryKey: [posts], queryFn: fetchPosts, initialData: [], })) /script {#if query.isError} spanError: {query.error.message}/span {/if} ul {#each query.data as post (post.id)} li{post.title}/li {/each} /ul六、queryOptions把选项提升为可共享、可复用的一等公民queryOptions接受与createQuery完全相同的选项对象返回时给queryKey附加数据类型标签QueryKeyWithDataTag使选项既可用于组件内的createQuery也可用于命令式 API如queryClient.query、queryClient.fetchQuery实现一份定义多处消费script langts import { queryOptions, createQuery } from tanstack/svelte-query const postOptions (id: string) queryOptions({ queryKey: [post, id], queryFn: () fetchPost(id), }) let { id }: { id: string } $props() const query createQuery(() postOptions(id)) /script七、常用配置组合实战结合 createQuery.ts 的文档示例 与上文字段以下是几组高频组合。7.1 select 派生数据而不污染缓存script langts import { createQuery } from tanstack/svelte-query // 缓存仍存完整 Post[]组件只读取数量 const query createQuery(() ({ queryKey: [posts], queryFn: fetchPosts, select: (posts) posts.length, })) /script {#if query.isPending} Loading... {:else if query.isError} spanError: {query.error.message}/span {:else} span{query.data} posts/span {/if}7.2 initialData 从缓存播种详情页script langts import { createQuery, useQueryClient } from tanstack/svelte-query let { postId }: { postId: number } $props() const queryClient useQueryClient() const query createQuery(() ({ queryKey: [post, postId], queryFn: () fetchPost(postId), initialData: () queryClient .getQueryDataArrayPost([posts]) ?.find((post) post.id postId), })) /script7.3 分页时保留上一页数据script langts import { createQuery, keepPreviousData } from tanstack/svelte-query let page $state(0) const query createQuery(() ({ queryKey: [posts, page], queryFn: () fetchPosts(page), placeholderData: keepPreviousData, })) /script button disabled{query.isPlaceholderData} onclick{() page} Next Page /button7.4 依赖查询enabled 与 isLoading 配合依赖其他数据的查询应使用enabled关闭自动请求并用isLoading而非isPending判断避免禁用期间误显示加载态script langts import { createQuery } from tanstack/svelte-query let { postId }: { postId: number | undefined } $props() const query createQuery(() ({ queryKey: [post, postId], queryFn: () fetchPost(postId!), enabled: postId ! null, })) /script {#if postId null} Select a post {:else if query.isLoading} Loading... {:else if query.isError} spanError: {query.error.message}/span {:else} h1{query.data?.title}/h1 {/if}八、关联类型一览CreateQueryOptions不是孤立存在它与 Svelte Query 类型体系中的以下成员紧密关联均定义于 packages/svelte-query/src/types.tsCreateBaseQueryOptions底层选项类型比CreateQueryOptions多一个TQueryData参数供内部createBaseQuery使用CreateQueryResultTData, TErrorcreateQuery的返回值类型DefinedCreateQueryResult提供initialData时保证data非空的返回类型CreateInfiniteQueryOptionscreateInfiniteQuery的选项类型额外包含initialPageParam、getNextPageParam、getPreviousPageParam与maxPagesUndefinedInitialDataOptions/DefinedInitialDataOptionscreateQuery两个重载使用的细分选项类型。理解CreateQueryOptions就等于掌握了 Svelte Query 声明式数据获取的全部旋钮从数据形态四个泛型参数、请求时机enabled/refetchOn*、失败策略retry/retryDelay/throwOnError、缓存寿命gcTime/staleTime/structuralSharing到派生展示select/placeholderData/initialData均可在类型系统的保护下组合使用。【免费下载链接】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），仅供参考