用途:TanStack DB 中的集合(Collections)是带类型的数据存储,将数据加载与数据绑定解耦,可从 REST API、同步引擎或本地存储填充,再用实时查询(live queries)统一查询。本手册按集合类型、配置方式、同步模式和常用 API 组织。
主要能力与集合类型:QueryCollection(@tanstack/query-db-collection,经 TanStack Query 访问 REST API)、ElectricCollection(@tanstack/electric-db-collection,经 Electric 实时同步 Postgres)、PowerSyncCollection(离线优先)、RxDBCollection(RxDB 本地持久化)、TrailBaseCollection(TrailBase 实时后端)、LocalStorageCollection 与 LocalOnlyCollection(均在 @tanstack/db,分别对应浏览器 localStorage 持久化与仅内存状态)。
使用方式:通过 createCollection 配合对应 options 创建,如 queryCollectionOptions、electricCollectionOptions、localStorageCollectionOptions、localOnlyCollectionOptions。常见配置含 queryKey、queryFn、getKey、schema(可选用 Zod 等做校验与类型转换)、以及 onInsert/onUpdate/onDelete 处理写操作;ElectricCollection 需提供 shapeOptions 并可返回 txid 等待同步。QueryCollection 可传入已有的 QueryClient。
同步模式:syncMode 可选 eager(默认,一次性加载全部,适合约 1 万行以内的较静态数据)、on-demand(仅加载查询请求的数据,适合超过 5 万行、搜索或目录场景)、progressive(先加载子集、后台同步全量,适合协作与首屏快速呈现)。
集合 API:读取用 get、has、toArray、size;写入用 insert、update、delete 并触发表明处理函数;工具方法包括 collection.utils.refetch(QueryCollection)、collection.utils.awaitTxId 与 awaitMatch(ElectricCollection)、acceptMutations(LocalCollection)。
适用场景:需要将 REST、实时同步、离线或本地持久化数据源统一到同一查询模型的前端应用。限制:具体版本兼容、性能指标与安装命令暂未提供。