TanStack Query lit-query 类型参考QueriesControllerOptions 详解与 createQueriesController 选项机制【免费下载链接】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/lit-query的类型别名QueriesControllerOptions展开它是createQueriesController所接受的选项类型。读完本文你能准确理解该类型的两层结构Accessor包装 CreateQueriesControllerOptions本体、两个类型参数的含义与默认值并掌握在 Lit 组件中编写静态/动态并行查询、使用combine聚合多查询结果的完整用法。类型定义与出处QueriesControllerOptions的完整定义为type QueriesControllerOptionsTQueryOptions, TCombinedResult AccessorCreateQueriesControllerOptionsTQueryOptions, TCombinedResult;该类型定义于 packages/lit-query/src/types.ts源码中带有明确的文档注释Accessor-wrapped options accepted bycreateQueriesController供createQueriesController使用的、被 Accessor 包装的选项。从定义结构看它由两个正交部分组成外层AccessorT包装允许调用方直接传入选项对象或传入一个零参 getter 函数让选项跟随 Lit 组件的响应式状态在宿主更新时被重新求值内层CreateQueriesControllerOptionsTQueryOptions, TCombinedResult真正的选项本体包含queries查询列表与可选的combine结果聚合函数两个字段。这种双层可访问设计是 lit-query 控制器 API 的统一约定Accessor的类型本体与运行时读取逻辑见 packages/lit-query/src/accessor.tsexport type AccessorT T | (() T) export function readAccessorT(value: AccessorT): T { return typeof value function ? (value as () T)() : value }类型参数TQueryOptions约束为Arrayany默认值Arrayany。它是传入queries的查询选项数组或元组的静态类型是结果类型推断的输入。源码中每个数组元素对应CreateQueriesInput即tanstack/query-core的QueryObserverOptions形态见 packages/lit-query/src/createQueriesController.ts。TCombinedResult默认值为CreateQueriesResultsTQueryOptions。即如果不显式指定该类型参数也未传combine返回结果就是一个按输入顺序推断出的查询结果元组如果传了combine它则是combine的返回值类型。CreateQueriesResults通过递归映射每个查询项的queryFn/select/initialData等信息推断出对应的QueryObserverResult其递归推断受MAXIMUM_DEPTH 20深度限制超限后退化为ArrayQueryObserverResult见 packages/lit-query/src/createQueriesController.ts。内层选项 CreateQueriesControllerOptions 的字段剥去Accessor包装后实际可配置的字段定义在 packages/lit-query/src/createQueriesController.tsexport type CreateQueriesControllerOptions TQueryOptions extends Arrayany Arrayany, TCombinedResult CreateQueriesResultsTQueryOptions, { /** Query options to observe, or a getter that returns the current options. */ queries: Accessor | readonly [...CreateQueriesOptionsTQueryOptions] | readonly [ { [K in keyof TQueryOptions]: GetCreateQueriesInputTQueryOptions[K] } ] /** Optional function that combines the query result array into one value. */ combine?: (result: CreateQueriesResultsTQueryOptions) TCombinedResult }各字段说明queries必填要观察的查询选项列表。注意它本身也是Accessor类型——即使外层options是静态对象queries也可以单独写成 getter 以跟随响应式状态反之亦然。两种嵌套组合都支持options是对象 queries是 getteroptions本身是 getter此时整个选项在宿主更新时重新读取。combine可选将查询结果数组折叠为单个派生值的函数。不传时QueriesControllerOptions的返回类型即TCombinedResult默认值CreateQueriesResultsTQueryOptions结果元组传入时其返回值即为最终类型。从源码结构看queries的类型签名是一个readonly的联合类型既接受递归映射后的数组形式CreateQueriesOptions也接受按keyof TQueryOptions映射的元组形式这正是输入是元组时结果也推断为对应位置元组的类型机制来源。使用示例静态并行查询 combine 聚合以下示例来自 packages/lit-query/src/createQueriesController.ts 中的官方example注释options以静态对象传入合法Accessor分支之一import { LitElement, html } from lit import { createQueriesController } from tanstack/lit-query class DashboardView extends LitElement { private readonly dashboard createQueriesController(this, { queries: [ { queryKey: [stats], queryFn: fetchStats }, { queryKey: [projects], queryFn: fetchProjects }, ], combine: ([stats, projects]) ({ stats: stats.data, projects: projects.data ?? [], isPending: stats.isPending || projects.isPending, }), }) render() { const dashboard this.dashboard() return htmlpProjects: ${dashboard.projects.length}/p } }动态查询列表options 作为 getter当查询数量/内容依赖宿主响应式字段时将整个options写成 getter。该用法收录于 docs/framework/lit/guides/parallel-queries.mdimport { LitElement, html } from lit import { createQueriesController } from tanstack/lit-query class UsersDetails extends LitElement { static properties { userIds: { attribute: false }, } userIds: Arraystring [] private readonly users createQueriesController(this, () ({ queries: this.userIds.map((id) ({ queryKey: [user, id], queryFn: () fetchUserById(id), })), })) render() { const userQueries this.users() return html ul ${userQueries.map((query, index) { if (query.isPending) return htmlliLoading.../li if (query.isError) return htmlliError loading user/li return htmlli${this.userIds[index]}: ${query.data.name}/li })} /ul } }结果顺序与输入查询顺序严格一致若queries数组中出现重复的queryKey这些条目会共享缓存数据——如果每行渲染需要独立查询状态应先去重。源码级机制选项在运行期如何被消费QueriesControllerOptions不只是类型层面的约定QueriesController类packages/lit-query/src/createQueriesController.ts在运行时对其做了如下消费1. 两层Accessor的解析。resolveQueriesOptions先readAccessor(optionsAccessor)得到内层选项对象再readAccessor(resolvedOptions.queries)得到实际查询数组随后逐项经过client.defaultQueryOptions(...)应用全局默认配置并打上_optimisticResults: optimistic标记乐观结果避免初次订阅时因缓存未就绪而抖动最后交给QueriesObserver建立对多个查询的观察见 packages/lit-query/src/createQueriesController.ts。2. 何时重新读取选项。shouldRefreshOnHostUpdate的判定逻辑直接对应类型定义中两处Accessor位置options是函数或options.queries是函数任一成立控制器就会在宿主更新onHostUpdate时重新解析选项并调用observer.setQueries同步查询列表见 packages/lit-query/src/createQueriesController.ts。这就是类型上允许函数、运行时保证响应式刷新的闭环。3. QueryClient 解析与占位结果。未显式传入queryClient时控制器从最近的QueryClientProvider上下文解析若客户端尚未就绪会先为每个查询生成占位QueryObserverResult有initialData时直接映射为成功态并在构造完成后重试初始化见 packages/lit-query/src/createQueriesController.ts 与 docs/framework/lit/reference/functions/createQueriesController.md 中对queryClient参数的说明。4. 返回值的形态。createQueriesController返回QueriesResultAccessorTCombinedResult——一个可调用函数同时暴露current属性与destroy()方法combine的返回值会经过replaceEqualDeep做深比较去重只有实际内容变化才触发宿主更新见 packages/lit-query/src/createQueriesController.ts。行为层面的覆盖可参考测试文件 packages/lit-query/src/tests/queries-controller.test.ts 与类型推断测试 packages/lit-query/src/tests/type-inference.test.ts。与其他类型的关系CreateQueriesControllerOptions被本类型解包后的选项本体见 docs/framework/lit/reference/type-aliases/CreateQueriesControllerOptions.mdAccessor外层包装类型定义于 packages/lit-query/src/accessor.tsQueriesResultAccessorcreateQueriesController的返回类型见 docs/framework/lit/reference/type-aliases/QueriesResultAccessor.md函数参考docs/framework/lit/reference/functions/createQueriesController.md 给出了该函数完整的参数、返回值与示例说明。小结QueriesControllerOptionsTQueryOptions, TCombinedResult是 lit-query 并行查询入口createQueriesController的类型契约外层Accessor决定了选项可以静态传入、也可以随宿主状态动态求值内层queriescombine决定了观察哪些查询、结果如何聚合TQueryOptions与TCombinedResult两个类型参数则通过元组递归推断把输入选项映射为精确的返回类型无combine时为结果元组有combine时为其返回值。在编写 Lit 组件的动态并行查询时理解这层结构即可正确使用静态选项、getter 选项与结果聚合三种模式。【免费下载链接】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），仅供参考