TanStack DB — SolidJS 绑定
用途 本技能用于在 SolidJS 中使用 TanStack DB 的实时查询能力,基于 db-core 构建。官方建议先阅读 db-core,了解集合设置、查询构建器与变更(mutation)模式。
安装与导入 代码示例从 @tanstack/solid-db 导入 useLiveQuery、eq、not,并从 solid-js 导入 ErrorBoundary、For、Show、Suspense。@tanstack/solid-db 重新导出了 @tanstack/db 的全部内容。资料未提供具体安装命令。
主要能力:useLiveQuery 调用 useLiveQuery 返回一个 Accessor<Array<T>>(使用 findOne 时为 Accessor<T | undefined>),并附带额外属性。可作为函数调用获取数据:
- query() → Array<T>(数据);使用 findOne() 时为 T | undefined
- query.data → 已弃用,应改用 query()
- query.status → CollectionStatus
- query.isLoading、query.isReady、query.isError
- query.state → ReactiveMap<TKey, T>
- query.collection → Collection
使用方式
- 基本查询:传入查询函数 (q) => q.from(...).where(...).orderBy(...)。
- 响应式信号:信号必须在查询函数内部读取,才能被追踪并触发重跑。
- 配置对象:以 Accessor 形式传入,如 useLiveQuery(() => ({ query: (q) => ..., gcTime: 60000 }))。
- 预创建集合:以 Accessor 形式传入,如 useLiveQuery(() => preloadedCollection)。
- 条件查询:在查询函数内读取信号,若无 id 则返回 undefined。
findOne(单条结果) 当查询使用 .findOne() 时,useLiveQuery 返回单个对象或 undefined,而非数组。可用 <Show when={userQuery()}> 渲染。
Suspense 集成 useLiveQuery 与 Solid 的 createResource 集成,使用 <Suspense> 处理加载、<ErrorBoundary> 处理错误。读取出错的查询会通过 resource 抛出,因此失败后不要依赖读取 isError。
Includes(层次化数据) 查询使用 includes(select 中的子查询)时,每个子字段默认为实时 Collection,可在子组件中用 useLiveQuery 订阅;需将子 Collection 包装为 Accessor(() => props.issuesCollection)以匹配重载签名。使用 toArray() 时,子结果是普通数组,父级会在子项变化时重新发出,无需子组件。完整 includes 规则(关联条件、嵌套 includes、聚合)见 db-core/live-queries/SKILL.md。
常见错误
- 高优先级:在查询函数外部读取信号。Solid 的响应式只追踪响应式上下文内的信号读取,外部读取只捕获创建时的值,后续变化不会触发重跑。
- 中优先级:使用已弃用的 query.data,应改用 query()。遇到既有 .data 代码应迁移为函数调用形式。
适用场景 适用于需要在 SolidJS 中构建实时、响应式数据查询界面的场景,包括列表查询、单条查询、条件查询、层次化数据展示,以及与 Suspense/ErrorBoundary 配合的加载与错误处理。
限制 资料未提供具体安装命令、版本要求、性能数据或收费信息。query.data 已弃用;读取出错的查询会抛出,不应在失败后依赖 isError。信号必须在查询函数内读取。