本技能介绍 TanStack DB 的 Svelte 5 绑定,需先阅读 db-core 以了解集合设置、查询构建器与变更模式。
用途
为 Svelte 5 应用提供 TanStack DB 的响应式查询能力。@tanstack/svelte-db 重新导出了 @tanstack/db 的全部内容。
主要能力
使用 useLiveQuery 返回带有 getter 属性的响应式对象,可通过点号访问 query.data、query.isLoading、query.status 等。支持三种调用形式:查询函数、带响应式依赖的查询函数加依赖数组、配置对象(含 query 与 gcTime),以及传入预先创建的集合。
使用方式
依赖数组必须使用 getter 函数,例如 [() => minPriority]。在 Svelte 5 中直接传入值会在创建时捕获,后续变化不会触发重新执行。解构会破坏响应式:不应直接 const { data, isLoading } = useLiveQuery(...),而应使用点号访问,或 const { data, isLoading } = $derived(query)。组件 props 用于依赖数组时同样需包裹为 getter,例如 [() => userId]。
includes 分层数据
当查询使用 includes(select 中的子查询)时,默认每个子字段是实时 Collection,可在子组件中用 useLiveQuery 订阅该子 Collection。若使用 toArray(),子结果为普通数组,父级会在子项变化时重新发出,无需子组件。完整的 includes 规则(关联条件、嵌套 includes、聚合)参见 ../tanstack-db-core-live-queries/SKILL.md。
适用场景
适用于在 Svelte 5 中构建需要实时响应数据库变化的界面,如待办列表过滤、按用户查询、项目与问题等分层数据的展示。
限制与注意事项
两个常见错误需避免:一是在依赖数组中传入值而非 getter 函数(关键错误);二是直接解构 useLiveQuery 的返回值(高优先级错误)。