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），僅供參考 Svelte Query CreateQueryOptions 類型指南：createQuery 全部選項的 TypeScript 權威解讀
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），僅供參考