Svelte Query 完整 API 参考：@tanstack/svelte-query 类型、函数与上下文体系全解

Svelte Query 完整 API 参考：@tanstack/svelte-query 类型、函数与上下文体系全解

发布时间：2026/9/11 15:53:10
Svelte Query 完整 API 参考：@tanstack/svelte-query 类型、函数与上下文体系全解 Svelte Query 完整 API 参考tanstack/svelte-query 类型、函数与上下文体系全解【免费下载链接】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本文是tanstack/svelte-query的 API 参考指南以 docs/framework/svelte/reference/index.md 索引为核心骨架系统梳理其全部类型别名、函数与变量并结合仓库源码packages/svelte-query/src讲解createQuery、createMutation、createInfiniteQuery、createQueries等核心 API 的重载签名、响应式Accessor设计、SSR 水合与上下文机制。读完本文你将能在 Svelte 5 项目中正确选用并组合这些 API写出类型安全、支持响应式选项与乐观更新的数据请求代码。API 全景索引页揭示的完整公开面tanstack/svelte-query的公开 API 被组织为四类类型别名Type Aliases、变量Variables、函数Functions与引用References。索引页完整列出的 26 个类型别名、1 个变量和 17 个函数正是 packages/svelte-query/src/index.ts 中 re-export 的完整清单。从索引结构可以清晰看到三条使用主线查询与数据获取createQuery、createInfiniteQuery、createQueries配合queryOptions、infiniteQueryOptions共享选项变更与服务端副作用createMutation配合mutationOptions与useMutationState跨组件观察状态上下文与生命周期QueryClientProvider、HydrationBoundary、useQueryClient、useHydrate、useIsFetching、useIsMutating、useIsRestoring。值得注意的细节是索引页的 References 一节指出QueryClientProvider是对HydrationBoundary的rename re-export见 variables/HydrationBoundary.md这在 packages/svelte-query/src/index.ts#L32-L33 中通过export { default as HydrationBoundary } from ./HydrationBoundary.svelte和export { default as QueryClientProvider } from ./QueryClientProvider.svelte得到印证——Svelte Query 使用同一个 Svelte 组件承载「提供客户端」与「水合状态」两项职责。类型别名体系从选项到结果的类型契约索引页列出的 26 个类型别名并非杂乱枚举它们构成了「选项 → 结果」的完整类型映射。核心定义集中在 packages/svelte-query/src/types.ts基础类型AccessorT定义为() Ttypes.ts#L22是 Svelte Query 响应式设计的基石——所有create*函数的第一个参数都是Accessor包裹的选项使得选项可以随 Svelte 响应式状态变化而更新。查询族类型别名说明CreateBaseQueryOptions/CreateBaseQueryResult底层选项与结果直接透传query-core的QueryObserverOptions/QueryObserverResultCreateQueryOptions/CreateQueryResultcreateQuery的常规选项与结果DefinedCreateQueryResult设置了initialData时的结果data永不为undefinedDefinedInitialDataOptions/UndefinedInitialDataOptions是否携带initialData的选项类型区分CreateInfiniteQueryOptions/CreateInfiniteQueryResult无限查询的选项与结果DefinedCreateInfiniteQueryResult带initialData的无限查询结果变更族CreateMutationOptions、CreateMutationResult、CreateMutateFunction、CreateMutateAsyncFunction覆盖mutationFn、mutate与mutateAsync的类型MutationTypeFromResult用于从结果反推变更类型支撑useMutationState的泛型推导。组合与特殊QueriesOptions、QueriesResults支持createQueries的 tuple/数组推导HydrationBoundary、QueryClientProviderProps定义水合组件的 propsMutationStateOptions定义useMutationState的过滤器与select参数。从源码结构看这些类型绝大多数是对tanstack/query-core中QueryObserverOptions、MutationObserverOptions等类型的精确定义包装types.ts#L25-L119目的是让 Svelte 侧的类型与 core 保持严格一致的同时裁剪掉_defaulted等内部字段。createQuery三种重载对应三种典型场景createQuery在 packages/svelte-query/src/createQuery.ts 中定义了三个重载Call Signature索引页与函数文档分别对应常规UndefinedInitialDataOptions、带initialData的DefinedInitialDataOptions、以及更宽泛的CreateQueryOptions。三个重载共享四个泛型参数TQueryFnData unknownqueryFn 的原始返回类型TError Error错误类型Svelte 侧默认Errorcore 中为DefaultErrorTData TQueryFnDataselect转换后的数据类型TQueryKey extends readonly unknown[] readonly unknown[]查询键类型两个可选位置参数optionsAccessor包裹支持响应式与queryClient?AccessorQueryClient不传则取最近上下文的客户端。基础用法status 与派生布尔值最简单形态——用status区分三种状态或直接用isPending/isError/isSuccess派生布尔值script langts import { createQuery } from tanstack/svelte-query const query createQuery(() ({ queryKey: [posts], queryFn: fetchPosts, })) /script {#if query.status pending} Loading... {:else if query.status error} spanError: {query.error.message}/span {:else} ul {#each query.data as post (post.id)} li{post.title}/li {/each} /ul {/if}status的取值语义在函数文档中明确给出无缓存数据显示时pending最近一次抓取失败为error有数据可展示为successisPending/isSuccess/isError只是方便阅读的派生布尔值。initialData 重载data 永不为 undefined当设置了initialData时TypeScript 自动选择第二个重载返回DefinedCreateQueryResult——此时status的类型层面永不解析为pending即使重新抓取失败旧数据也会保留script langts import { createQuery } from tanstack/svelte-query // data 是 Post[]永不 undefined——即便 refetch 失败列表也保持可见 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高级模式select、依赖查询与分页createQuery文档提供了四个实战级示例覆盖数据获取场景的高频诉求1.select派生数据——缓存仍存完整的Post[]但组件拿到的data是number且不会污染缓存const query createQuery(() ({ queryKey: [posts], queryFn: fetchPosts, select: (posts) posts.length, }))2. 依赖查询——postId未就绪时禁用查询。注意文档的提醒禁用期间要用isLoading而非isPending否则会误显示 loadinglet { postId }: { postId: number | undefined } $props() const query createQuery(() ({ queryKey: [post, postId], queryFn: () fetchPost(postId!), enabled: postId ! null, }))3. 从缓存列表种子化详情查询——用initialData函数形式从已缓存的列表数据中取出详情跳过加载态const queryClient useQueryClient() const query createQuery(() ({ queryKey: [post, postId], queryFn: () fetchPost(postId), initialData: () queryClient .getQueryDataArrayPost([posts]) ?.find((post) post.id postId), }))4. 分页保持旧数据可见——placeholderData: keepPreviousData配合isPlaceholderData禁用下一页按钮let page $state(0) const query createQuery(() ({ queryKey: [posts, page], queryFn: () fetchPosts(page), placeholderData: keepPreviousData, }))createInfiniteQuery无限滚动与分页加载createInfiniteQuerypackages/svelte-query/src/createInfiniteQuery.ts同样有三个重载泛型在查询族基础上增加TPageParam unknownTData默认值为InfiniteDataTQueryFnData, unknown。其返回结果在CreateQueryResult基础上增加fetchNextPage/fetchPreviousPage/hasNextPage/hasPreviousPage四个分页能力。Load More 按钮模式通过initialPageParam指定起始页码getNextPageParam从最后一页推导下一页参数script langts import { createInfiniteQuery } from tanstack/svelte-query const query createInfiniteQuery(() ({ queryKey: [projects], queryFn: ({ pageParam }) fetchProjects(pageParam), initialPageParam: 0, getNextPageParam: (lastPage) lastPage.nextId, })) /script {#if query.isPending} Loading... {:else if query.isError} spanError: {query.error.message}/span {:else} ul {#each query.data.pages as page} {#each page.projects as project (project.id)} li{project.name}/li {/each} {/each} /ul button onclick{() query.fetchNextPage()} disabled{!query.hasNextPage || query.isFetching} {query.isFetchingNextPage ? Loading more... : query.hasNextPage ? Load More : Nothing more to load} /button {/if}IntersectionObserver 无限滚动模式用 Svelte 5 的$effectbind:this挂载哨兵元素滚动到底部自动加载let sentinel: HTMLDivElement | undefined $state() $effect(() { if (sentinel null || !query.hasNextPage || query.isFetching) return const observer new IntersectionObserver(([entry]) { if (entry?.isIntersecting) query.fetchNextPage() }) observer.observe(sentinel) return () observer.disconnect() })createMutation服务端副作用与乐观更新与查询不同变更通常用于创建/更新/删除数据或执行服务端副作用。createMutationpackages/svelte-query/src/createMutation.svelte.ts的泛型为TData unknown、TError Error、TVariables void、TContext unknown返回CreateMutationResult。基础mutate 触发 成功后失效查询script langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, onSuccess: () queryClient.invalidateQueries({ queryKey: [todos] }), })) /script button onclick{() addMutation.mutate(Item)}Add/button调用点回调与批量提交mutate/mutateAsync都接受第二个参数传入onSuccess/onError/onSettled回调适合在调用点做导航等副作用而不用耦合共享的变更定义。关键语义若连续多次请求onSuccess只会在最近一次调用后触发mutateAsync则每次调用返回独立的 Promise可逐个等待async function handleAddAll(todos: Arraystring) { try { await Promise.all(todos.map((todo) addMutation.mutateAsync(todo))) } catch (error) { console.error(Failed to add todos:, error) } }若希望各请求独立失败也能拿到各自结果文档建议换用Promise.allSettled避免第一个 reject 就丢失其余结果信息。乐观更新三件套onMutate / onError / onSettled文档给出了完整的乐观更新闭环onMutate中取消进行中的查询、快照旧数据、写入新数据并返回onMutateResult失败时onError用快照回滚最后onSettled统一失效查询const addMutation createMutation(() ({ mutationFn: addTodo, onMutate: async (newTodo: string) { await queryClient.cancelQueries({ queryKey: [todos] }) const previousTodos queryClient.getQueryDataArraystring([todos]) queryClient.setQueryDataArraystring([todos], (old) [ ...(old ?? []), newTodo, ]) // 失败时传给 onError 作为 onMutateResult return { previousTodos } }, onError: (_err, _newTodo, onMutateResult) { queryClient.setQueryData([todos], onMutateResult?.previousTodos) }, onSettled: () { queryClient.invalidateQueries({ queryKey: [todos] }) }, }))createQueries并行查询与结果合并createQueriespackages/svelte-query/src/createQueries.svelte.ts接收一个对象queries数组每个元素是一个查询选项支持 tuple 类型推导 可选combine函数整体由Accessor包裹实现响应式。返回按queries顺序排列的结果数组提供combine时返回combine的产物。let { ids }: { ids: Arraynumber } $props() const postQueries createQueries(() ({ queries: ids.map((id) ({ queryKey: [post, id], queryFn: () fetchPost(id), staleTime: Infinity, })), }))配合combine把多个查询聚合成单一对象方便统一渲染const combined createQueries(() ({ queries: ids.map((id) ({ queryKey: [post, id], queryFn: () fetchPost(id), })), combine: (postQueries) ({ data: postQueries.map((query) query.data), isPending: postQueries.some((query) query.isPending), isError: postQueries.some((query) query.isError), }), }))选项构造器queryOptions / infiniteQueryOptions / mutationOptions这三者在 index.md 中并列用于把选项定义与组件解耦既可在create*中共享也能被queryClient.query、queryClient.infiniteQuery等命令式 API 复用。queryOptionspackages/svelte-query/src/queryOptions.tsqueryKey必填返回值使queryKey携带推断出的数据类型QueryKeyWithDataTag。有initialData与无initialData两个重载。典型用法是参数化工厂按id复用同一套选项const postOptions (id: string) queryOptions({ queryKey: [post, id], queryFn: () fetchPost(id), }) const query createQuery(() postOptions(id))infiniteQueryOptionspackages/svelte-query/src/infiniteQueryOptions.ts同样queryKey必填TData默认InfiniteDataTQueryFnData, unknown。可用initialData: { pages: [], pageParams: [] }跳过首屏加载态const projectsOptions infiniteQueryOptions({ queryKey: [projects], queryFn: ({ pageParam }) fetchProjects(pageParam), initialPageParam: 0, getNextPageParam: (lastPage) lastPage.nextId, initialData: { pages: [], pageParams: [] }, })mutationOptionspackages/svelte-query/src/mutationOptions.ts两个重载的关键差异在于mutationKey——带mutationKey的重载返回WithRequired..., mutationKey可用于useMutationState跨组件查询变更状态不带的重载返回Omit..., mutationKeyconst createPostOptions mutationOptions({ mutationKey: [posts, create], mutationFn: createPost, }) const pending useMutationState({ filters: { mutationKey: createPostOptions.mutationKey, status: pending }, })上下文机制QueryClient 的存取与恢复状态Svelte Query 依赖 Svelte 的 context API 传递QueryClient。核心实现在 packages/svelte-query/src/context.tssetQueryClientContext(client)通过setContext(Symbol(QueryClient), client)写入getQueryClientContext()通过getContext读取找不到时会抛出No QueryClient was found in Svelte context. Did you forget to wrap your component with QueryClientProvider?context.ts#L14-L23这解释了为什么所有create*函数都必须处于QueryClientProvider之下setIsRestoringContext/getIsRestoringContext以Symbol(isRestoring)为键存取恢复状态布尔值getIsRestoringContext在取不到时安全回退为{ current: false }不会抛错。useQueryClientpackages/svelte-query/src/useQueryClient.ts是对getQueryClientContext的薄封装可传可选参数指定自定义客户端否则取最近上下文。useIsRestoring用于在持久化恢复过程中抑制抓取配合 packages/svelte-query/src/useIsRestoring.ts 读取 context 中的恢复标记。全局状态观察useIsFetching / useIsMutating / useMutationState这类函数让「不在同一组件内的请求/变更」也能被全局观察到useIsFetching(filters?, queryClient?)packages/svelte-query/src/useIsFetching.svelte.ts返回ReactiveValuenumber——注意返回值是响应式容器需读.current取当前正在抓取的查询数量。filters可传QueryFilters收窄范围如{ queryKey: [posts] }省略则统计全部const isFetchingPosts useIsFetching({ queryKey: [posts] }) {#if isFetchingPosts.current} spanRefreshing posts.../span {/if}useIsMutating与前者对称统计匹配过滤条件的进行中变更数量常用于全局「保存中…」指示。useMutationState(options?, queryClient?)packages/svelte-query/src/useMutationState.svelte.ts可访问任何匹配filters的变更——包括由其他组件或 hook 创建、甚至已卸载的。options为MutationStateOptions默认{}含filters与可选的select。返回值是对每个匹配变更应用select后的数组const pendingVariables useMutationState({ filters: { status: pending }, select: (mutation) mutation.state.variables, }) {pendingVariables.length} posts saving...文档还提示一个重要细节每次mutate调用都会在变更缓存中保留一个条目直到gcTime过期因此取useMutationState返回数组的最后一个元素即最近一次成功的变更配合status: success过滤const savedPosts useMutationState({ filters: { mutationKey: [posts], status: success }, select: (mutation) mutation.state.data, }) const latestSavedPost $derived(savedPosts[savedPosts.length - 1])SSR 与状态水合useHydrate / HydrationBoundaryuseHydrate(state?, options?, queryClient?)packages/svelte-query/src/useHydrate.ts把之前dehydrate出的状态并入queryClient若客户端已有数据会基于更新时间戳智能合并。HydrationBoundary是对它的封装日常 SSR 场景直接使用组件形式即可——除非需要在自定义组件中手动触发水合才直接用useHydrate。典型的 SSR 流程服务端 load 函数用queryClient.query预取并dehydrate(queryClient)客户端通过 props 接收dehydratedState交给HydrationBoundaryscript langts import { HydrationBoundary } from tanstack/svelte-query import type { DehydratedState } from tanstack/svelte-query import Posts from ./Posts.svelte let { dehydratedState }: { dehydratedState: DehydratedState } $props() /script HydrationBoundary state{dehydratedState} Posts / /HydrationBoundary扩展阅读与源码索引围绕本文涉及的 API可在仓库中继续深入全部类型别名与函数的逐条签名docs/framework/svelte/reference/type-aliases 与 docs/framework/svelte/reference/functionsSvelte Query 实现源码packages/svelte-query/src/index.ts、createQuery.ts、createMutation.svelte.ts、context.ts、types.ts框架总览与安装方式docs/framework/svelte/overview.md、docs/framework/svelte/installation.mdSvelte Query 官方示例basic、load-more-infinite-scroll、optimistic-updates、ssr 等examples/svelteSvelte 5 迁移说明docs/framework/svelte/migrate-from-v5-to-v6.md理解这些 API 时把握三条主线即可查询用createQuery/createInfiniteQuery/createQueries加选项构造器共享定义变更用createMutation配合useMutationState实现跨组件观察与乐观更新上下文由QueryClientProvider提供、useQueryClient消费SSR 场景经dehydrate/HydrationBoundary完成状态交接。【免费下载链接】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），仅供参考