@firebase/firestore

函数

函数 说明
function(应用, ...)
getFirestore(应用) 返回与提供的 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。
getFirestore(app, databaseId) (Beta 版)返回与提供的 FirebaseApp 关联的现有已命名 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。
initializeFirestore(app, settings, databaseId) 使用提供的设置初始化 Firestore 的新实例。只能在任何其他函数(包括 getFirestore())之前调用。如果自定义设置为空,则此函数等同于调用 getFirestore()
function(firestore, ...)
clearIndexedDbPersistence(firestore) 清除永久性存储空间。其中包括待处理的写入和缓存的文档。必须在 Firestore 实例未启动(在应用终止或应用首次初始化后)时调用。启动时,必须在其他函数(initializeFirestore()getFirestore() 除外)之前调用此函数。如果 Firestore 实例仍在运行,promise 将被拒绝并返回错误代码 failed-precondition注意:clearIndexedDbPersistence() 主要用于帮助编写使用 Cloud Firestore 的可靠测试。它使用高效的机制删除现有数据,但不会尝试安全地覆盖或以其他方式使缓存数据不可恢复。对于在用户会话之间披露缓存数据敏感的应用,我们强烈建议完全不要启用持久化。
collection(firestore, path, pathSegments) 获取引用指定绝对路径下的集合的 CollectionReference 实例。
collectionGroup(firestore, collectionId) 创建并返回一个新的 Query 实例,该实例中包含数据库中具有给定 collectionId 的集合或子集合中包含的所有文档。
connectFirestoreEmulator(firestore, host, port, options) 请修改此实例以与 Cloud Firestore 模拟器进行通信。注意:在使用此实例执行任何操作之前,必须调用此方法。
disableNetwork(firestore) 停用此实例的网络。您可以通过 enableNetwork() 重新启用该网络。网络停用后,所有快照监听器、getDoc()getDocs() 调用都会从缓存中返回结果,所有写入操作都将排入队列,直到网络恢复。
doc(firestore, path, pathSegments) 获取引用指定绝对路径中文档的 DocumentReference 实例。
enableIndexedDbPersistence(firestore, persistentSettings) 如果可能,尝试启用永久性存储。如果失败,enableIndexedDbPersistence() 将拒绝 promise 或抛出异常。导致运行失败的原因有多种,具体可通过错误中的 code 来判断。* 失败前提条件:应用已在其他浏览器标签页中打开。* 未实现:浏览器与离线持久化实现不兼容。请注意,即使发生故障,Firestore 实例仍然可用,但离线持久化将被停用。注意:enableIndexedDbPersistence() 必须在任何其他函数(initializeFirestore()getFirestore()clearIndexedDbPersistence() 除外)之前调用。持久性不能在 Node.js 环境中使用。
enableMultiTabIndexedDbPersistence(firestore) 如果可能,尝试启用多标签页永久性存储。如果在所有标签页上启用,则所有操作都有权访问本地持久性存储,包括在所有已连接的实例中共享执行查询和延迟补偿的本地文档更新。如果失败,enableMultiTabIndexedDbPersistence() 将拒绝 promise 或抛出异常。导致运行失败的原因有多种,具体可通过错误中的 code 来判断。* 前提条件失败:应用已在另一个浏览器标签页中打开,且未启用多标签页功能。* 未实现:浏览器与离线持久化实现不兼容。请注意,即使发生故障,Firestore 实例仍然可用,但离线持久化将被停用。
enableNetwork(firestore) 在之前调用 disableNetwork() 后,重新为此 Firestore 实例重新启用网络。
getPersistentCacheIndexManager(firestore) 返回给定 Firestore 对象使用的 PersistentCache 索引管理器。PersistentCacheIndexManager 实例;如果本地永久性存储空间未使用,则为 null
loadBundle(firestore, bundleData) 将 Firestore 内容包加载到本地缓存中。
NameQuery(firestore, name) 从本地缓存中读取由给定名称标识的 Firestore 查询已命名的查询在服务器端打包成捆绑包(以及生成的文档),并使用 loadBundle 加载到本地缓存。进入本地缓存后,使用此方法按名称提取 Query
onSnapshotsInSync(firestore, observer) 为同步快照事件附加监听器。同步快照事件表示受指定更改影响的所有监听器均已触发,即使服务器生成的单项更改会影响多个监听器也是如此。注意:同步快照事件仅表示监听器彼此同步,而与这些快照是否与服务器同步无关。在各个监听器中使用 SnapshotMetadata 来确定快照是来自缓存还是来自服务器。
onSnapshotsInSync(firestore、onSync) 为同步快照事件附加监听器。同步快照事件表示受指定更改影响的所有监听器均已触发,即使服务器生成的单项更改会影响多个监听器也是如此。注意:同步快照事件仅表示监听器彼此同步,而与这些快照是否与服务器同步无关。在单个监听器中使用 SnapshotMetadata 来确定快照是来自缓存还是来自服务器。
runTransaction(firestore, updateFunction, options) 执行指定的 updateFunction,然后尝试提交在事务中应用的更改。如果事务中读取的任何文档已发生更改,Cloud Firestore 会重试 updateFunction。如果 5 次尝试后仍未提交,则事务将失败。单个事务中允许的最大写入次数为 500。
setIndexConfiguration(firestore, configuration) (Beta 版)为本地查询执行配置索引编制。之前的所有索引配置都会被覆盖。索引配置持久保存后,Promise 便会解析。索引条目本身是异步创建的。即使索引尚不可用,您也可以继续使用需要编入索引的查询。索引条目写入完毕后,查询执行将自动开始使用索引。只有 IndexedDb 持久性支持索引。如果未启用 IndexedDb,系统会忽略任何索引配置。
setIndexConfiguration(firestore, json) (Beta 版)为本地查询执行配置索引编制。之前的所有索引配置都会被覆盖。索引配置持久保存后,Promise 便会解析。索引条目本身是异步创建的。即使索引尚不可用,您也可以继续使用需要编入索引的查询。索引条目写入完毕后,查询执行将自动开始使用索引。只有 IndexedDb 持久性支持索引。在设置索引配置之前,调用 enableIndexedDbPersistence()enableMultiTabIndexedDbPersistence()。如果未启用 IndexedDb,系统会忽略任何索引配置。该方法接受 Firebase CLI (firebase firestore:indexes) 导出的 JSON 格式。如果 JSON 格式无效,此方法会引发错误。
terminate(firestore) 终止提供的 Firestore 实例。调用 terminate() 后,只能使用 clearIndexedDbPersistence() 函数。任何其他函数都会抛出 FirestoreError要在终止后重启,请使用 getFirestore() 创建一个新的 FirebaseFirestore 实例。终止后不会取消任何待处理的写入,并且任何等待服务器响应的 promise 都不会解析。如果您启用了持久化,则下次启动此实例时,它将继续将这些写入操作发送到服务器。注意:正常情况下,不需要调用 terminate()。此函数仅在您希望强制此实例释放其所有资源或与 clearIndexedDbPersistence() 结合使用以确保在两次测试运行之间销毁所有本地状态时有用。
waitForPendingWrites(firestore) 等待后端确认活跃用户当前的所有待处理写入。如果没有未完成的写入,返回的 promise 会立即解析。否则,promise 会等待之前发出的所有写入操作(包括在先前应用会话中写入的写入操作),但不会等待调用函数后添加的写入操作。如果您想等待额外的写入操作,请再次调用 waitForPendingWrites()在用户更改期间,任何未完成的 waitForPendingWrites() promise 都会被拒绝。
writeBatch(firestore) 创建写入批次,用于以单个原子操作的形式执行多次写入。单个 WriteBatch 中允许的最大写入次数为 500 次。与事务不同,批量写入会离线保留,因此,如果不需要根据读取数据调整写入,写入批量操作是首选方法。
函数
count() 创建一个 AggregateField 对象,用于计算查询结果集中的文档数。
deleteField() 返回一个可与 updateDoc()setDoc() 结合使用的标记,同时使用 {merge: true} 标记要删除的字段。
documentId() 返回特殊标记 FieldPath 来引用文档的 ID。它可用于查询,以按文档 ID 进行排序或过滤。
getFirestore() 返回与默认 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。
memoryEagerGarbageCollector() 创建 MemoryEagerGarbageCollector 的实例。除非另行明确指定,否则这也是默认的垃圾回收器。
persistentMultipleTabManager() 创建 PersistentMultipleTabManager 的实例。
serverTimestamp() 返回与 setDoc()updateDoc() 结合使用的 Sentinel,以将服务器生成的时间戳包含在写入的数据中。
function(databaseId, ...)
getFirestore(databaseId) (Beta 版)返回与默认 FirebaseApp 关联的现有已命名 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。
function(元素, ...)
arrayRemove(元素) 返回一个可与 setDoc() 配合使用的特殊值,或者告知服务器从服务器上已存在的任何数组值中移除指定元素。每个指定元素的所有实例都将从数组中移除。如果要修改的字段还不是数组,它将会被一个空数组覆盖。
arrayUnion(元素) 返回一个可与 setDoc()updateDoc() 结合使用的特殊值,该值会指示服务器将给定元素与服务器上已存在的任何数组值联合。数组中尚不存在的每个指定元素都会添加到末尾。如果要修改的字段还不是数组,系统会用仅包含指定元素的数组来覆盖它。
function(字段, ...)
average(field) 创建一个 AggregateField 对象,用于计算查询结果集内一系列文档的指定字段的平均值。
sum(字段) 创建一个 AggregateField 对象,用于计算查询结果集中一系列文档中指定字段的总和。
function(fieldPath, ...)
orderBy(fieldPath, directionsStr) 创建 QueryOrderByConstraint,按指定字段对查询结果进行排序,可选择降序,而非升序。注意:不包含指定字段的文档不会显示在查询结果中。
where(fieldPath, opStr, value) 创建一个 QueryFieldFilterConstraint,用于强制文档必须包含指定字段,并且值应该满足所提供的关系限制条件。
function(fieldValues, ...)
endAt(fieldValues) 创建一个 QueryEndAtConstraint,将结果集修改为相对于查询顺序在提供的字段结束。字段值的顺序必须与查询的“排序依据”子句的顺序一致。
endBefore(fieldValues) 创建一个 QueryEndAtConstraint,它将结果集修改为相对于查询顺序在提供的字段之前结束。字段值的顺序必须与查询的“排序依据”子句的顺序一致。
startAfter(fieldValues) 创建 QueryStartAtConstraint,根据查询的顺序将结果集修改为在提供的字段之后开始。字段值的顺序必须与查询的“排序依据”子句的顺序一致。
startAt(fieldValues) 创建 QueryStartAtConstraint,将结果集修改为相对于查询顺序从提供的字段开始。字段值的顺序必须与查询的“排序依据”子句的顺序一致。
function(indexManager, ...)
deleteAllPersistentCacheIndexes(indexManager) 移除所有永久性缓存索引。请注意,此函数还将删除由已弃用的 setIndexConfiguration() 生成的索引。
disablePersistentCacheIndexAutoCreation(indexManager) 停止为本地查询执行自动创建永久性缓存索引。通过调用 enablePersistentCacheIndexAutoCreation() 创建的索引仍然有效。
enablePersistentCacheIndexAutoCreation(indexManager) 当 SDK 认为缓存索引有助于提高性能时,使 SDK 能够自动为本地查询执行创建永久性缓存索引。此功能默认处于停用状态。
函数(左,...)
aggregateFieldEqual(左,右) 比较两个“AggregateField”实例是否相等。
aggregateQuerySnapshotEqual(左,右) 比较两个 AggregateQuerySnapshot 实例是否相等。两个 AggregateQuerySnapshot 实例被视为“相等”如果它们具有可比较相同且相同数据的基础查询。
queryEqual(左,右) 如果提供的查询指向同一集合并应用相同的约束条件,则返回 true。
refEqual(左,右) 如果提供的引用相等,则返回 true。
SnapshotEqual(左,右) 如果提供的快照相等,则返回 true。
function(limit, ...)
limit(limit) 创建一个仅返回第一个匹配文档的 QueryLimitConstraint
limitToLast(limit) 创建仅返回最后匹配的文档的 QueryLimitConstraint您必须为 limitToLast 查询指定至少一个 orderBy 子句,否则在执行过程中会抛出异常。
function(logLevel, ...)
setLogLevel(logLevel) 设置 Cloud Firestore 日志的详细程度(调试、错误或静默)。
函数(n, ...)
increment(n) 返回可与 setDoc()updateDoc() 一起使用的特殊值,该值会指示服务器按指定值递增字段的当前值。如果操作数或当前字段值使用浮点精度,则所有算术都遵循 IEEE 754 语义。如果这两个值都是整数,则超出 JavaScript 安全数字范围(Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER)的值也会有精度损失。此外,一旦 Firestore 后端进行处理,所有整数操作的上限将介于 -2^63 到 2^63-1 之间。如果当前字段值不是 number 类型,或者该字段尚不存在,转换会将该字段设置为指定值。
函数(query, ...)
getAggregateFromServer(query, aggregateSpec) 计算给定查询结果集中的文档的指定聚合,无需实际下载文档。使用此函数执行聚合非常高效,因为只有最终聚合值,而不是文档的数据。如果结果集非常大,无法全部下载(数千个文档),此函数可以对文档进行聚合。从服务器接收的结果将原封不动地呈现,而不考虑任何本地状态。也就是说,系统不会考虑本地缓存中的文档,也不会考虑尚未与服务器同步的本地修改。系统不会使用之前下载的结果(如果有)。每次调用此函数时都必须往返于服务器。
getCountFromServer(查询) 在不实际下载文档的情况下,计算指定查询的结果集中的文档数量。使用此函数计算文档数量的效率会更高,因为只有最终计数,而不计算文档的数据。在结果集太大而无法全部下载(数千个文档)的情况下,此函数可以统计文档数量。从服务器收到的结果将保持不变,不考虑任何本地状态。也就是说,系统不会考虑本地缓存中的文档,也不会考虑尚未与服务器同步的本地修改。系统不会使用之前下载的结果(如果有)。每次调用此函数时都必须往返于服务器。
getDocs(查询) 执行查询并以 QuerySnapshot 的形式返回结果。注意:getDocs() 会尝试通过等待来自服务器的数据来提供最新数据,但可能会返回缓存的数据,或者,如果您处于离线状态且无法连接到服务器,它可能会返回缓存的数据或失败。如要指定此行为,请调用 getDocsFromCache()getDocsFromServer()
getDocsFromCache(查询) 执行查询并返回缓存中的 QuerySnapshot 结果。如果当前没有缓存与查询匹配的文档,则返回空的结果集。
getDocsFromServer(查询) 执行查询并将结果作为 QuerySnapshot 从服务器返回。如果网络不可用,则返回错误。
onSnapshot(query, 观察者) 附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用调用 onSnapshot 时返回的函数来取消监听器。注意:虽然可以提供 onCompletion 回调,但永远不会调用该回调,因为快照流会无限循环。
onSnapshot(query, options, observer) 附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用调用 onSnapshot 时返回的函数来取消监听器。注意:虽然可以提供 onCompletion 回调,但永远不会调用该回调,因为快照流会无限循环。
onSnapshot(query, onNext, onError, on 完美) 附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用调用 onSnapshot 时返回的函数来取消监听器。注意:虽然可以提供 onCompletion 回调,但永远不会调用该回调,因为快照流会无限循环。
onSnapshot(query, options, onNext, onError, onCompleted) 附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用调用 onSnapshot 时返回的函数来取消监听器。注意:虽然可以提供 onCompletion 回调,但永远不会调用该回调,因为快照流会无限循环。
query(query, compositeFilter, queryConstraints) 创建新的 Query 不可变实例,该实例可通过扩展还包含其他查询限制条件。
query(query, queryConstraints) 创建新的 Query 不可变实例,该实例可通过扩展还包含其他查询限制条件。
function(queryConstraints, ...)
and(queryConstraints) 创建一个新的 QueryCompositeFilterConstraint,它是给定过滤条件约束条件的组合。如果一个文档满足所有指定过滤条件,则关联过滤条件会包含该文档。
或(queryConstraints) 创建一个新的 QueryCompositeFilterConstraint,它是给定过滤条件约束的析取。析取运算包含符合任何给定过滤条件的文档。
function(引用, ...)
addDoc(reference, data) 使用给定数据向指定的 CollectionReference 添加新文档,并自动为其分配文档 ID。
collection(reference, path, pathSegments) 获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。
collection(reference, path, pathSegments) 获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。
deleteDoc(reference) 删除指定的 DocumentReference 引用的文档。
doc(reference, path, pathSegments) 获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。如果未指定路径,将为返回的 DocumentReference 使用自动生成的唯一 ID。
doc(reference, path, pathSegments) 获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。
getDoc(reference) 读取此 DocumentReference 引用的文档。注意:getDoc() 会尝试通过等待服务器发送数据来提供最新数据,但如果您处于离线状态,并且无法连接到服务器,它可能会返回缓存数据或失败。若要指定此行为,请调用 getDocFromCache()getDocFromServer()
getDocFromCache(reference) 从缓存中读取此 DocumentReference 引用的文档。如果文档当前未缓存,则返回错误。
getDocFromServer(参考) 从服务器读取此 DocumentReference 引用的文档。如果网络不可用,则返回错误。
onSnapshot(reference, observer) 附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以使用 nexterror 回调传递单个观察器对象。注意:虽然可以提供 onCompletion 回调,但永远不会调用它,因为快照流永无止境。
onSnapshot(reference, options, observer) 附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以使用 nexterror 回调传递单个观察器对象。注意:虽然可以提供 onCompletion 回调,但永远不会调用它,因为快照流永无止境。
onSnapshot(reference, onNext, onError, onCompleted) 附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以使用 nexterror 回调传递单个观察器对象。注意:虽然可以提供 onCompletion 回调,但永远不会调用它,因为快照流永无止境。
onSnapshot(reference, options, onNext, onError, onCompleted) 附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以使用 nexterror 回调传递单个观察器对象。注意:虽然可以提供 onCompletion 回调,但永远不会调用它,因为快照流永无止境。
setDoc(reference, data) 对此 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在,系统将会创建该文档。
setDoc(reference, data, options) 对指定的 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在,系统将会创建该文档。如果您提供 mergemergeFields,则所提供的数据可以合并到现有文档中。
updateDoc(reference, data) 更新由指定 DocumentReference 引用的文档中的字段。如果应用于不存在的文档,更新将失败。
updateDoc(reference, field, value, moreFieldsAndValues) 对指定的 DocumentReference 引用的文档中的字段进行更新。如果将更新应用于不存在的文档,系统会更新嵌套字段。您可以通过提供以英文句点分隔的字段路径字符串或提供 FieldPath 对象来更新嵌套字段。
function(settings, ...)
memoryLocalCache(设置) 创建 MemoryLocalCache 的实例。该实例可设置为 FirestoreSettings.cache,以告知 SDK 应使用哪个缓存层。
memoryLruGarbageCollector(设置) 创建 MemoryLruGarbageCollector 的实例。您可以在设置参数中指定目标尺寸。一旦缓存大小超过给定大小,收集器就会开始删除文档。默认缓存大小为 40MB(40 * 1024 * 1024 字节)。
persistentLocalCache(设置) 创建 PersistentLocalCache 的实例。实例可以设置为 FirestoreSettings.cache,以告知 SDK 使用哪个缓存层。无法在 Node.js 环境中使用永久性缓存。
persistentSingleTabManager(设置) 创建 PersistentSingleTabManager 的实例。
function(快照, ...)
endAt(快照) 创建 QueryEndAtConstraint,将结果集修改为以提供的文档(含边界值)结束。结束位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。
endBefore(快照) 创建一个 QueryEndAtConstraint,将结果集修改为在提供的文档之前结束(不含边界值)。结束位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。
startAfter(Snapshot) 创建 QueryStartAtConstraint,将结果集修改为在提供的文档之后开始(不包含结果)。起始位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。
startAt(快照) 创建 QueryStartAtConstraint,将结果集修改为从提供的文档(含)开始。起始位置是相对于查询顺序而言的。该文档必须包含此查询的 orderBy 中提供的所有字段。
function(values, ...)
vector(values) 创建使用给定数字数组的副本构造的新 VectorValue

说明
AggregateField 表示可以由 Firestore 执行的聚合。
AggregateQuerySnapshot 执行聚合查询的结果。
字节 表示字节数组的不可变对象。
CollectionReference CollectionReference 对象可用于添加文档、获取文档引用和查询文档(使用 query())。
文档引用 DocumentReference 是指文档在 Firestore 数据库中的位置,可用于写入、读取或监听该位置。引用位置的文件可能不存在。
文档快照 DocumentSnapshot 包含从 Firestore 数据库中的文档读取的数据。您可以使用 .data().get(<field>) 提取数据,以获取特定字段。对于指向不存在文档的 DocumentSnapshot,任何数据访问都将返回“undefined”。您可以使用 exists() 方法明确验证某个文档是否存在。
FieldPath FieldPath 是指文档中的字段。路径可以由单个字段名称(引用文档中的顶级字段)或一系列字段名称(引用文档中的嵌套字段)组成。提供字段名称来创建 FieldPath。如果提供了多个字段名称,则路径将指向文档中的嵌套字段。
FieldValue 使用 set()update() 写入文档字段时可以使用的 Sentinel 值。
Firestore Cloud Firestore 服务接口。请勿直接调用此构造函数,请改用 getFirestore()
FirestoreError Firestore 操作返回的错误。
GeoPoint Firestore 中表示地理位置的不可变对象。该位置以纬度/经度对表示。纬度值在 [-90, 90] 的范围内。经度值在 [-180, 180] 的范围内。
LoadBundleTask 表示加载 Firestore 软件包的任务。它提供了软件包加载的进度,以及任务完成和错误事件。该 API 与 Promise<LoadBundleTaskProgress> 兼容。
PersistentCacheIndexManager PersistentCacheIndexManager,用于配置用于执行本地查询的永久性缓存索引。如需使用,请调用 getPersistentCacheIndexManager() 以获取实例。
查询 Query 是指您可以读取或监听的查询。您还可以通过添加过滤条件和排序来构建经过优化的 Query 对象。
QueryCompositeFilterConstraint QueryCompositeFilterConstraint 用于通过对多个 QueryFieldFilterConstraintQueryCompositeFilterConstraint 执行逻辑 OR 或 AND 来缩小 Firestore 查询返回的文档集。QueryCompositeFilterConstraint 通过调用 or()and() 创建,然后可以传递给 query() 以创建包含 QueryCompositeFilterConstraint 的新查询实例。
QueryConstraint QueryConstraint 用于缩小 Firestore 查询返回的文档集的范围。QueryConstraint 是通过调用 where()orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast() 等方法创建的,然后便可将此 QueryConstraintquery() 传递给新的 QueryConstraintquery()。
QueryDocumentSnapshot QueryDocumentSnapshot 包含作为查询的一部分从 Firestore 数据库的文档读取的数据。该文档一定会存在,并且可以使用 .data().get(<field>) 提取其数据,以获取特定字段。QueryDocumentSnapshotDocumentSnapshot 提供相同的 API Surface。由于查询结果仅包含现有文档,因此 exists 属性将始终为 true,而 data() 绝不会返回“undefined”。
QueryEndAtConstraint QueryEndAtConstraint 用于从 Firestore 查询返回的结果集的末尾排除文档。QueryEndAtConstraint 通过调用 endAt()endBefore() 来创建,然后可以传递给 query() 来创建包含此 QueryEndAtConstraint 的新查询实例。
QueryFieldFilterConstraint QueryFieldFilterConstraint 用于通过过滤一个或多个文档字段来缩小 Firestore 查询返回的文档集的范围。QueryFieldFilterConstraint 通过调用 where() 创建,然后可以传递给 query() 以创建包含此 QueryFieldFilterConstraint 的新查询实例。
QueryLimitConstraint QueryLimitConstraint 用于限制 Firestore 查询返回的文档数量。QueryLimitConstraint 是通过调用 limit()limitToLast() 创建的,然后可以将其传递给 query() 来创建包含此 QueryLimitConstraint 的新查询实例。
QueryOrderByConstraint QueryOrderByConstraint 用于对 Firestore 查询返回的文档集进行排序。QueryOrderByConstraint 通过调用 orderBy() 创建,然后可以传递给 query() 以创建包含此 QueryOrderByConstraint 的新查询实例。注意:不包含 orderBy 字段的文档不会显示在查询结果中。
QuerySnapshot QuerySnapshot 包含零个或多个表示查询结果的 DocumentSnapshot 对象。您可以通过 docs 属性以数组的形式访问这些文档,也可以使用 forEach 方法枚举这些文档。您可以通过 emptysize 属性确定文档数量。
QueryStartAtConstraint QueryStartAtConstraint 用于从 Firestore 查询返回的结果集的开头排除文档。QueryStartAtConstraint 通过调用 startAt()startAfter() 来创建,然后可以传递给 query() 来创建包含此 QueryStartAtConstraint 的新查询实例。
SnapshotMetadata 有关快照的元数据,用于描述快照的状态。
时间戳 Timestamp 表示与任何时区或日历无关的时间点,以纳秒精度表示(以 UTC 新纪元时间为准),以纳秒为单位表示秒数和小数。它使用前公历进行编码,可将公历向前扩展到第一年。其编码假设每分钟的时长均为 60 秒,即闰秒经过均匀分布处理,因此不需要使用闰秒表进行解释。范围是 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。如需查看示例和其他规范,请参阅时间戳定义
事务 对事务的引用。传递到事务的 updateFunctionTransaction 对象提供了在事务上下文中读取和写入数据的方法。请参阅 runTransaction()
VectorValue 表示 Firestore 文档中的矢量类型。使用 创建实例。矢量值
WriteBatch 批量写入,用于以单个原子单元的形式执行多次写入。可通过调用 writeBatch() 获取 WriteBatch 对象。它提供了将写入添加到批量写入的方法。在调用 WriteBatch.commit() 之前,所有写入操作都不会提交(或在本地可见)。

接口

接口 说明
AggregateSpec 指定一组聚合及其别名。
文档更改 DocumentChange 表示与查询匹配的文档发生的更改。其中包含受影响的文档以及已发生的更改类型。
文档数据 文档数据(与 setDoc() 一起使用)由映射到值的字段组成。
ExperimentalLongPollingOptions 用于配置使用长轮询时 SDK 底层网络传输 (WebChannel) 的选项。注意:此接口是“实验性”接口并可能会发生变化。请参阅“FirestoreSettings.experimentalAutoDetectLongPolling”、“FirestoreSettings.experimentalForceLongPolling”和“FirestoreSettings.experimentalLongPollingOptions”。
FirestoreDataConverter withConverter() 使用的转换器,用于将 AppModelType 类型的用户对象转换为 DbModelType 类型的 Firestore 数据。通过使用该转换器,您可以在从 Firestore 存储和检索对象时指定通用类型参数。在此上下文中,“AppModel”是在应用中使用,用于将相关信息和功能打包在一起的类。例如,此类类可能包含复杂的嵌套数据类型、用于记忆的属性、Firestore 不支持的类型的属性(例如 symbolbigint),以及执行复合操作的辅助函数。此类类不适合和/或无法存储到 Firestore 数据库中。需要将此类类的实例转换为“普通的旧 JavaScript 对象”(POJO) 只具有完全基本的属性,可能嵌套在其他 POJO 或 POJO 数组中。在此上下文中,这种类型称为“DbModel”并且会是一个适合持久保存到 Firestore 的对象。为方便起见,应用可以实现 FirestoreDataConverter 并使用 Firestore 对象(例如 DocumentReferenceQuery)注册转换器,以便在存储到 Firestore 时自动将 AppModel 转换为 DbModel,并在从 Firestore 检索时将 DbModel 转换为 AppModel
FirestoreSettings 指定 Cloud Firestore 实例的自定义配置。您必须在调用任何其他方法之前设置这些变量。
索引 (Beta 版):Firestore 索引的 SDK 定义。
IndexConfiguration (Beta 版)用于加快本地查询执行速度的 Firestore 索引列表。如需查看索引定义格式的说明,请参阅 JSON 格式
IndexField (Beta 版)索引配置中的单个字段元素。
LoadBundleTaskProgress 表示进度更新或加载 bundle 的最终状态。
MemoryCacheSettings 用于配置 MemoryLocalCache 实例的设置对象。
MemoryEagerGarbageCollector 只要文档不属于任何活跃查询,并且没有附加任何本地变更,垃圾回收器就会删除文档。此收集器会尝试确保 SDK 占用的内存最小,但存在没有为离线查询或直接查询缓存而缓存文档的风险。使用工厂函数创建此收集器的实例。
MemoryLocalCache 为 SDK 提供内存缓存。除非另行明确配置,否则这就是默认缓存。若要使用缓存,请使用工厂函数 创建一个实例,然后将该实例设置为 FirestoreSettings.cache 并使用设置对象调用 initializeFirestore
MemoryLruGarbageCollector 垃圾回收器会分批删除最近最少使用的文档。此收集器配置了目标大小,并且只会在缓存的文档超过目标大小时执行收集。这样可以避免针对同一查询或文档重复在后端执行查询,但存在占用更多内存的风险。请使用工厂函数创建此收集器的实例。
PersistenceSettings 可传递给 enableIndexedDbPersistence() 以配置 Firestore 持久性的设置。持久性不能在 Node.js 环境中使用。
PersistentCacheSettings 用于配置 PersistentLocalCache 实例的设置对象。永久性缓存不能在 Node.js 环境中使用。
PersistentLocalCache 为 SDK 提供由 IndexedDb 支持的永久性缓存。如需使用,请使用工厂函数 创建一个实例,然后将该实例设置为 FirestoreSettings.cache 并使用设置对象调用 initializeFirestore
PersistentMultipleTabManager 支持多个标签页的标签页管理器。SDK 将使用 SDK 同步所有标签页中完成的查询和变更。
PersistentSingleTabManager 标签页管理器仅支持一个标签页,不会在标签页之间执行同步。
PersistentSingleTabManagerSettings 输入以配置 PersistentSingleTabManager 实例。
SnapshotListenOptions 可以传递给 onSnapshot()QuerySnapshot.docChanges() 的选项对象,以控制要在结果集中包含哪些类型的更改。
SnapshotOptions 用于配置如何从 DocumentSnapshot 检索数据的选项(例如,尚未设为最终值的服务器时间戳的所需行为)。
TransactionOptions 用于自定义交易行为的选项。
退订 onSnapshot() 返回的一个函数,可在调用时移除监听器。

变量

变量 说明
CACHE_SIZE_UNLIMITED 一个常量,用于指示应停用 LRU 垃圾回收。在传递给 Firestore 实例的设置中,将此值设置为 cacheSizeBytes

类型别名

类型别名 说明
AddPrefixToKeys 返回一个新的映射,其中每个键的前缀都是附加到一个点的外部键。
AggregateFieldType Firestore 支持的所有 AggregateField 类型的并集。
AggregateSpecData 一个类型,其键取自 AggregateSpec,其值是输入 AggregateSpec 中的相应 AggregateField 执行聚合的结果。
汇总类型 表示要执行的聚合类型的联合类型。
ChildUpdateFields 用于计算给定类型 T1 的嵌套字段的帮助程序。需要这样做,才能分发 undefined | {...}(可选属性)或 {a: A} | {b: B} 等并集类型。在这个用例中,V 用于在 Record 上分布 T[K] 的并集类型,因为 T[K] 被评估为表达式,而不是分布式。请参阅 https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
DocumentChangeType DocumentChange 的类型可能是“已添加”、“已移除”或“修改”。
FirestoreErrorCode Firestore 状态代码集。这些代码与 gRPC 在此处公开的代码相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md可能的值:-“cancelled”:操作已取消(通常是被调用方取消)。-“未知”:未知错误或来自其他错误域的错误。- 'invalid- arguments':客户端指定的参数无效。请注意,这与“failed-precondition”不同。“无效参数”表示无论系统状态如何,都会有问题的参数(例如无效的字段名称)。- 'deadline-exceeded':截止期限已过,操作还未完成。对于更改系统状态的操作,即使操作已成功完成,也可能会返回此错误。例如,服务器的成功响应延迟时间过长,截止期限已过。-“not-found”:未找到所请求的某些文档。- “ already-exists”:我们尝试创建的某个文档已存在。-“permission-denied”:调用方没有执行指定操作的权限。-“resource-exhausted”:部分资源已用尽,可能是每个用户的配额不足,也可能是因为整个文件系统空间不足。- 'failed-precondition':操作被拒绝,因为系统未处于执行操作所需的状态。- “aborted”:操作被取消,通常是由于事务中止等并发问题。-“超出范围”:尝试操作超出了有效范围。-“未实现”:操作未实现或不受支持/启用。-“internal”:内部错误。这意味着底层系统所期望的一些不变量已损坏。如果您看到上述某个错误,则表明某些地方已损坏。-“unavailable”:服务当前不可用。这很可能是一种暂时情况,可以通过退避重试来纠正。-“data-loss”:不可恢复的数据丢失或损坏。-“unauthenticated”:请求未包含相应操作的有效身份验证凭据。
FirestoreLocalCache 所有受支持的 SDK 缓存层中的联合类型。
ListenSource 描述查询监听的来源。设置为 default 可监听缓存和服务器更改。设置为 cache 可仅监听缓存中的更改。
MemoryGarbageCollector 针对内存本地缓存的所有支持垃圾回收器中的联合类型。
NestedUpdateFields 对于每个字段(例如“bar”),找出所有嵌套的键(例如 {'bar.baz': T1, 'bar.qux': T2})。将它们相交形成一个映射,其中包含所有可能的键(这些键均标记为可选)
OrderByDirection orderBy() 子句的方向指定为“desc”或“asc”(降序或升序)。
PartialWithFieldValue 与 TypeScript 的 Partial<T> 类似,但允许省略嵌套字段,并允许将 FieldValues 作为属性值传入。
PersistentTabManager 所有可用标签页管理器的并集。
初始 基元类型。
QueryConstraintType 介绍此 SDK 中提供的不同查询限制。
QueryFilterConstraint QueryFilterConstraint 是一种辅助联合类型,表示 QueryFieldFilterConstraintQueryCompositeFilterConstraint
QueryNonFilterConstraint QueryNonFilterConstraint 是一种辅助联合类型,表示 QueryConstraint,用于缩小文档集或对文档集进行排序,但不会明确过滤文档字段。QueryNonFilterConstraint 是通过调用 orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast() 来创建,然后可以传递到 query() 中也包含相应新查询。/}QueryConstraint
SetOptions 一个选项对象,用于配置 setDoc() 的行为和调用。通过提供带有 merge: trueSetOptions,可以将这些调用配置为执行精细的合并,而不是将目标文档全部覆盖。
TaskState 表示软件包加载任务的状态。“错误”和和“Success”(成功)正在接收器状态:任务将中止或完成,并且在更新报告后,将不再有更新。
UnionToIntersection 给定并集类型 U = T1 | T2 | ...,返回相交类型 (T1 & T2 & ...)使用分配条件类型并根据条件类型进行推断。这之所以有效,是因为同一类型变量在反向变体位置有多个候选对象会导致推断交集类型。https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type
更新数据 更新由映射到值的字段路径(例如“foo”或“foo.baz”)构成的数据(与 updateDoc() 搭配使用)。包含点的字段会引用文档中的嵌套字段。FieldValues 可以作为属性值传入。
whereFilterOp where() 子句中的过滤条件是使用字符串“&lt;”“<
WithFieldValue 允许在保持类型安全的同时将 FieldValues 作为属性值传入。

function(应用, ...)

getFirestore(应用)

返回与提供的 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。

签名

export declare function getFirestore(app: FirebaseApp): Firestore;

参数

参数 类型 说明
应用 FirebaseApp 与返回的 Firestore 实例相关联的 FirebaseApp 实例。

返回

Firestore

所提供应用的默认 Firestore 实例。

getFirestore(应用, databaseId)

此 API 是为开发者提供的预览版,可能会根据我们收到的反馈发生变化。请勿在生产环境中使用此 API。

返回与提供的 FirebaseApp 关联的现有已命名 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。

签名

export declare function getFirestore(app: FirebaseApp, databaseId: string): Firestore;

参数

参数 类型 说明
应用 FirebaseApp 与返回的 Firestore 实例相关联的 FirebaseApp 实例。
数据库 ID 字符串 数据库的名称。

返回

Firestore

所提供应用的已命名 Firestore 实例。

initializeFirestore(应用, 设置, 数据库 ID)

使用提供的设置初始化 Firestore 的新实例。只能在任何其他函数(包括 getFirestore())之前调用。如果自定义设置为空,则此函数等同于调用 getFirestore()

签名

export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore;

参数

参数 类型 说明
应用 FirebaseApp 要与 Firestore 实例相关联的 FirebaseApp
设置 FirestoreSettings 用于配置 Firestore 实例的设置对象。
数据库 ID 字符串 数据库的名称。

返回

Firestore

新初始化的 Firestore 实例。

function(firestore, ...)

clearIndexedDbPersistence(firestore)

清除永久性存储空间。这包括待处理的写入和缓存的文档。

必须在 Firestore 实例未启动(在应用终止或应用首次初始化后)时调用。启动时,必须在其他函数(initializeFirestore()getFirestore() 除外)之前调用此函数。如果 Firestore 实例仍在运行,promise 将被拒绝,并显示错误代码 failed-precondition

签名

export declare function clearIndexedDbPersistence(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore 要清除保留数据的 Firestore 实例。

返回

承诺<void>

清除永久性存储空间时解析的 Promise。否则,promise 会被拒绝并报错。

collection(firestore、path、pathSegments)

获取引用指定绝对路径下的集合的 CollectionReference 实例。

签名

export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

参数

参数 类型 说明
firestore Firestore 对根 Firestore 实例的引用。
路径 字符串 以斜杠分隔的集合路径。
路径细分 字符串[] 要应用的其他路径细分(相对于第一个参数)。

返回

CollectionReference<DocumentDataDocumentData>

CollectionReference 实例。

异常

最终路径中路段数量为偶数,且未指向集合。

collectionGroup(firestore, collectionId)

创建并返回一个新的 Query 实例,该实例中包含数据库中具有给定 collectionId 的集合或子集合中包含的所有文档。

签名

export declare function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData, DocumentData>;

参数

参数 类型 说明
firestore Firestore 对根 Firestore 实例的引用。
集合 ID 字符串 标识要查询的集合。将包含此 ID 作为其路径最后一段的每个集合或子集合。不能包含斜杠。

返回

查询<DocumentData, DocumentData>

已创建“Query”。

connectFirestoreEmulator(firestore、host、 port、 options)

修改此实例以与 Cloud Firestore 模拟器进行通信。

签名

export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: {
    mockUserToken?: EmulatorMockTokenOptions | string;
}): void;

参数

参数 类型 说明
firestore Firestore 要配置为连接到模拟器的 Firestore 实例。
主机 字符串 模拟器主机(例如:localhost)。
端口 数字 模拟器端口(例如:9000)。
选项 { mockUserToken?:EmulatorMockTokenOptions |字符串;}

返回

void

停用网络(firestore)

停用此实例的网络。您可以通过 enableNetwork() 重新启用该网络。网络停用后,所有快照监听器、getDoc()getDocs() 调用都会从缓存中返回结果,所有写入操作都将排入队列,直到网络恢复。

签名

export declare function disableNetwork(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore

返回

承诺<void>

在网络停用后解析的 Promise

doc(firestore、path、pathSegments)

获取引用指定绝对路径中文档的 DocumentReference 实例。

签名

export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;

参数

参数 类型 说明
firestore Firestore 对根 Firestore 实例的引用。
路径 字符串 以斜杠分隔的文档路径。
路径细分 字符串[] 将相对于第一个参数应用的其他路径细分。

返回

DocumentReference<DocumentDataDocumentData>

DocumentReference 实例。

异常

最终路径的段数为奇数,且未指向文档。

enableIndexedDbPersistence(firestore、persistentSettings)

<ph type="x-smartling-placeholder">
</ph>

我们将在未来的主要版本中移除此函数。请改为将 FirestoreSettings.localCache 设置为 PersistentLocalCache 的实例,以启用 IndexedDb 缓存。在已指定 FirestoreSettings.localCache 的情况下调用此函数会抛出异常。

如果可能,尝试启用永久性存储。

如果失败,enableIndexedDbPersistence() 将拒绝 promise 或抛出异常。有多种原因会导致失败,这些原因可通过错误的 code 来确定。

* failed-precondition:应用已在其他浏览器标签页中打开。* 未实现:浏览器与离线持久化实现不兼容。

请注意,即使发生故障,Firestore 实例仍然可用,但离线持久化会被停用。

Node.js 环境中无法使用持久性。

签名

export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;

参数

参数 类型 说明
firestore Firestore 要为其启用持久化的 Firestore 实例。
持久性设置 PersistenceSettings 用于配置保留的可选设置对象。

返回

承诺<void>

Promise,表示已成功启用永久性存储。

enableMultiTabIndexedDbPersistence(firestore)

<ph type="x-smartling-placeholder">
</ph>

我们将在未来的主要版本中移除此函数。请改为将 FirestoreSettings.localCache 设置为 PersistentLocalCache 的实例,以启用 indexdb 缓存。在已指定 FirestoreSettings.localCache 的情况下调用此函数会抛出异常。

如果可能,尝试启用多标签页永久性存储。如果在所有标签页上启用,则所有操作都有权访问本地持久性存储,包括在所有已连接的实例中共享执行查询和以延迟方式补偿的本地文档更新。

如果失败,enableMultiTabIndexedDbPersistence() 将拒绝 promise 或抛出异常。有多种原因会导致失败,这些原因可通过错误的 code 来确定。

* failed-precondition:应用已在其他浏览器标签页中打开,且未启用多标签页功能。* 未实现:浏览器与离线持久化实现不兼容。

请注意,即使发生故障,Firestore 实例仍然可用,但离线持久化会被停用。

签名

export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore 要为其启用持久化的 Firestore 实例。

返回

承诺<void>

Promise,表示已成功启用永久性存储。

enableNetwork(firestore)

在之前调用 disableNetwork() 后,重新为此 Firestore 实例重新启用网络。

签名

export declare function enableNetwork(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore

返回

承诺<void>

启用网络后解析的 Promise

getPersistentCacheIndexManager(firestore)

返回给定 Firestore 对象使用的 PersistentCache 索引管理器。

PersistentCacheIndexManager 实例;如果本地永久性存储空间未使用,则为 null

签名

export declare function getPersistentCacheIndexManager(firestore: Firestore): PersistentCacheIndexManager | null;

参数

参数 类型 说明
firestore Firestore

返回

PersistentCacheIndexManager |null

loadBundle(firestore, bundleData)

将 Firestore 内容包加载到本地缓存中。

签名

export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;

参数

参数 类型 说明
firestore Firestore 要为其加载内容包的 Firestore 实例。
bundleData ReadableStream<Uint8Array>|ArrayBuffer |字符串 表示要加载的 bundle 的对象。有效对象为 ArrayBufferReadableStream<Uint8Array>string

返回

LoadBundleTask

LoadBundleTask 对象,用于向调用方通知进度更新以及完成或错误事件。它可用作 Promise<LoadBundleTaskProgress>

nameQuery(firestore, name)

从本地缓存中读取由给定名称标识的 Firestore Query

命名的查询会在服务器端打包成 bundle(以及生成的文档),并使用 loadBundle 加载到本地缓存中。进入本地缓存后,使用此方法按名称提取 Query

签名

export declare function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;

参数

参数 类型 说明
firestore Firestore 要从中读取查询的 Firestore 实例。
名称 字符串 查询的名称。

返回

Promise<查询 |null>

使用 Query 或 null 解析的 Promise

onSnapshotsInSync(firestore, 观察者)

为同步快照事件附加监听器。同步快照事件表示受指定更改影响的所有监听器均已触发,即使服务器生成的单项更改会影响多个监听器,也是如此。

注意:Snapshot-in-sync 事件仅表示监听器彼此同步,而与这些快照是否与服务器同步无关。在各个监听器中使用 SnapshotMetadata 来确定快照是来自缓存还是来自服务器。

签名

export declare function onSnapshotsInSync(firestore: Firestore, observer: {
    next?: (value: void) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

参数

参数 类型 说明
firestore Firestore 用于同步快照的 Firestore 实例。
观察者 {下一个?:(值:void)=>无效;错误?:(错误:FirestoreError)=>无效;完成?:() =>无效;} 包含 nexterror 回调的单个对象。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshotsInSync(firestore、onSync)

为同步快照事件附加监听器。同步快照事件表示受指定更改影响的所有监听器均已触发,即使服务器生成的单项更改会影响多个监听器,也是如此。

注意:Snapshot-in-sync 事件仅表示监听器彼此同步,而与这些快照是否与服务器同步无关。在单个监听器中使用 SnapshotMetadata 来确定快照是来自缓存还是来自服务器。

签名

export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe;

参数

参数 类型 说明
firestore Firestore 用于同步快照的 Firestore 实例。
onSync () =>无效 每次所有快照监听器彼此同步时要调用的回调。

返回

退订

可调用以取消快照监听器的退订函数。

runTransaction(firestore, updateFunction, options)

执行指定的 updateFunction,然后尝试提交在事务中应用的更改。如果事务中读取的任何文档已发生更改,Cloud Firestore 会重试 updateFunction。如果 5 次尝试后仍未提交,则事务将失败。

单个事务中允许的最大写入次数为 500。

签名

export declare function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;

参数

参数 类型 说明
firestore Firestore 对要运行此事务的 Firestore 数据库的引用。
updateFunction (交易:交易)=>承诺<T> 要在事务上下文中执行的函数。
选项 TransactionOptions 用于配置提交尝试次数上限的选项对象。

返回

承诺<T>

如果事务成功完成或被明确取消(updateFunction 返回一个失败的 promise),则 updateFunction 返回的 promise 会在此处返回。否则,如果事务失败,系统将返回一个被拒绝的 promise 以及相应的失败错误。

setIndexConfiguration(firestore, configuration)

此 API 是为开发者提供的预览版,可能会根据我们收到的反馈发生变化。请勿在生产环境中使用此 API。

。 <ph type="x-smartling-placeholder">
</ph>

不妨考虑使用 enablePersistentCacheIndexAutoCreation(),让 SDK 决定是否为本地运行的查询创建缓存索引,而不是手动创建缓存索引。

为本地查询执行配置索引编制。之前的所有索引配置都会被覆盖。保存索引配置后,Promise 便会进行解析。

索引条目本身是异步创建的。即使索引尚不可用,您也可以继续使用需要编入索引的查询。写入索引条目后,查询执行将自动开始使用索引。

只有 IndexedDb 持久性支持索引。如果未启用 IndexedDb,系统会忽略任何索引配置。

签名

export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise<void>;

参数

参数 类型 说明
firestore Firestore 要为其配置索引的 Firestore 实例。
配置 IndexConfiguration 索引定义。

返回

承诺<void>

成功配置所有索引后解析的 Promise

异常

如果 JSON 格式无效,则会发生 FirestoreError。

setIndexConfiguration(firestore, json)

此 API 是为开发者提供的预览版,可能会根据我们收到的反馈发生变化。请勿在生产环境中使用此 API。

。 <ph type="x-smartling-placeholder">
</ph>

不妨考虑使用 enablePersistentCacheIndexAutoCreation(),让 SDK 决定是否为本地运行的查询创建缓存索引,而不是手动创建缓存索引。

为本地查询执行配置索引编制。之前的所有索引配置都会被覆盖。保存索引配置后,Promise 便会进行解析。

索引条目本身是异步创建的。即使索引尚不可用,您也可以继续使用需要编入索引的查询。写入索引条目后,查询执行将自动开始使用索引。

只有 IndexedDb 持久性支持索引。在设置索引配置之前,调用 enableIndexedDbPersistence()enableMultiTabIndexedDbPersistence()。如果未启用 IndexedDb,系统会忽略任何索引配置。

该方法接受 Firebase CLI 导出的 JSON 格式 (firebase firestore:indexes)。如果 JSON 格式无效,此方法会引发错误。

签名

export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise<void>;

参数

参数 类型 说明
firestore Firestore 要为其配置索引的 Firestore 实例。
json 字符串 Firebase CLI 导出的 JSON 格式。

返回

承诺<void>

成功配置所有索引后解析的 Promise

异常

如果 JSON 格式无效,则会发生 FirestoreError。

终止(firestore)

终止提供的 Firestore 实例。

调用 terminate() 后,只能使用 clearIndexedDbPersistence() 函数。任何其他函数都会抛出 FirestoreError

如需在终止后重启,请使用 getFirestore() 创建一个新的 FirebaseFirestore 实例。

终止操作不会取消任何待处理的写入,并且不会解析任何等待服务器响应的 promise。如果您启用了持久化,则下次启动此实例时,它将继续将这些写入操作发送到服务器。

签名

export declare function terminate(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore

返回

承诺<void>

实例成功终止后解析的 Promise

waitForPendingWrites(firestore)

等待后端确认活跃用户当前的所有待处理写入。

如果不存在未完成的写入,则返回的 promise 会立即解析。否则,promise 会等待之前发出的所有写入操作(包括在先前应用会话中写入的写入操作),但不会等待调用函数后添加的写入操作。如果您想等待其他写入操作,请再次调用 waitForPendingWrites()

在用户更改期间,任何未完成的 waitForPendingWrites() promise 都会被拒绝。

签名

export declare function waitForPendingWrites(firestore: Firestore): Promise<void>;

参数

参数 类型 说明
firestore Firestore

返回

承诺<void>

Promise,可在后端确认当前待处理的写入操作后解析。

writeBatch(firestore)

创建写入批次,用于以单个原子操作的形式执行多次写入。单个 WriteBatch 中允许的最大写入次数为 500。

与事务不同,批量写入会离线保留,因此如果不需要根据读取数据调整写入,批量写入是首选方法。

签名

export declare function writeBatch(firestore: Firestore): WriteBatch;

参数

参数 类型 说明
firestore Firestore

返回

WriteBatch

可用于以原子方式执行多项写入的 WriteBatch

function()

计数()

创建一个 AggregateField 对象,用于计算查询结果集中的文档数。

签名

export declare function count(): AggregateField<number>;

返回

汇总字段<数字>

deleteField()

返回一个可与 updateDoc()setDoc() 结合使用的标记,同时使用 {merge: true} 标记要删除的字段。

签名

export declare function deleteField(): FieldValue;

返回

FieldValue

documentId()

返回特殊标记 FieldPath 来引用文档的 ID。它可用于查询,以按文档 ID 进行排序或过滤。

签名

export declare function documentId(): FieldPath;

返回

FieldPath

getFirestore()

返回与默认 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。

签名

export declare function getFirestore(): Firestore;

返回

Firestore

默认应用的默认 Firestore 实例。

memoryEagerGarbageCollector()

创建 MemoryEagerGarbageCollector 的实例。除非另行明确指定,否则这也是默认的垃圾回收器。

签名

export declare function memoryEagerGarbageCollector(): MemoryEagerGarbageCollector;

返回

MemoryEagerGarbageCollector

PersistentMultipleTabManager()

创建 PersistentMultipleTabManager 的实例。

签名

export declare function persistentMultipleTabManager(): PersistentMultipleTabManager;

返回

PersistentMultipleTabManager

serverTimestamp()

返回与 setDoc()updateDoc() 结合使用的 Sentinel,以将服务器生成的时间戳包含在写入的数据中。

签名

export declare function serverTimestamp(): FieldValue;

返回

FieldValue

function(databaseId, ...)

getFirestore(databaseId)

此 API 是为开发者提供的预览版,可能会根据我们收到的反馈发生变化。请勿在生产环境中使用此 API。

返回与默认 FirebaseApp 关联的现有已命名 Firestore 实例。如果不存在实例,则使用默认设置初始化新实例。

签名

export declare function getFirestore(databaseId: string): Firestore;

参数

参数 类型 说明
数据库 ID 字符串 数据库的名称。

返回

Firestore

默认应用的已命名 Firestore 实例。

function(元素, ...)

数组 Remove(元素)

返回一个可与 setDoc() 配合使用的特殊值,或者告知服务器从服务器上已存在的任何数组值中移除指定元素。每个指定元素的所有实例都将从数组中移除。如果要修改的字段还不是数组,它将会被一个空数组覆盖。

签名

export declare function arrayRemove(...elements: unknown[]): FieldValue;

参数

参数 类型 说明
elements 未知 [] 要从数组中移除的元素。

返回

FieldValue

在调用 setDoc()updateDoc() 时使用的 FieldValue 标记

数组 Union(元素)

返回一个可与 setDoc()updateDoc() 结合使用的特殊值,该值会指示服务器将给定元素与服务器上已存在的任何数组值联合。数组中尚不存在的每个指定元素都会添加到末尾。如果要修改的字段还不是数组,系统会用仅包含指定元素的数组来覆盖它。

签名

export declare function arrayUnion(...elements: unknown[]): FieldValue;

参数

参数 类型 说明
elements 未知 [] 要联合到数组中的元素。

返回

FieldValue

在调用 setDoc()updateDoc() 时使用的 FieldValue 标记。

function(字段, ...)

平均(字段)

创建一个 AggregateField 对象,用于计算查询结果集内一系列文档的指定字段的平均值。

签名

export declare function average(field: string | FieldPath): AggregateField<number | null>;

参数

参数 类型 说明
字段 字符串 |FieldPath 指定要计算结果集中平均值的字段。

返回

AggregateField<数字 |null>

求和(字段)

创建一个 AggregateField 对象,用于计算查询结果集中一系列文档中指定字段的总和。

签名

export declare function sum(field: string | FieldPath): AggregateField<number>;

参数

参数 类型 说明
字段 字符串 |FieldPath 指定对结果集中进行求和的字段。

返回

汇总字段<数字>

function(fieldPath, ...)

orderBy(fieldPath, directionStr)

创建 QueryOrderByConstraint,按指定字段对查询结果进行排序,可选择降序,而非升序。

签名

export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint;

参数

参数 类型 说明
字段路径 字符串 |FieldPath 要排序的字段。
方向串 OrderByDirection 排序的可选方向(“asc”或“desc”)。如果未指定,则会按升序排列。

返回

QueryOrderByConstraint

已创建的 QueryOrderByConstraint

where(fieldPath, opStr, value)

创建一个 QueryFieldFilterConstraint,用于强制文档必须包含指定字段,并且值应该满足所提供的关系限制条件。

签名

export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint;

参数

参数 类型 说明
字段路径 字符串 |FieldPath 要比较的路径
操作串 whereFilterOp 操作字符串(例如“&lt;"”、“&lt;=”、“==”、“&lt;"”、“&lt;=”、“!=”)。
未知 要比较的值

返回

QueryFieldFilterConstraint

创建的 QueryFieldFilterConstraint

function(fieldValues, ...)

endAt(fieldValues)

创建一个 QueryEndAtConstraint,将结果集修改为相对于查询顺序在提供的字段结束。字段值的顺序必须与查询的“排序依据”子句的顺序一致。

签名

export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;

参数

参数 类型 说明
字段值 未知 [] 此查询的结束字段值(按照查询的排序依据)。

返回

QueryEndAtConstraint

要传递给 query()QueryEndAtConstraint

endBefore(fieldValues)

创建一个 QueryEndAtConstraint,它将结果集修改为相对于查询顺序在提供的字段之前结束。字段值的顺序必须与查询的“排序依据”子句的顺序一致。

签名

export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;

参数

参数 类型 说明
字段值 未知 [] 要在其前结束此查询的字段值(按照查询的排序依据)。

返回

QueryEndAtConstraint

要传递给 query()QueryEndAtConstraint

startAfter(fieldValues)

创建 QueryStartAtConstraint,根据查询的顺序将结果集修改为在提供的字段之后开始。字段值的顺序必须与查询的“排序依据”子句的顺序一致。

签名

export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint;

参数

参数 类型 说明
字段值 未知 [] 要在其后启动此查询的字段值(按照查询的排序依据)。

返回

QueryStartAtConstraint

要传递给 query()QueryStartAtConstraint

startAt(fieldValues)

创建 QueryStartAtConstraint,将结果集修改为相对于查询顺序从提供的字段开始。字段值的顺序必须与查询的“排序依据”子句的顺序一致。

签名

export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;

参数

参数 类型 说明
字段值 未知 [] 此查询的起始字段值(按照查询的排序依据)。

返回

QueryStartAtConstraint

要传递给 query()QueryStartAtConstraint

function(indexManager, ...)

deleteAllPersistentCacheIndexes(indexManager)

移除所有永久性缓存索引。

请注意,此函数还将删除由已废弃的 setIndexConfiguration() 生成的索引。

签名

export declare function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void;

参数

参数 类型 说明
indexManager PersistentCacheIndexManager

返回

void

disablePersistentCacheIndexAutoCreation(indexManager)

停止为本地查询执行自动创建永久性缓存索引。通过调用 enablePersistentCacheIndexAutoCreation() 创建的索引仍然有效。

签名

export declare function disablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;

参数

参数 类型 说明
indexManager PersistentCacheIndexManager

返回

void

enablePersistentCacheIndexAutoCreation(indexManager)

当 SDK 认为缓存索引有助于提高性能时,使 SDK 能够自动为本地查询执行创建永久性缓存索引。

默认情况下,此功能处于停用状态。

签名

export declare function enablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;

参数

参数 类型 说明
indexManager PersistentCacheIndexManager

返回

void

函数(左,...)

totalFieldEqual(左,右)

比较两个“AggregateField”实例是否相等。

签名

export declare function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;

参数

参数 类型 说明
剩余 汇总字段<未知> 将此 AggregateField 与 right 进行比较。
汇总字段<未知> 将此 AggregateField 与 left 进行比较。

返回

布尔值

totalQuerySnapshotEqual(左,右)

比较两个 AggregateQuerySnapshot 实例是否相等。

两个 AggregateQuerySnapshot 实例被视为“相等”如果它们具有可比较相同且相同数据的基础查询。

签名

export declare function aggregateQuerySnapshotEqual<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(left: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>, right: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>): boolean;

参数

参数 类型 说明
剩余 AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType> 要比较的前 AggregateQuerySnapshot 个。
AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType> 第二个要比较的 AggregateQuerySnapshot

返回

布尔值

如果对象为“等于”(如上文所定义),则为 true,否则为 false

queryEqual(左,右)

如果提供的查询指向同一集合并应用相同的约束条件,则返回 true。

签名

export declare function queryEqual<AppModelType, DbModelType extends DocumentData>(left: Query<AppModelType, DbModelType>, right: Query<AppModelType, DbModelType>): boolean;

参数

参数 类型 说明
剩余 查询<AppModelType, DbModelType> 要比较的 Query
查询<AppModelType, DbModelType> 要比较的 Query

返回

布尔值

如果引用指向同一 Firestore 数据库中的同一位置,则返回 true。

refEqual(左,右)

如果提供的引用相等,则返回 true。

签名

export declare function refEqual<AppModelType, DbModelType extends DocumentData>(left: DocumentReference<AppModelType, DbModelType> | CollectionReference<AppModelType, DbModelType>, right: DocumentReference<AppModelType, DbModelType> | CollectionReference<AppModelType, DbModelType>): boolean;

参数

参数 类型 说明
剩余 DocumentReference<AppModelType, DbModelType>|CollectionReference<AppModelType, DbModelType> 要比较的引用。
DocumentReference<AppModelType, DbModelType>|CollectionReference<AppModelType, DbModelType> 要比较的引用。

返回

布尔值

如果引用指向同一 Firestore 数据库中的同一位置,则返回 true。

snapshotEqual(左,右)

如果提供的快照相等,则返回 true。

签名

export declare function snapshotEqual<AppModelType, DbModelType extends DocumentData>(left: DocumentSnapshot<AppModelType, DbModelType> | QuerySnapshot<AppModelType, DbModelType>, right: DocumentSnapshot<AppModelType, DbModelType> | QuerySnapshot<AppModelType, DbModelType>): boolean;

参数

参数 类型 说明
剩余 DocumentSnapshot<AppModelType、DbModelType>|QuerySnapshot<AppModelType, DbModelType> 要比较的快照。
DocumentSnapshot<AppModelType、DbModelType>|QuerySnapshot<AppModelType, DbModelType> 要比较的快照。

返回

布尔值

如果快照相等,则返回 true。

function(limit, ...)

limit(limit)

创建一个仅返回第一个匹配文档的 QueryLimitConstraint

签名

export declare function limit(limit: number): QueryLimitConstraint;

参数

参数 类型 说明
限制 数字 需要返回的最大项数。

返回

QueryLimitConstraint

已创建的 QueryLimitConstraint

limitToLast(限制)

创建一个仅返回最后匹配的文档的 QueryLimitConstraint

您必须为 limitToLast 查询指定至少一个 orderBy 子句,否则在执行期间会抛出异常。

签名

export declare function limitToLast(limit: number): QueryLimitConstraint;

参数

参数 类型 说明
限制 数字 需要返回的最大项数。

返回

QueryLimitConstraint

已创建的 QueryLimitConstraint

function(logLevel, ...)

setLogLevel(logLevel)

设置 Cloud Firestore 日志的详细程度(调试、错误或静默)。

签名

export declare function setLogLevel(logLevel: LogLevel): void;

参数

参数 类型 说明
logLevel LogLevel 您为活动和错误日志记录设置的详细程度。可以是以下任意值:
  • debug 表示最详细的日志记录级别,主要用于调试。
  • error 以仅记录错误。
  • silent to turn off logging.

返回

void

function(n, ...)

增量

返回一个可与 setDoc()updateDoc() 一起使用的特殊值,该值会指示服务器以给定值递增字段的当前值。

如果操作数或当前字段值使用浮点精度,则所有算术都遵循 IEEE 754 语义。如果这两个值都是整数,则超出 JavaScript 安全数字范围(Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER)的值也会有精度损失。此外,一旦 Firestore 后端处理了所有整数操作,其上限就介于 -2^63 到 2^63-1 之间。

如果当前字段值不是 number 类型,或者该字段尚不存在,该转换会将该字段设置为指定值。

签名

export declare function increment(n: number): FieldValue;

参数

参数 类型 说明
n 数字 要递增的数值。

返回

FieldValue

在调用 setDoc()updateDoc() 时使用的 FieldValue 标记

function(query, ...)

getAggregateFromServer(query, aggregateSpec)

计算给定查询的结果集中的文档的指定聚合,而不实际下载文档。

使用此函数执行聚合非常高效,因为只有最终聚合值,而不是文档的数据。如果结果集非常大,无法全部下载(数千个文档),则此函数可以对文档进行聚合。

从服务器收到的结果将保持不变,不考虑任何本地状态。也就是说,系统不会考虑本地缓存中的文档,也不会考虑尚未与服务器同步的本地修改。系统不会使用之前下载的结果(如果有)。每次调用此函数时都必须往返于服务器。

签名

export declare function getAggregateFromServer<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, aggregateSpec: AggregateSpecType): Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 对其结果集进行汇总的查询。
汇总规范 汇总规范类型 AggregateSpec 对象,用于指定要对结果集执行的聚合。AggregateSpec 会为每个汇总指定别名,这些别名可用于检索汇总结果。

返回

Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>

示例

const aggregateSnapshot = await getAggregateFromServer(query, {
  countOfDocs: count(),
  totalHours: sum('hours'),
  averageScore: average('score')
});

const countOfDocs: number = aggregateSnapshot.data().countOfDocs;
const totalHours: number = aggregateSnapshot.data().totalHours;
const averageScore: number | null = aggregateSnapshot.data().averageScore;

getCountFromServer(查询)

计算给定查询的结果集中的文档数量,而不实际下载文档。

使用此函数计算文档数量的效率更高,因为只有最终计数,而不计算文档的数据。在结果集太大而无法全部下载(数千个文档)的情况下,此函数可以对文档进行计数。

从服务器收到的结果将保持不变,不考虑任何本地状态。也就是说,系统不会考虑本地缓存中的文档,也不会考虑尚未与服务器同步的本地修改。系统不会使用之前下载的结果(如果有)。每次调用此函数时都必须往返于服务器。

签名

export declare function getCountFromServer<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<AggregateQuerySnapshot<{
    count: AggregateField<number>;
}, AppModelType, DbModelType>>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 计算其结果集大小的查询。

返回

Promise<AggregateQuerySnapshot<{ count: AggregateField<number>;}、AppModelType、DbModelType>>

将通过计数解析的 Promise;计数可以从 snapshot.data().count 中检索到,其中 snapshot 是返回的 Promise 解析的 AggregateQuerySnapshot

getDocs(查询)

执行查询并以 QuerySnapshot 形式返回结果。

签名

export declare function getDocs<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType>

返回

Promise<QuerySnapshot<AppModelType, DbModelType>>

将使用查询结果进行解析的 Promise

getDocsFromCache(查询)

执行查询并返回缓存中的 QuerySnapshot 结果。如果当前没有缓存与查询匹配的文档,则返回空的结果集。

签名

export declare function getDocsFromCache<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType>

返回

Promise<QuerySnapshot<AppModelType, DbModelType>>

将使用查询结果进行解析的 Promise

getDocsFromServer(查询)

执行查询并将结果作为 QuerySnapshot 从服务器返回。如果网络不可用,则返回错误。

签名

export declare function getDocsFromServer<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType>

返回

Promise<QuerySnapshot<AppModelType, DbModelType>>

将使用查询结果进行解析的 Promise

onSnapshot(查询, 观察者)

附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用在调用 onSnapshot 时返回的函数来取消监听器。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, observer: {
    next?: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要监听的查询。
观察者 {下一个?:(快照:QuerySnapshot<AppModelType, DbModelType>)=>无效;错误?:(错误:FirestoreError)=>无效;完成?:() =>无效;} 包含 nexterror 回调的单个对象。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(查询, 选项, 观察者)

附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用在调用 onSnapshot 时返回的函数来取消监听器。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, options: SnapshotListenOptions, observer: {
    next?: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要监听的查询。
选项 SnapshotListenOptions 用于控制监听行为的选项。
观察者 {下一个?:(快照:QuerySnapshot<AppModelType, DbModelType>)=>无效;错误?:(错误:FirestoreError)=>无效;完成?:() =>无效;} 包含 nexterror 回调的单个对象。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(query, onNext, onError, on 完美)

附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用在调用 onSnapshot 时返回的函数来取消监听器。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, onNext: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要监听的查询。
onNext (快照:QuerySnapshot<AppModelType, DbModelType>)=>无效 每次有新的 QuerySnapshot 可用时要调用的回调。
onError (错误:FirestoreError)=>无效 监听失败或被取消时调用的回调。不会再发生回调。
onComplete () =>无效 可提供,但不会调用,因为数据流永不结束。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(query, options, onNext, onError, on 完美)

附加 QuerySnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。您可以通过调用在调用 onSnapshot 时返回的函数来取消监听器。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要监听的查询。
选项 SnapshotListenOptions 用于控制监听行为的选项。
onNext (快照:QuerySnapshot<AppModelType, DbModelType>)=>无效 每次有新的 QuerySnapshot 可用时要调用的回调。
onError (错误:FirestoreError)=>无效 监听失败或被取消时调用的回调。不会再发生回调。
onComplete () =>无效 可提供,但不会调用,因为数据流永不结束。

返回

退订

可调用以取消快照监听器的退订函数。

query(query, compositeFilter, queryConstraints)

创建新的 Query 不可变实例,该实例可通过扩展还包含其他查询限制条件。

签名

export declare function query<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, compositeFilter: QueryCompositeFilterConstraint, ...queryConstraints: QueryNonFilterConstraint[]): Query<AppModelType, DbModelType>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要用作新约束基础的 Query 实例。
compositeFilter QueryCompositeFilterConstraint 要应用的 QueryCompositeFilterConstraint。使用 and()or() 创建 QueryCompositeFilterConstraint
queryConstraints QueryNonFilterConstraint[] 要应用的其他 QueryNonFilterConstraint(例如 orderBy()limit())。

返回

查询<AppModelType, DbModelType>

异常

如果提供的查询限制条件无法与现有或新的限制条件组合使用,则会发生该错误。

query(query, queryConstraints)

创建新的 Query 不可变实例,该实例可通过扩展还包含其他查询限制条件。

签名

export declare function query<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, ...queryConstraints: QueryConstraint[]): Query<AppModelType, DbModelType>;

参数

参数 类型 说明
查询 查询<AppModelType, DbModelType> 要用作新约束基础的 Query 实例。
queryConstraints QueryConstraint[] 要应用的 QueryConstraint 列表。

返回

查询<AppModelType, DbModelType>

异常

如果提供的查询限制条件无法与现有或新的限制条件组合使用,则会发生该错误。

function(queryConstraints, ...)

and(queryConstraints)

创建一个新的 QueryCompositeFilterConstraint,它是给定过滤条件约束条件的组合。如果一个文档满足所有指定过滤条件,则关联过滤条件会包含该文档。

签名

export declare function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;

参数

参数 类型 说明
queryConstraints QueryFilterConstraint[] 可选。要执行合并的 QueryFilterConstraint 列表。这些容器必须通过调用 where()or()and() 来创建。

返回

QueryCompositeFilterConstraint

新创建的 QueryCompositeFilterConstraint

or(queryConstraints)

创建一个新的 QueryCompositeFilterConstraint,它是给定过滤条件约束的析取。析取运算包含符合任何给定过滤条件的文档。

签名

export declare function or(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;

参数

参数 类型 说明
queryConstraints QueryFilterConstraint[] 可选。要执行析取的 QueryFilterConstraint 列表。这些容器必须通过调用 where()or()and() 来创建。

返回

QueryCompositeFilterConstraint

新创建的 QueryCompositeFilterConstraint

function(reference, ...)

addDoc(reference, data)

使用给定数据向指定的 CollectionReference 添加新文档,并自动为其分配文档 ID。

签名

export declare function addDoc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<DocumentReference<AppModelType, DbModelType>>;

参数

参数 类型 说明
参考 CollectionReference<AppModelType, DbModelType> 对此文档要添加到的集合的引用。
数据 WithFieldValue<AppModelType> 包含新文档数据的对象。

返回

Promise<DocumentReference<AppModelType, DbModelType>>

Promise 写入后端后,使用指向新创建的文档的 DocumentReference 进行解析(请注意,离线时无法解析文档)。

collection(reference, path, pathSegments)

获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。

签名

export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

参数

参数 类型 说明
参考 CollectionReference<AppModelType, DbModelType> 对集合的引用。
路径 字符串 以斜杠分隔的集合路径。
路径细分 字符串[] 要应用的其他路径细分(相对于第一个参数)。

返回

CollectionReference<DocumentDataDocumentData>

CollectionReference 实例。

异常

最终路径中路段数量为偶数,且未指向集合。

collection(reference, path, pathSegments)

获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。

签名

export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对 Firestore 文档的引用。
路径 字符串 以斜杠分隔的集合路径。
路径细分 字符串[] 将相对于第一个参数应用的其他路径细分。

返回

CollectionReference<DocumentDataDocumentData>

CollectionReference 实例。

异常

最终路径中路段数量为偶数,且未指向集合。

deleteDoc(引用)

删除指定的 DocumentReference 引用的文档。

签名

export declare function deleteDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<void>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要删除的文档的引用。

返回

承诺<void>

从后端成功删除文档后,Promise 解析(请注意,离线时无法解析 Promise)。

doc(reference, path, pathSegments)

获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。如果未指定路径,将为返回的 DocumentReference 使用自动生成的唯一 ID。

签名

export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path?: string, ...pathSegments: string[]): DocumentReference<AppModelType, DbModelType>;

参数

参数 类型 说明
参考 CollectionReference<AppModelType, DbModelType> 对集合的引用。
路径 字符串 以斜杠分隔的文档路径。必须省略该值才能使用自动生成的 ID。
路径细分 字符串[] 将相对于第一个参数应用的其他路径细分。

返回

DocumentReference<AppModelType, DbModelType>

DocumentReference 实例。

异常

最终路径的段数为奇数,且未指向文档。

doc(reference, path, pathSegments)

获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。

签名

export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对 Firestore 文档的引用。
路径 字符串 以斜杠分隔的文档路径。
路径细分 字符串[] 将相对于第一个参数应用的其他路径细分。

返回

DocumentReference<DocumentDataDocumentData>

DocumentReference 实例。

异常

最终路径的段数为奇数,且未指向文档。

getDoc(引用)

读取此 DocumentReference 引用的文档。

签名

export declare function getDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 要获取的文档的引用。

返回

Promise<文档快照<AppModelType, DbModelType>>

使用包含当前文档内容的 DocumentSnapshot 解析的 Promise。

getDocFromCache(引用)

从缓存中读取此 DocumentReference 引用的文档。如果文档当前未缓存,则返回错误。

签名

export declare function getDocFromCache<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType>

返回

Promise<文档快照<AppModelType, DbModelType>>

使用包含当前文档内容的 DocumentSnapshot 解析的 Promise

getDocFromServer(参考)

从服务器读取此 DocumentReference 引用的文档。如果网络不可用,则返回错误。

签名

export declare function getDocFromServer<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType>

返回

Promise<文档快照<AppModelType, DbModelType>>

使用包含当前文档内容的 DocumentSnapshot 解析的 Promise

onSnapshot(引用, 观察者)

附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, observer: {
    next?: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要监听的文档的引用。
观察者 {下一个?:(快照:DocumentSnapshot<AppModelType, DbModelType>)=>无效;错误?:(错误:FirestoreError)=>无效;完成?:() =>无效;} 包含 nexterror 回调的单个对象。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(引用, 选项, 观察者)

附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, options: SnapshotListenOptions, observer: {
    next?: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要监听的文档的引用。
选项 SnapshotListenOptions 用于控制监听行为的选项。
观察者 {下一个?:(快照:DocumentSnapshot<AppModelType, DbModelType>)=>无效;错误?:(错误:FirestoreError)=>无效;完成?:() =>无效;} 包含 nexterror 回调的单个对象。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(reference, onNext, onError, onCompleted)

附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, onNext: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要监听的文档的引用。
onNext (快照:DocumentSnapshot<AppModelType, DbModelType>)=>无效 每次有新的 DocumentSnapshot 可用时要调用的回调。
onError (错误:FirestoreError)=>无效 监听失败或被取消时调用的回调。不会再发生回调。
onComplete () =>无效 可提供,但不会调用,因为数据流永不结束。

返回

退订

可调用以取消快照监听器的退订函数。

onSnapshot(reference, options, onNext, onError, onCompleted)

附加 DocumentSnapshot 事件的监听器。您可以传递单独的 onNextonError 回调,也可以传递带有 nexterror 回调的单个观察器对象。

注意:虽然可以提供 onCompletion 回调,但由于快照流将永无止境,因此永远不会调用它。

签名

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要监听的文档的引用。
选项 SnapshotListenOptions 用于控制监听行为的选项。
onNext (快照:DocumentSnapshot<AppModelType, DbModelType>)=>无效 每次有新的 DocumentSnapshot 可用时要调用的回调。
onError (错误:FirestoreError)=>无效 监听失败或被取消时调用的回调。不会再发生回调。
onComplete () =>无效 可提供,但不会调用,因为数据流永不结束。

返回

退订

可调用以取消快照监听器的退订函数。

setDoc(reference, data)

对此 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在,系统将会创建该文档。

签名

export declare function setDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<void>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要写入的文档的引用。
数据 WithFieldValue<AppModelType> 文档的字段和值的映射。

返回

承诺<void>

数据成功写入后端后,系统会解析 Promise(请注意,离线时无法解析此数据)。

setDoc(reference, data, options)

对指定的 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在,系统将会创建该文档。如果您提供 mergemergeFields,则所提供的数据可以合并到现有文档中。

签名

export declare function setDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: PartialWithFieldValue<AppModelType>, options: SetOptions): Promise<void>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要写入的文档的引用。
数据 PartialWithFieldValue<AppModelType> 文档的字段和值的映射。
选项 SetOptions 用于配置 set 行为的对象。

返回

承诺<void>

数据成功写入后端后,Promise 便会解析(请注意,处于离线状态时无法解析 Promise)。

updateDoc(reference, data)

更新由指定的 DocumentReference 引用的文档中的字段。如果应用于不存在的文档,更新将失败。

签名

export declare function updateDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: UpdateData<DbModelType>): Promise<void>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要更新的文档的引用。
数据 UpdateData<DbModelType> 一个对象,包含更新文档时使用的字段和值。字段可以包含点,以引用文档中的嵌套字段。

返回

承诺<void>

数据成功写入后端后,系统会解析 Promise(请注意,离线时无法解析此数据)。

updateDoc(reference, field, value, moreFieldsAndValues)

更新指定 DocumentReference 引用的文档中的字段。如果应用于不存在的文档,更新将失败。

您可以通过提供以英文句点分隔的字段路径字符串或提供 FieldPath 对象来更新嵌套字段。

签名

export declare function updateDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;

参数

参数 类型 说明
参考 DocumentReference<AppModelType, DbModelType> 对要更新的文档的引用。
字段 字符串 |FieldPath 要更新的第一个字段。
未知 第一个值。
更多字段和值 未知 [] 其他键值对。

返回

承诺<void>

数据成功写入后端后,系统会解析 Promise(请注意,离线时无法解析此数据)。

function(settings, ...)

memoryLocalCache(设置)

创建 MemoryLocalCache 的实例。该实例可设置为 FirestoreSettings.cache,以告知 SDK 应使用哪个缓存层。

签名

export declare function memoryLocalCache(settings?: MemoryCacheSettings): MemoryLocalCache;

参数

参数 类型 说明
设置 MemoryCacheSettings

返回

MemoryLocalCache

memoryLruGarbageCollector(设置)

创建 MemoryLruGarbageCollector 的实例。

您可以在设置参数中指定目标尺寸。一旦缓存大小超过给定大小,收集器就会开始删除文档。默认缓存大小为 40MB(40 * 1024 * 1024 字节)。

签名

export declare function memoryLruGarbageCollector(settings?: {
    cacheSizeBytes?: number;
}): MemoryLruGarbageCollector;

参数

参数 类型 说明
设置 { cacheSizeBytes?: number;}

返回

MemoryLruGarbageCollector

PersistentLocalCache(设置)

创建 PersistentLocalCache 的实例。该实例可设置为 FirestoreSettings.cache,以告知 SDK 应使用哪个缓存层。

无法在 Node.js 环境中使用永久性缓存。

签名

export declare function persistentLocalCache(settings?: PersistentCacheSettings): PersistentLocalCache;

参数

参数 类型 说明
设置 PersistentCacheSettings

返回

PersistentLocalCache

PersistentSingleTabManager(设置)

创建 PersistentSingleTabManager 的实例。

签名

export declare function persistentSingleTabManager(settings: PersistentSingleTabManagerSettings | undefined): PersistentSingleTabManager;

参数

参数 类型 说明
设置 PersistentSingleTabManagerSettings |未定义 配置已创建的标签页管理器。

返回

PersistentSingleTabManager

function(快照, ...)

endAt(快照)

创建 QueryEndAtConstraint,将结果集修改为以提供的文档(含边界值)结束。结束位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。

签名

export declare function endAt<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;

参数

参数 类型 说明
快照 DocumentSnapshot<AppModelType、DbModelType> 结束位置的文档快照。

返回

QueryEndAtConstraint

要传递给 query()QueryEndAtConstraint

endBefore(快照)

创建一个 QueryEndAtConstraint,将结果集修改为在提供的文档之前结束(不含边界值)。结束位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。

签名

export declare function endBefore<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;

参数

参数 类型 说明
快照 DocumentSnapshot<AppModelType、DbModelType> 结束位置之前的文档快照。

返回

QueryEndAtConstraint

要传递给 query()QueryEndAtConstraint

startAfter(快照)

创建 QueryStartAtConstraint,将结果集修改为在提供的文档之后开始(不包含结果)。起始位置是相对于查询顺序而言的。该文档必须包含查询的 orderBy 中提供的所有字段。

签名

export declare function startAfter<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryStartAtConstraint;

参数

参数 类型 说明
快照 DocumentSnapshot<AppModelType、DbModelType> 在其后开始播放的文档的快照。

返回

QueryStartAtConstraint

要传递给 query()QueryStartAtConstraint

startAt(快照)

创建 QueryStartAtConstraint,将结果集修改为从提供的文档(含)开始。起始位置是相对于查询顺序而言的。该文档必须包含此查询的 orderBy 中提供的所有字段。

签名

export declare function startAt<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryStartAtConstraint;

参数

参数 类型 说明
快照 DocumentSnapshot<AppModelType、DbModelType> 起始文档的快照。

返回

QueryStartAtConstraint

要传递给 query()QueryStartAtConstraint

function(values, ...)

向量(值)

创建使用给定数字数组的副本构造的新 VectorValue

签名

export declare function vector(values?: number[]): VectorValue;

参数

参数 类型 说明
数值 [] 使用此数字数组的副本创建 VectorValue 实例。

返回

VectorValue

使用给定数字数组的副本构造的新 VectorValue

CACHE_SIZE_UNLIMITED

一个常量,用于指示应停用 LRU 垃圾回收。在传递给 Firestore 实例的设置中,将此值设置为 cacheSizeBytes

签名

CACHE_SIZE_UNLIMITED = -1

AddPrefixToKeys

返回一个新的映射,其中每个键的前缀都是附加到一个点的外部键。

签名

export declare type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
    [K in keyof T & string as `${Prefix}.${K}`]+?: string extends K ? any : T[K];
};

汇总字段类型

Firestore 支持的所有 AggregateField 类型的并集。

签名

export declare type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;

汇总规范数据

一个类型,其键取自 AggregateSpec,其值是输入 AggregateSpec 中的相应 AggregateField 执行聚合的结果。

签名

export declare type AggregateSpecData<T extends AggregateSpec> = {
    [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
};

汇总类型

表示要执行的聚合类型的联合类型。

签名

export declare type AggregateType = 'count' | 'avg' | 'sum';

ChildUpdateField

用于计算给定类型 T1 的嵌套字段的帮助程序。需要这样做才能分配并集类型,例如 undefined | {...}(发生在可选属性中)或 {a: A} | {b: B}

在此用例中,V 用于在 Record 上分布 T[K] 的并集类型,因为 T[K] 是作为表达式进行求值,而不是分布。

请参阅 https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types

签名

export declare type ChildUpdateFields<K extends string, V> = V extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<V>> : never;

DocumentChangeType

DocumentChange 的类型可能是“已添加”、“已移除”或“修改”。

签名

export declare type DocumentChangeType = 'added' | 'removed' | 'modified';

FirestoreErrorCode

Firestore 状态代码集。这些代码与 gRPC 在此处公开的代码相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md

可能的值:-“cancelled”:操作已取消(通常是被调用方取消)。-“未知”:未知错误或来自其他错误域的错误。- 'invalid- arguments':客户端指定的参数无效。请注意,这与“failed-precondition”不同。“无效参数”表示无论系统状态如何,都会有问题的参数(例如无效的字段名称)。- 'deadline-exceeded':截止期限已过,操作还未完成。对于更改系统状态的操作,即使操作已成功完成,也可能会返回此错误。例如,服务器的成功响应延迟时间过长,截止期限已过。-“not-found”:未找到所请求的某些文档。- “ already-exists”:我们尝试创建的某个文档已存在。-“permission-denied”:调用方没有执行指定操作的权限。-“resource-exhausted”:部分资源已用尽,可能是每个用户的配额不足,也可能是因为整个文件系统空间不足。- 'failed-precondition':操作被拒绝,因为系统未处于执行操作所需的状态。- “aborted”:操作被取消,通常是由于事务中止等并发问题。-“超出范围”:尝试操作超出了有效范围。-“未实现”:操作未实现或不受支持/启用。-“internal”:内部错误。这意味着底层系统所期望的一些不变量已损坏。如果您看到上述某个错误,则表明某些地方已损坏。-“unavailable”:服务当前不可用。这很可能是一种暂时情况,可以通过退避重试来纠正。-“data-loss”:不可恢复的数据丢失或损坏。-“unauthenticated”:请求未包含相应操作的有效身份验证凭据。

签名

export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';

FirestoreLocalCache

所有受支持的 SDK 缓存层中的联合类型。

签名

export declare type FirestoreLocalCache = MemoryLocalCache | PersistentLocalCache;

ListenSource

描述查询监听的来源。

设置为 default 可监听缓存和服务器更改。设置为 cache 可仅监听缓存中的更改。

签名

export declare type ListenSource = 'default' | 'cache';

内存垃圾回收器

针对内存本地缓存的所有支持垃圾回收器中的联合类型。

签名

export declare type MemoryGarbageCollector = MemoryEagerGarbageCollector | MemoryLruGarbageCollector;

NestedUpdateField

对于每个字段(例如“bar”),找出所有嵌套的键(例如 {'bar.baz': T1, 'bar.qux': T2})。将它们相交形成一个映射,其中包含所有可能的键(这些键均标记为可选)

签名

export declare type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
    [K in keyof T & string]: ChildUpdateFields<K, T[K]>;
}[keyof T & string]>;

OrderByDirection

orderBy() 子句的方向指定为“desc”或“asc”(降序或升序)。

签名

export declare type OrderByDirection = 'desc' | 'asc';

PartialWithFieldValue

与 TypeScript 的 Partial<T> 类似,但允许省略嵌套字段,并允许传入 FieldValues 作为属性值。

签名

export declare type PartialWithFieldValue<T> = Partial<T> | (T extends Primitive ? T : T extends {} ? {
    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
} : never);

PersistentTabManager

所有可用标签页管理器的并集。

签名

export declare type PersistentTabManager = PersistentSingleTabManager | PersistentMultipleTabManager;

原初

基元类型。

签名

export declare type Primitive = string | number | boolean | undefined | null;

QueryConstraintType

介绍此 SDK 中提供的不同查询限制。

签名

export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore';

QueryFilterConstraint

QueryFilterConstraint 是一种辅助联合类型,表示 QueryFieldFilterConstraintQueryCompositeFilterConstraint

签名

export declare type QueryFilterConstraint = QueryFieldFilterConstraint | QueryCompositeFilterConstraint;

QueryNonFilterConstraint

QueryNonFilterConstraint 是一种辅助联合类型,表示 QueryConstraint,用于缩小文档集或对文档集进行排序,但不会明确过滤文档字段。QueryNonFilterConstraint 是通过调用 orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast() 来创建的,然后可以传递给同样包含新查询的 query() 实例。QueryConstraint

签名

export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint;

SetOptions

一个选项对象,用于配置 setDoc() 的行为和调用。通过向 merge: true 提供 SetOptions,您可以将这些调用配置为执行精细合并,而不是将目标文档全部覆盖。

签名

export declare type SetOptions = {
    readonly merge?: boolean;
} | {
    readonly mergeFields?: Array<string | FieldPath>;
};

任务状态

表示软件包加载任务的状态。

两者均为“错误”和“Success”(成功)正在接收器状态:任务将中止或完成,并且在更新报告后,将不再有更新。

签名

export declare type TaskState = 'Error' | 'Running' | 'Success';

UnionToIntersection

如果给定联合类型 U = T1 | T2 | ...,则返回相交类型 (T1 & T2 & ...)

使用分配性条件类型和根据条件类型进行推断。这之所以有效,是因为同一类型变量在反向变体位置有多个候选对象会导致推断交集类型。https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type

签名

export declare type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;

更新数据

更新由映射到值的字段路径(例如“foo”或“foo.baz”)构成的数据(与 updateDoc() 搭配使用)。包含点的字段会引用文档中的嵌套字段。FieldValues 可以作为属性值传入。

签名

export declare type UpdateData<T> = T extends Primitive ? T : T extends {} ? {
    [K in keyof T]?: UpdateData<T[K]> | FieldValue;
} & NestedUpdateFields<T> : Partial<T>;

whereFilterOp

where() 子句中的过滤条件是使用字符串“&lt;”“<

签名

export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';

WithFieldValue

允许在保持类型安全的同时将 FieldValues 作为属性值传入。

签名

export declare type WithFieldValue<T> = T | (T extends Primitive ? T : T extends {} ? {
    [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
} : never);