安装

更新于 2026-11-02 Lit 查看英文原文 ↗

重要：Lit 适配器目前处于实验阶段，版本为 v0.1。若需在 API 尚不稳定的早期阶段获得额外的发布稳定性，请锁定精确版本。

安装 Lit Query：

Shell

1npm i @tanstack/lit-query

或

Shell

1pnpm add @tanstack/lit-query

或

Shell

1yarn add @tanstack/lit-query

或

Shell

1bun add @tanstack/lit-query

要求

Lit Query 面向 Lit 2.8 及更高版本（包括 Lit 3）。它使用 Lit 的响应式控制器（reactive controllers）和 Lit 上下文（context），因此查询消费者应为 ReactiveControllerHost 实例，例如 LitElement。

本文档中的代码片段使用 static properties 声明响应式属性，并将其初始化为类字段。使用原生 [[Define]] 语义的类字段会遮蔽 Lit 用于检测变更的访问器（accessors），因此在 TypeScript 中请将 useDefineForClassFields 设为 false（如可运行示例所示）。更多详情，请参阅 Lit 文档中的避免类字段相关问题。

JSON

1{2  "compilerOptions": {3    "useDefineForClassFields": false4  }5}

TanStack Query 针对现代浏览器进行了优化：

Text

1Chrome >= 912Firefox >= 903Edge >= 914Safari >= 155iOS >= 156Opera >= 77

提供者设置

创建一个 QueryClient，通过 QueryClientProvider 向其提供配置，并注册你的自定义元素。该包导出了提供者类，但不会为你调用 customElements.define。

子类模式

TypeScript

1import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'2 3const queryClient = new QueryClient()4 5class AppQueryProvider extends QueryClientProvider {6  constructor() {7    super()8    this.client = queryClient9  }10}11 12customElements.define('app-query-provider', AppQueryProvider)

HTML

1<app-query-provider>2  <todos-view></todos-view>3</app-query-provider>

直接提供者元素

你可以直接注册提供者类，并从 Lit 模板中绑定其 client 属性。点号（.）至关重要：.client=${queryClient} 是属性绑定，而非 HTML 属性。

TypeScript

1import { LitElement, html } from 'lit'2import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'3 4const queryClient = new QueryClient()5 6customElements.define('query-client-provider', QueryClientProvider)7 8class AppRoot extends LitElement {9  render() {10    return html`11      <query-client-provider .client=${queryClient}>12        <todos-view></todos-view>13      </query-client-provider>14    `15  }16}

若已连接的提供者未设置 client，则会抛出错误。有关完整契约，请参阅生成的 QueryClientProvider 参考文档。

渲染根节点

本文档中的代码片段使用 Lit 默认的 shadow DOM。Lit Query 控制器和 QueryClientProvider 同时支持 shadow DOM 和 light DOM，因为它们依赖宿主生命周期（host lifecycle）和 Lit 上下文，而非全局选择器。

部分可运行示例重写了 createRenderRoot() 并返回 this，以使演示标记保留在 light DOM 中，便于共享页面样式和测试选择器。该重写并非 Lit Query 所必需。仅当你的应用有其他明确理由（例如需向全局 CSS、测试或非 shadow DOM 集成代码暴露组件内部标记）时，才应使用 light DOM。

开发者工具状态

Lit Devtools 尚不可用。这是当前适配器的限制，而非安装步骤。