@firebase/firestore/lite

函数

函数	说明
function(应用, ...)
getFirestore(应用)	返回与提供的 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例，则使用默认设置初始化新实例。
getFirestore(app, databaseId)	（Beta 版）返回与所提供的 FirebaseApp 关联的现有 Firestore 实例。如果不存在实例，则使用默认设置初始化新实例。
initializeFirestore(应用, 设置)	使用提供的设置初始化 Cloud Firestore 的新实例。只能在任何其他函数（包括 getFirestore()）之前调用。如果自定义设置为空，则此函数等同于调用 getFirestore()。
initializeFirestore(app, settings, databaseId)	（Beta 版）使用提供的设置初始化 Cloud Firestore 的新实例。只能在任何其他函数（包括 getFirestore()）之前调用。如果自定义设置为空，则此函数等同于调用 getFirestore()。
function(firestore, ...)
collection(firestore, path, pathSegments)	获取引用指定绝对路径下的集合的 CollectionReference 实例。
collectionGroup(firestore, collectionId)	创建并返回一个新的 Query 实例，该实例中包含数据库中具有给定 collectionId 的集合或子集合中包含的所有文档。
connectFirestoreEmulator(firestore, host, port, options)	请修改此实例以与 Cloud Firestore 模拟器进行通信。注意：在使用此实例执行任何操作之前，必须调用此方法。
doc(firestore, path, pathSegments)	获取引用指定绝对路径中文档的 DocumentReference 实例。
runTransaction(firestore, updateFunction, options)	执行指定的 updateFunction，然后尝试提交在事务中应用的更改。如果事务中读取的任何文档已发生更改，Cloud Firestore 会重试 updateFunction。如果 5 次尝试后仍未提交，则事务将失败。单个事务中允许的最大写入次数为 500。
terminate(firestore)	终止所提供的 Firestore 实例。调用 terminate() 后，只能使用 clearIndexedDbPersistence() 函数。任何其他函数都会抛出 FirestoreError。终止操作不会取消任何待处理的写入，并且任何等待服务器响应的 promise 都不会解析。要在终止后重启，请使用 getFirestore() 创建一个新的 Firestore 实例。注意：正常情况下，不需要调用 terminate()。此函数仅在您希望强制此实例释放其所有资源或与 clearIndexedDbPersistence() 结合使用以确保在两次测试运行之间销毁所有本地状态时有用。
writeBatch(firestore)	创建写入批次，用于以单个原子操作的形式执行多次写入。单个 WriteBatch 中允许的最大写入次数为 500。这些写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
函数
count()	创建一个 AggregateField 对象，用于计算查询结果集中的文档数。
deleteField()	返回一个可与 updateDoc() 或 setDoc() 结合使用的标记，同时使用 {merge: true} 标记要删除的字段。
documentId()	返回特殊标记 FieldPath 来引用文档的 ID。它可用于查询，以按文档 ID 进行排序或过滤。
getFirestore()	返回与默认 FirebaseApp 关联的现有默认 Firestore 实例。如果不存在实例，则使用默认设置初始化新实例。
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，将结果集修改为相对于查询顺序从提供的字段开始。字段值的顺序必须与查询的“排序依据”子句的顺序一致。
函数（左，...）
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_INTEGER 到 Number.MAX_SAFE_INTEGER）的值也会有精度损失。此外，一旦 Firestore 后端进行处理，所有整数操作的上限将介于 -2^63 到 2^63-1 之间。如果当前字段值不是 number 类型，或者该字段尚不存在，转换会将该字段设置为指定值。
函数(query, ...)
getAggregate(query, aggregateSpec)	计算给定查询结果集中的文档的指定聚合，无需实际下载文档。使用此函数执行聚合非常高效，因为只有最终聚合值，而不是文档的数据。如果结果集非常大，无法全部下载（数千个文档），则此函数可以对文档进行聚合。
getCount(查询)	在不实际下载文档的情况下，计算指定查询的结果集中的文档数量。使用此函数计算文档数量的效率会更高，因为只有最终计数，而不计算文档的数据。在结果集太大而无法全部下载（数千个文档）的情况下，此函数可以对文档进行计数。
getDocs(查询)	执行查询并以 QuerySnapshot 的形式返回结果。所有查询都直接由服务器执行，即使之前已执行过该查询也是如此。仅当后端已应用最近的修改时，这些修改才会反映在检索的结果中。如果客户端处于离线状态，则操作将失败。如需查看之前缓存的结果和本地修改，请使用完整的 Firestore SDK。
query(query, compositeFilter, queryConstraints)	创建新的 Query 不可变实例，该实例可通过扩展还包含其他查询限制条件。
query(query, queryConstraints)	创建新的 Query 不可变实例，该实例可通过扩展还包含其他查询限制条件。
function(queryConstraints, ...)
and(queryConstraints)	创建一个新的 QueryCompositeFilterConstraint，它是给定过滤条件约束条件的组合。如果一个文档满足所有指定过滤条件，则关联过滤条件会包含该文档。
或(queryConstraints)	创建一个新的 QueryCompositeFilterConstraint，它是给定过滤条件约束的析取。析取运算包含符合任何给定过滤条件的文档。
function(引用, ...)
addDoc(reference, data)	使用给定数据向指定的 CollectionReference 添加新文档，并自动为其分配文档 ID。此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
collection(reference, path, pathSegments)	获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。
collection(reference, path, pathSegments)	获取引用指定相对路径下 reference 子集合的 CollectionReference 实例。
deleteDoc(reference)	删除指定的 DocumentReference 引用的文档。删除操作只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则删除失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
doc(reference, path, pathSegments)	获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。如果未指定路径，将为返回的 DocumentReference 使用自动生成的唯一 ID。
doc(reference, path, pathSegments)	获取引用 reference 中位于指定相对路径的文档的 DocumentReference 实例。
getDoc(reference)	读取指定的文档引用所引用的文档。系统会直接从服务器提取所有文档，即使文档之前已被读取或修改也是如此。仅当最近的修改已由后端应用时，它们才会反映在检索到的 DocumentSnapshot 中。如果客户端处于离线状态，则读取将失败。如果您想使用缓存或查看本地修改，请使用完整的 Firestore SDK。
setDoc(reference, data)	对指定的 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在，系统会创建一个。此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
setDoc(reference, data, options)	对指定的 DocumentReference 引用的文档执行写入操作。如果该文档尚不存在，系统将会创建该文档。如果您提供 merge 或 mergeFields，则所提供的数据可以合并到现有文档中。此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
updateDoc(reference, data)	更新由指定 DocumentReference 引用的文档中的字段。如果应用于不存在的文档，更新将失败。此更新的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
updateDoc(reference, field, value, moreFieldsAndValues)	对指定的 DocumentReference 引用的文档中的字段进行更新。如果应用于不存在的文档，更新将失败。您可以通过提供以英文句点分隔的字段路径字符串或提供 FieldPath 对象来更新嵌套字段。此更新的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。
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] 的范围内。
查询	Query 是指您可以读取或监听的查询。您还可以通过添加过滤条件和排序来构建经过优化的 Query 对象。
QueryCompositeFilterConstraint	QueryCompositeFilterConstraint 用于通过对多个 QueryFieldFilterConstraint 或 QueryCompositeFilterConstraint 执行逻辑 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>) 提取其数据，以获取特定字段。QueryDocumentSnapshot 与 DocumentSnapshot 提供相同的 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 方法枚举这些文档。您可以通过 empty 和 size 属性确定文档数量。
QueryStartAtConstraint	QueryStartAtConstraint 用于从 Firestore 查询返回的结果集的开头排除文档。QueryStartAtConstraint 通过调用 startAt() 或 startAfter() 来创建，然后可以传递给 query() 来创建包含此 QueryStartAtConstraint 的新查询实例。
时间戳	Timestamp 表示与任何时区或日历无关的时间点，以纳秒精度表示（以 UTC 新纪元时间为准），以纳秒为单位表示秒数和小数。它使用前公历进行编码，可将公历向前扩展到第一年。其编码假设每分钟的时长均为 60 秒，即闰秒经过均匀分布处理，因此不需要使用闰秒表进行解释。范围是 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。如需查看示例和其他规范，请参阅时间戳定义。
事务	对事务的引用。传递到事务的 updateFunction 的 Transaction 对象提供了在事务上下文中读取和写入数据的方法。请参阅 runTransaction()。
VectorValue	表示 Firestore 文档中的矢量类型。使用 创建实例。矢量值
WriteBatch	批量写入，用于以单个原子单元的形式执行多次写入。可通过调用 writeBatch() 获取 WriteBatch 对象。它提供了将写入添加到批量写入的方法。在调用 WriteBatch.commit() 之前，所有写入操作都不会提交（或在本地可见）。

接口

接口	说明
AggregateSpec	指定一组聚合及其别名。
文档数据	文档数据（与 setDoc() 一起使用）由映射到值的字段组成。
FirestoreDataConverter	withConverter() 使用的转换器，用于将 AppModelType 类型的用户对象转换为 DbModelType 类型的 Firestore 数据。通过使用该转换器，您可以在从 Firestore 存储和检索对象时指定通用类型参数。在此上下文中，“AppModel”是在应用中使用，用于将相关信息和功能打包在一起的类。例如，此类类可能包含复杂的嵌套数据类型、用于记忆的属性、Firestore 不支持的类型的属性（例如 symbol 和 bigint），以及执行复合操作的辅助函数。此类类不适合和/或无法存储到 Firestore 数据库中。需要将此类类的实例转换为“普通的旧 JavaScript 对象”(POJO) 只具有完全基本的属性，可能嵌套在其他 POJO 或 POJO 数组中。在此上下文中，这种类型称为“DbModel”并且会是一个适合持久保存到 Firestore 的对象。为方便起见，应用可以实现 FirestoreDataConverter 并使用 Firestore 对象（例如 DocumentReference 或 Query）注册转换器，以便在存储到 Firestore 时自动将 AppModel 转换为 DbModel，并在从 Firestore 检索时将 DbModel 转换为 AppModel。
设置	指定 Cloud Firestore 实例的自定义配置。您必须在调用任何其他方法之前设置这些变量。
TransactionOptions	用于自定义交易行为的选项。

类型别名

类型别名	说明
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
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”：请求未包含相应操作的有效身份验证凭据。
NestedUpdateFields	对于每个字段（例如“bar”），找出所有嵌套的键（例如 {'bar.baz': T1, 'bar.qux': T2}）。将它们相交形成一个映射，其中包含所有可能的键（这些键均标记为可选）
OrderByDirection	orderBy() 子句的方向指定为“desc”或“asc”（降序或升序）。
PartialWithFieldValue	与 TypeScript 的 Partial<T> 类似，但允许省略嵌套字段，并允许将 FieldValues 作为属性值传入。
初始	基元类型。
QueryConstraintType	介绍此 SDK 中提供的不同查询限制。
QueryFilterConstraint	QueryFilterConstraint 是一种辅助联合类型，表示 QueryFieldFilterConstraint 和 QueryCompositeFilterConstraint。
QueryNonFilterConstraint	QueryNonFilterConstraint 是一种辅助联合类型，表示 QueryConstraint，用于缩小文档集或对文档集进行排序，但不会明确过滤文档字段。QueryNonFilterConstraint 是通过调用 orderBy()、startAt()、startAfter()、endBefore()、endAt()、limit() 或 limitToLast() 来创建，然后可以传递到 query() 中也包含相应新查询。/}QueryConstraint
SetOptions	一个选项对象，用于配置 setDoc() 的行为和调用。通过提供带有 merge: true 的 SetOptions，可以将这些调用配置为执行精细的合并，而不是将目标文档全部覆盖。
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(应用, 设置)

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

签名：

export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore;

参数

参数	类型	说明
应用	FirebaseApp	将与 Firestore 实例关联的 FirebaseApp。
设置	设置	用于配置 Firestore 实例的设置对象。

返回：

Firestore

新初始化的 Firestore 实例。

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

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

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

签名：

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

参数

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

返回：

Firestore

新初始化的 Firestore 实例。

function(firestore, ...)

collection（firestore、path、pathSegments）

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

签名：

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

参数

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

返回：

CollectionReference<DocumentData、DocumentData>

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

doc（firestore、path、pathSegments）

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

签名：

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

参数

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

返回：

DocumentReference<DocumentData、DocumentData>

DocumentReference 实例。

异常

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

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 以及相应的失败错误。

终止(firestore)

终止提供的 Firestore 实例。

调用 terminate() 后，只能使用 clearIndexedDbPersistence() 函数。任何其他函数都会抛出 FirestoreError。终止操作不会取消任何待处理的写入，并且不会解析任何等待服务器响应的 promise。

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

注意 ：正常情况下，不需要调用 terminate()。此函数仅在您希望强制此实例释放其所有资源或与 clearIndexedDbPersistence() 结合使用以确保在两次测试运行之间销毁所有本地状态时有用。

签名：

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

参数

参数	类型	说明
firestore	Firestore	要终止的 Firestore 实例。

返回：

承诺<void>

实例成功终止后解析的 Promise。

writeBatch(firestore)

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

这些写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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 实例。

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	操作字符串（例如“<"”、“<=”、“==”、“<"”、“<=”、“!=”）。
值	未知	要比较的值

返回：

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。

函数（左，...）

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_INTEGER 到 Number.MAX_SAFE_INTEGER）的值也会有精度损失。此外，一旦 Firestore 后端处理了所有整数操作，其上限就介于 -2^63 到 2^63-1 之间。

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

签名：

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

参数

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

返回：

FieldValue

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

function(query, ...)

getAggregate(query, aggregateSpec)

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

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

签名：

export declare function getAggregate<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 getAggregate(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;

getCount(查询)

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

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

签名：

export declare function getCount<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 的形式返回结果。

所有查询都由服务器直接执行，即使之前执行过查询也是如此。仅当后端已应用最近的修改时，这些修改才会反映在检索的结果中。如果客户端处于离线状态，则操作将失败。如需查看之前缓存的结果和本地修改，请使用完整的 Firestore SDK。

签名：

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

参数

参数	类型	说明
查询	查询<AppModelType, DbModelType>	要执行的 Query。

返回：

Promise<QuerySnapshot<AppModelType, DbModelType>>

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

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。

此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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>>

在将文档写入后端后，使用指向新创建的文档的 DocumentReference 解析 Promise。

异常

错误 - 如果提供的输入不是有效的 Firestore 文档。

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<DocumentData、DocumentData>

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<DocumentData、DocumentData>

CollectionReference 实例。

异常

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

deleteDoc(引用)

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

删除操作只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则删除失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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

参数

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

返回：

承诺<void>

从后端成功删除文档后，系统会解析 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<DocumentData、DocumentData>

DocumentReference 实例。

异常

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

getDoc(引用)

读取指定的文档引用所引用的文档。

系统会直接从服务器提取所有文档，即使文档之前已被读取或修改也是如此。仅当最近的修改已由后端应用时，它们才会反映在检索到的 DocumentSnapshot 中。如果客户端处于离线状态，则读取将失败。如果您想使用缓存或查看本地修改，请使用完整的 Firestore SDK。

签名：

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

参数

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

返回：

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

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

setDoc(reference, data)

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

此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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

参数

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

返回：

承诺<void>

数据成功写入后端后，系统会解析 Promise。

异常

错误 - 如果提供的输入不是有效的 Firestore 文档。

setDoc(reference, data, options)

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

此写入的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则写入将失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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。

异常

错误 - 如果提供的输入不是有效的 Firestore 文档。

updateDoc(reference, data)

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

此更新的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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

参数

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

返回：

承诺<void>

数据成功写入后端后，系统会解析 Promise。

异常

错误 - 如果提供的输入不是有效的 Firestore 数据。

updateDoc(reference, field, value, moreFieldsAndValues)

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

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

此更新的结果只会反映在返回的 promise 解析后发生的文档读取中。如果客户端处于离线状态，则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入，请使用完整的 Firestore SDK。

签名：

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。

异常

错误 - 如果提供的输入不是有效的 Firestore 数据。

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。

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;

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';

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);

原初

基元类型。

签名：

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 是一种辅助联合类型，表示 QueryFieldFilterConstraint 和 QueryCompositeFilterConstraint。

签名：

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>;
};

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);