@firebase/firestore/lite

功能

功能描述
函数(应用程序,...)
获取Firestore(应用程序)返回与提供的FirebaseApp关联的现有默认Firestore实例。如果不存在实例,则使用默认设置初始化新实例。
getFirestore(应用程序,数据库Id) (测试版)返回与提供的FirebaseApp关联的现有Firestore实例。如果不存在实例,则使用默认设置初始化新实例。
初始化Firestore(应用程序,设置)使用提供的设置初始化 Cloud Firestore 的新实例。只能在任何其他函数之前调用,包括getFirestore() 。如果自定义设置为空,该函数相当于调用getFirestore()
初始化Firestore(应用程序,设置,databaseId) (测试版)使用提供的设置初始化 Cloud Firestore 的新实例。只能在任何其他函数之前调用,包括getFirestore() 。如果自定义设置为空,该函数相当于调用getFirestore()
函数(firestore,...)
集合(firestore、路径、pathSegments)获取引用指定绝对路径处的集合CollectionReference实例。
集合组(firestore,集合Id)创建并返回一个新的Query实例,其中包含数据库中具有给定collectionId集合或子集合中包含的所有文档。
connectFirestoreEmulator(firestore、主机、端口、选项)修改此实例以与 Cloud Firestore 模拟器进行通信。注意:必须在使用该实例执行任何操作之前调用此方法。
文档(firestore、路径、pathSegments)获取引用指定绝对路径处的文档的DocumentReference实例。
runTransaction(firestore,updateFunction,选项)执行给定的updateFunction ,然后尝试提交事务中应用的更改。如果事务中读取的任何文档发生更改,Cloud Firestore 会重试updateFunction 。如果5次尝试后仍无法提交,则事务失败。单个事务允许的最大写入次数为 500。
终止(火存储)终止提供的Firestore实例。调用terminate()后,只能使用clearIndexedDbPersistence()函数。任何其他函数都会抛出FirestoreError 。终止不会取消任何挂起的写入,并且任何等待服务器响应的承诺都不会得到解决。要在终止后重新启动,请使用getFirestore()创建Firestore的新实例注意:一般情况下,不需要调用terminate() 。仅当您想要强制此实例释放其所有资源或与clearIndexedDbPersistence()结合使用以确保在测试运行之间销毁所有本地状态时,此函数才有用。
writeBatch(火存储)创建一个写入批处理,用于将多个写入作为单个原子操作执行。单个 WriteBatch 中允许的最大写入次数为 500。这些写入的结果只会反映在返回的 Promise 解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
功能()
数数()创建一个 AggregateField 对象,该对象可用于计算查询结果集中的文档计数。
删除字段()返回一个哨兵,与带有{merge: true}updateDoc()setDoc()一起使用,以标记要删除的字段。
文档ID()返回一个特殊的哨兵FieldPath来引用文档的 ID。它可用于在查询中按文档 ID 排序或过滤。
获取Firestore()返回与默认FirebaseApp关联的现有默认Firestore实例。如果不存在实例,则使用默认设置初始化新实例。
服务器时间戳()返回与setDoc()updateDoc()一起使用的哨兵,以在写入的数据中包含服务器生成的时间戳。
函数(数据库ID,...)
getFirestore(数据库ID) (测试版)返回与默认FirebaseApp关联的现有Firestore实例。如果不存在实例,则使用默认设置初始化新实例。
函数(元素,...)
数组删除(元素)返回一个可以与setDoc()一起使用的特殊值,或者告诉服务器从服务器上已存在的任何数组值中删除给定元素。指定的每个元素的所有实例都将从数组中删除。如果正在修改的字段还不是数组,它将被空数组覆盖。
数组联合(元素)返回一个可以与setDoc()updateDoc()一起使用的特殊值,该值告诉服务器将给定元素与服务器上已存在的任何数组值联合起来。数组中尚不存在的每个指定元素都将添加到末尾。如果正在修改的字段还不是数组,它将被包含确切指定元素的数组覆盖。
函数(字段,...)
平均(场)创建一个 AggregateField 对象,该对象可用于计算查询结果集中一系列文档中指定字段的平均值。
总和(字段)创建一个 AggregateField 对象,该对象可用于计算查询结果集中一系列文档的指定字段的总和。
函数(字段路径,...)
orderBy(fieldPath, 方向Str)创建一个QueryOrderByConstraint ,按指定字段对查询结果进行排序,可以选择按降序而不是升序。注意:不包含指定字段的文档不会出现在查询结果中。
其中(字段路径、opStr、值)创建一个QueryFieldFilterConstraint ,强制文档必须包含指定字段并且该值应满足提供的关系约束。
函数(字段值,...)
结束于(字段值)创建一个QueryEndAtConstraint ,它将结果集修改为相对于查询顺序在提供的字段处结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。
结束之前(字段值)创建一个QueryEndAtConstraint ,将结果集修改为相对于查询顺序在提供的字段之前结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。
开始之后(字段值)创建一个QueryStartAtConstraint ,它将结果集修改为相对于查询顺序在提供的字段之后开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。
开始于(字段值)创建一个QueryStartAtConstraint ,它将结果集修改为从相对于查询顺序提供的字段开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。
函数(左,...)
聚合字段等于(左,右)比较两个“AggregateField” ` 平等的实例。
聚合查询快照等于(左,右)比较两个AggregateQuerySnapshot实例是否相等。如果两个AggregateQuerySnapshot实例具有比较相等且数据相同的基础查询,则它们被视为“相等”。
查询等于(左,右)如果提供的查询指向同一集合并应用相同的约束,则返回 true。
refEqual(左,右)如果提供的引用相等,则返回 true。
快照等于(左,右)如果提供的快照相等,则返回 true。
函数(极限,...)
限制(限制)创建一个仅返回第一个匹配文档的QueryLimitConstraint
限制到最后(限制)创建一个仅返回最后匹配文档的QueryLimitConstraint limitToLast查询必须至少指定一个orderBy子句,否则执行过程中会抛出异常。
函数(日志级别,...)
设置日志级别(日志级别)设置 Cloud Firestore 日志的详细程度(调试、错误或静默)。
函数(n,...)
增量(n)返回一个特殊值,可与setDoc()updateDoc()一起使用,告诉服务器将字段的当前值增加给定值。如果操作数或当前字段值使用浮点精度,则所有算术都遵循 IEEE 754 语义。如果两个值都是整数,则超出 JavaScript 安全数字范围( Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER )的值也会受到精度损失的影响。此外,一旦由 Firestore 后端处理,所有整数运算都限制在 -2^63 和 2^63-1 之间。如果当前字段值不是number类型,或者该字段尚不存在,则转换会将该字段设置为给定值。
函数(查询,...)
getAggregate(查询,aggregateSpec)计算给定查询结果集中文档的指定聚合,而无需实际下载文档。使用此函数执行聚合非常高效,因为仅下载最终聚合值,而不下载文档数据。当结果集太大而无法完全下载(数千个文档)时,此函数可以执行文档聚合。
获取计数(查询)计算给定查询的结果集中的文档数,而无需实际下载文档。使用此功能对文档进行计数非常高效,因为只下载最终计数,而不下载文档数据。当结果集太大而无法完全下载(数千个文档)时,此函数可以对文档进行计数。
获取文档(查询)执行查询并将结果作为QuerySnapshot返回所有查询都直接由服务器执行,即使该查询之前已执行过。最近的修改仅在后端已应用的情况下才会反映在检索到的结果中。如果客户端离线,则操作失败。要查看之前缓存的结果和本地修改,请使用完整的 Firestore SDK。
查询(查询、复合过滤器、查询约束)创建一个新的不可变Query实例,该实例已扩展为还包含其他查询约束。
查询(查询,查询约束)创建一个新的不可变Query实例,该实例已扩展为还包含其他查询约束。
函数(查询约束,...)
和(查询约束)创建一个新的QueryCompositeFilterConstraint ,它是给定过滤器约束的结合。如果合取过滤器满足所有给定过滤器,则该文档包含该文档。
或(查询约束)创建一个新的QueryCompositeFilterConstraint ,它是给定过滤器约束的析取。如果析取过滤器满足任何给定过滤器,则该文档包含该文档。
函数(参考,...)
addDoc(参考,数据)使用给定数据将新文档添加到指定的CollectionReference ,并自动为其分配文档 ID。此写入的结果只会反映在返回的 Promise 解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
集合(参考、路径、pathSegments)获取一个CollectionReference实例,该实例引用指定相对路径处的reference子集合。
集合(参考、路径、pathSegments)获取一个CollectionReference实例,该实例引用指定相对路径处的reference子集合。
删除文档(参考)删除指定DocumentReference引用的文档。删除只会反映在返回的 Promise 解决后发生的文档读取中。如果客户端离线,则删除失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
文档(参考、路径、路径段)获取一个DocumentReference实例,该实例引用指定相对路径处的reference内的文档。如果未指定路径,则返回的DocumentReference将使用自动生成的唯一 ID。
文档(参考、路径、路径段)获取一个DocumentReference实例,该实例引用指定相对路径处的reference内的文档。
获取文档(参考)读取指定文档引用所引用的文档。所有文档都直接从服务器获取,即使文档之前已被读取或修改。如果后端已应用最近的修改,则仅会反映在检索到的DocumentSnapshot中。如果客户端离线,则读取失败。如果您喜欢使用缓存或查看本地修改,请使用完整的 Firestore SDK。
setDoc(参考,数据)写入指定DocumentReference引用的文档。如果该文档尚不存在,则会创建该文档。此写入的结果只会反映在返回的 Promise 解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
setDoc(参考、数据、选项)写入指定DocumentReference引用的文档。如果该文档尚不存在,则会创建该文档。如果您提供mergemergeFields ,则提供的数据可以合并到现有文档中。此写入的结果只会反映在返回的 Promise 解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
updateDoc(参考,数据)更新指定DocumentReference引用的文档中的字段。如果应用于不存在的文档,更新将会失败。此更新的结果将仅反映在返回的承诺解决后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
updateDoc(参考、字段、值、moreFieldsAndValues)更新指定DocumentReference引用的文档中的字段 如果应用于不存在的文档,更新将失败。可以通过提供点分隔的字段路径字符串或提供FieldPath对象来更新嵌套字段。此更新的结果将仅反映在返回的承诺解决后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
函数(快照,...)
结束时间(快照)创建一个QueryEndAtConstraint ,将结果集修改为以提供的文档(包含)结束。结束位置与查询的顺序相关。该文档必须包含查询的 orderBy 中提供的所有字段。
结束之前(快照)创建一个QueryEndAtConstraint ,将结果集修改为在提供的文档之前结束(不包括)。结束位置与查询的顺序相关。该文档必须包含查询的 orderBy 中提供的所有字段。
开始之后(快照)创建一个QueryStartAtConstraint ,将结果集修改为在提供的文档之后开始(不包括)。起始位置与查询的顺序相关。该文档必须包含查询的 orderBy 中提供的所有字段。
开始时间(快照)创建一个QueryStartAtConstraint ,它将结果集修改为从提供的文档(包括)开始。起始位置与查询的顺序相关。该文档必须包含此查询的orderBy中提供的所有字段。

课程

班级描述
聚合字段表示可由 Firestore 执行的聚合。
聚合查询快照执行聚合查询的结果。
字节表示字节数组的不可变对象。
收藏参考CollectionReference对象可用于添加文档、获取文档引用和查询文档(使用query() )。
文档参考DocumentReference是指 Firestore 数据库中的文档位置,可用于写入、读取或侦听该位置。引用位置处的文档可能存在,也可能不存在。
文档快照DocumentSnapshot包含从 Firestore 数据库中的文档读取的数据。可以使用.data().get(<field>)提取数据以获取特定字段。对于指向不存在文档的DocumentSnapshot ,任何数据访问都将返回“未定义”。您可以使用exists()方法显式验证文档是否存在。
字段路径FieldPath指的是文档中的字段。该路径可以由单个字段名称(指文档中的顶级字段)或字段名称列表(指文档中的嵌套字段)组成。通过提供字段名称创建FieldPath 。如果提供多个​​字段名称,则路径将指向文档中的嵌套字段。
字段值使用set()update()写入文档字段时可以使用的哨兵值。
火库Cloud Firestore 服务接口。不要直接调用此构造函数。相反,使用getFirestore()
Firestore错误Firestore 操作返回的错误。
地理点表示 Firestore 中地理位置的不可变对象。该位置以纬度/经度对表示。纬度值的范围为 [-90, 90]。经度值的范围为 [-180, 180]。
询问Query是指您可以阅读或收听的查询。您还可以通过添加过滤器和排序来构造精炼的Query对象。
查询复合过滤器约束QueryCompositeFilterConstraint用于通过执行多个QueryFieldFilterConstraint的逻辑 OR 或 AND 来缩小 Firestore 查询返回的文档集s 或QueryCompositeFilterConstraint s。 QueryCompositeFilterConstraint通过调用or()and()创建,然后可以传递给query()以创建也包含QueryCompositeFilterConstraint的新查询实例。
查询约束QueryConstraint用于缩小 Firestore 查询返回的文档集。 QueryConstraint通过调用where()创建, orderBy() ,开始处() ,开始之后() ,结束之前() ,结束 ()限制()limitToLast()然后可以传递给query()以创建一个也包含此QueryConstraint的新查询实例。
查询文档快照QueryDocumentSnapshot包含作为查询的一部分从 Firestore 数据库中的文档读取的数据。该文档保证存在,并且可以使用.data().get(<field>)提取其数据以获取特定字段。 QueryDocumentSnapshot提供与DocumentSnapshot相同的 API 界面。由于查询结果仅包含现有文档, exists属性将始终为 true,并且data()永远不会返回“未定义”。
查询结束约束QueryEndAtConstraint用于从 Firestore 查询返回的结果集末尾排除文档。 QueryEndAtConstraint是通过调用endAt()endBefore()创建的,然后可以传递给query()以创建也包含此QueryEndAtConstraint的新查询实例。
查询字段过滤约束QueryFieldFilterConstraint用于通过过滤一个或多个文档字段来缩小 Firestore 查询返回的文档集。 QueryFieldFilterConstraint是通过调用where()创建的,然后可以传递给query()以创建一个也包含此QueryFieldFilterConstraint的新查询实例。
查询限制约束QueryLimitConstraint用于限制 Firestore 查询返回的文档数量。 QueryLimitConstraint是通过调用limit()limitToLast()创建的,然后可以传递给query()以创建一个也包含此QueryLimitConstraint的新查询实例。
按约束查询顺序QueryOrderByConstraint用于对 Firestore 查询返回的文档集进行排序。 QueryOrderByConstraint是通过调用orderBy()创建的,然后可以传递给query()以创建一个也包含此QueryOrderByConstraint的新查询实例。注意:不包含 orderBy 字段的文档不会出现在查询结果中。
查询快照QuerySnapshot包含零个或多个表示查询结果的DocumentSnapshot对象。文档可以通过docs属性作为数组进行访问,也可以使用forEach方法进行枚举。文档的数量可以通过emptysize属性来确定。
查询开始约束QueryStartAtConstraint用于从 Firestore 查询返回的结果集的开头排除文档。 QueryStartAtConstraint是通过调用startAt()startAfter()创建的,然后可以传递给query()以创建一个也包含此QueryStartAtConstraint的新查询实例。
时间戳Timestamp表示独立于任何时区或日历的时间点,以 UTC 纪元时间中纳秒分辨率的秒和秒的分数表示。它使用 Proleptic 公历进行编码,将公历向后延伸到第一年。它的编码假定所有分钟都是 60 秒长,即闰秒被“涂抹”,因此不需要闰秒表来解释。范围从 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。有关示例和更多规范,请参阅时间戳定义
交易对交易的引用。传递给事务的updateFunctionTransaction对象提供在事务上下文中读取和写入数据的方法。参见runTransaction()
写批处理写入批处理,用于将多个写入作为单个原子单元执行。可以通过调用writeBatch()获取WriteBatch对象。它提供了将写入添加到写入批次的方法。在调用WriteBatch.commit()之前,不会提交任何写入(或在本地可见)。

接口

界面描述
聚合规格指定一组聚合及其别名。
文档数据文档数据(与setDoc()一起使用) 由映射到值的字段组成。
Firestore数据转换器withConverter()使用转换器将AppModelType类型的用户对象转换为DbModelType类型的 Firestore 数据。使用转换器允许您在从 Firestore 存储和检索对象时指定通用类型参数。在这种情况下,“AppModel”是在应用程序中用于将相关信息和功能打包在一起的类。例如,这样的类可以具有复杂嵌套数据类型的属性、用于记忆的属性、Firestore 不支持的类型的属性(例如symbolbigint )以及执行复合操作的辅助函数。此类类不适合和/或不可能存储到 Firestore 数据库中。相反,此类的实例需要转换为具有专有原始属性的“普通旧 JavaScript 对象”(POJO),可能嵌套在其他 POJO 或 POJO 数组中。在此上下文中,此类型称为“DbModel”,并且是适合持久保存到 Firestore 中的对象。为了方便起见,应用程序可以实现FirestoreDataConverter并向 Firestore 对象(例如DocumentReferenceQuery注册转换器,以便在存储到 Firestore 时自动将AppModel转换为DbModel ,并在从 Firestore 检索时自动将DbModel转换为AppModel
设置指定 Cloud Firestore 实例的自定义配置。您必须在调用任何其他方法之前设置这些。
交易选项自定义交易行为的选项。

类型别名

类型别名描述
添加前缀到键返回一个新映射,其中每个键都以附加到点的外部键为前缀。
聚合字段类型Firestore 支持的所有AggregateField类型的并集。
聚合规格数据一种类型,其键取自AggregateSpec ,其值是输入AggregateSpec中相应AggregateField执行聚合的结果。
聚合类型联合类型表示要执行的聚合类型。
子更新字段用于计算给定类型 T1 的嵌套字段的帮助程序。这是分配联合类型(例如undefined | {...}所必需的。 undefined | {...} (发生在可选 props 中)或{a: A} | {b: B}在此用例中, V用于在Record上分发T[K]的联合类型,因为T[K]被计算为表达式而不是分发。请参阅 https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
Firestore错误代码Firestore 状态代码集。这些代码与 gRPC 公开的代码相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md可能的值: - 'cancelled':操作被取消(通常由调用者取消)。 -“未知”:未知错误或来自不同错误域的错误。 -“无效参数”:客户端指定了无效参数。请注意,这与“失败前提条件”不同。 “invalid-argument”表示无论系统状态如何都有问题的参数(例如无效的字段名称)。 -“超过截止日期”:操作完成之前截止日期已过。对于更改系统状态的操作,即使操作已成功完成,也可能会返回此错误。例如,服务器的成功响应可能会延迟足够长的时间,以致截止日期到期。 -“未找到”:未找到某些请求的文档。 -“已经存在”:我们尝试创建的某些文档已经存在。 - 'permission-denied':调用者没有执行指定操作的权限。 -“资源耗尽”:某些资源已耗尽,可能是每个用户的配额,或者可能是整个文件系统空间不足。 - 'failed-precondition':操作被拒绝,因为系统未处于操作执行所需的状态。 -“已中止”:操作被中止,通常是由于事务中止等并发问题。 -“超出范围”:尝试的操作超出了有效范围。 -“未实现”:操作未实现或不支持/启用。 -“内部”:内部错误。意味着底层系统期望的一些不变量已经被打破。如果您看到其中一个错误,则表明某些内容已严重损坏。 -“不可用”:该服务当前不可用。这很可能是瞬态情况,可以通过退避重试来纠正。 -“数据丢失”:不可恢复的数据丢失或损坏。 -“未经身份验证”:请求没有用于操作的有效身份验证凭据。
嵌套更新字段对于每个字段(例如“bar”),查找所有嵌套键(例如{ 'bar.baz':T1,'bar.qux':T2 } )。将它们交叉在一起以形成一个包含所有可能的键(全部标记为可选)的映射
按方向订购orderBy()子句的方向指定为“desc”或“asc”(降序或升序)。
带字段值的部分与 Typescript 的Partial<T>类似,但允许省略嵌套字段并允许将 FieldValues 作为属性值传入。
原始原始类型。
查询约束类型描述此 SDK 中可用的不同查询约束。
查询过滤约束QueryFilterConstraint是表示QueryFieldFilterConstraintQueryCompositeFilterConstraint的辅助联合类型
查询非过滤约束QueryNonFilterConstraint是一种辅助联合类型,表示 QueryConstraint,用于缩小或排序文档集,但不会显式过滤文档字段。 QueryNonFilterConstraint通过调用orderBy()创建,开始处() ,开始之后() ,结束之前() ,结束 ()limit()limitToLast() ,然后可以传递给query()以创建一个也包含QueryConstraint新查询实例。
设置选项配置setDoc()行为的选项对象,并拨打电话。可以将这些调用配置为执行粒度合并,而不是通过提供带有merge: trueSetOptions来完全覆盖目标文档。
并集到交集给定一个联合类型U = T1 | T2 | ... ,返回相交类型(T1 & T2 & ...)使用分布式条件类型和条件类型的推断。这是有效的,因为逆变位置中同一类型变量的多个候选者会导致推断出交集类型。 https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-in​​ference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection -类型
更新数据更新数据(与updateDoc()一起使用),由映射到值的字段路径(例如“foo”或“foo.baz”)组成。包含点的字段引用文档中的嵌套字段。 FieldValues 可以作为属性值传入。
过滤器所在位置where()子句中的过滤条件使用字符串 '<'、'<='、'=='、'!='、'>='、'>'、'array-contains' 指定、“在”、“数组包含任何”和“不在”。
带字段值允许 FieldValues 作为属性值传入,同时保持类型安全。

函数(应用程序,...)

获取Firestore(应用程序)

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

签名:

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

参数

范围类型描述
应用程序Firebase应用程序返回的Firestore实例关联的FirebaseApp实例。

返回:

火库

所提供应用程序的Firestore实例。

getFirestore(应用程序,数据库Id)

此 API 作为开发人员预览版提供,可能会根据我们收到的反馈进行更改。不要在生产环境中使用此 API。

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

签名:

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

参数

范围类型描述
应用程序Firebase应用程序返回的Firestore实例关联的FirebaseApp实例。
数据库ID细绳数据库的名称。

返回:

火库

所提供应用程序的Firestore实例。

初始化Firestore(应用程序,设置)

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

签名:

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

参数

范围类型描述
应用程序Firebase应用程序Firestore实例将与之关联的FirebaseApp
设置设置用于配置Firestore实例的设置对象。

返回:

火库

新初始化的Firestore实例。

初始化Firestore(应用程序,设置,databaseId)

此 API 作为开发人员预览版提供,可能会根据我们收到的反馈进行更改。不要在生产环境中使用此 API。

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

签名:

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

参数

范围类型描述
应用程序Firebase应用程序Firestore实例将与之关联的FirebaseApp
设置设置用于配置Firestore实例的设置对象。
数据库ID细绳数据库的名称。

返回:

火库

新初始化的Firestore实例。

函数(firestore,...)

集合(firestore、路径、pathSegments)

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

签名:

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

参数

范围类型描述
火库火库对根Firestore实例的引用。
小路细绳以斜线分隔的集合路径。
路径段细绳[]相对于第一个参数应用的附加路径段。

返回:

收藏参考<文档数据,文档数据>

CollectionReference实例。

例外情况

如果最终路径有偶数个段并且不指向集合。

集合组(firestore,集合Id)

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

签名:

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

参数

范围类型描述
火库火库对根Firestore实例的引用。
集合ID细绳标识要查询的集合。将包含将此 ID 作为其路径最后一段的每个集合或子集合。不能包含斜杠。

返回:

询问<文档数据,文档数据>

创建的Query

connectFirestoreEmulator(firestore、主机、端口、选项)

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

签名:

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

参数

范围类型描述
火库火库要配置为连接到模拟器的Firestore实例。
主持人细绳模拟器主机(例如:localhost)。
港口数字模拟器端口(例如:9000)。
选项{mockUserToken?: EmulatorMockTokenOptions |细绳; }

返回:

空白

文档(firestore、路径、pathSegments)

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

签名:

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

参数

范围类型描述
火库火库对根Firestore实例的引用。
小路细绳以斜线分隔的文档路径。
路径段细绳[]将相对于第一个参数应用的附加路径段。

返回:

文档参考<文档数据,文档数据>

DocumentReference实例。

例外情况

如果最终路径有奇数个段并且不指向文档。

runTransaction(firestore,updateFunction,选项)

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

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

签名:

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

参数

范围类型描述
火库火库对运行此事务的 Firestore 数据库的引用。
更新函数(交易:交易) => 承诺<T>在事务上下文中执行的函数。
选项交易选项用于配置尝试提交的最大次数的选项对象。

返回:

承诺<T>

如果事务成功完成或显式中止( updateFunction返回失败的 Promise),则updateFunction返回的 Promise返回这里。否则,如果交易失败,则会返回带有相应失败错误的拒绝承诺。

终止(火存储)

终止提供的Firestore实例。

调用terminate()后,只能使用clearIndexedDbPersistence()函数。任何其他函数都会抛出FirestoreError 。终止不会取消任何挂起的写入,并且任何等待服务器响应的承诺都不会得到解决。

要在终止后重新启动,请使用getFirestore()创建Firestore的新实例

签名:

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

参数

范围类型描述
火库火库要终止的Firestore实例。

返回:

承诺<无效>

当实例成功终止时解决的Promise

writeBatch(火存储)

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

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

签名:

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

参数

范围类型描述
火库火库

返回:

写批处理

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

功能()

数数()

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

签名:

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

返回:

聚合字段<数字>

删除字段()

返回一个哨兵,与带有{merge: true}updateDoc()setDoc()一起使用,以标记要删除的字段。

签名:

export declare function deleteField(): FieldValue;

返回:

字段值

文档ID()

返回一个特殊的哨兵FieldPath来引用文档的 ID。它可用于在查询中按文档 ID 排序或过滤。

签名:

export declare function documentId(): FieldPath;

返回:

字段路径

获取Firestore()

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

签名:

export declare function getFirestore(): Firestore;

返回:

火库

所提供应用程序的Firestore实例。

服务器时间戳()

返回与setDoc()updateDoc()一起使用的哨兵,以在写入的数据中包含服务器生成的时间戳。

签名:

export declare function serverTimestamp(): FieldValue;

返回:

字段值

函数(数据库ID,...)

getFirestore(数据库ID)

此 API 作为开发人员预览版提供,可能会根据我们收到的反馈进行更改。不要在生产环境中使用此 API。

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

签名:

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

参数

范围类型描述
数据库ID细绳数据库的名称。

返回:

火库

所提供应用程序的Firestore实例。

函数(元素,...)

数组删除(元素)

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

签名:

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

参数

范围类型描述
元素未知[]要从数组中删除的元素。

返回:

字段值

用于调用setDoc()updateDoc()FieldValue标记

数组联合(元素)

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

签名:

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

参数

范围类型描述
元素未知[]要合并到数组中的元素。

返回:

字段值

用于调用setDoc()updateDoc()FieldValue标记

函数(字段,...)

平均(场)

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

签名:

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

参数

范围类型描述
场地字符串 |字段路径指定要在结果集中求平均值的字段。

返回:

聚合字段<数字|空>

总和(字段)

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

签名:

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

参数

范围类型描述
场地字符串 |字段路径指定要在结果集中求和的字段。

返回:

聚合字段<数字>

函数(字段路径,...)

orderBy(fieldPath, 方向Str)

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

签名:

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

参数

范围类型描述
字段路径字符串 |字段路径排序依据的字段。
方向Str按方向订购可选的排序方向(“asc”或“desc”)。如果未指定,则顺序将升序。

返回:

按约束查询顺序

创建的QueryOrderByConstraint

其中(字段路径、opStr、值)

创建一个QueryFieldFilterConstraint ,强制文档必须包含指定字段并且该值应满足提供的关系约束。

签名:

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

参数

范围类型描述
字段路径字符串 |字段路径比较路径
操作符过滤器所在位置操作字符串(例如“<”、“<=”、“==”、“<”、“<=”、“!=”)。
价值未知比较值

返回:

查询字段过滤约束

创建的QueryFieldFilterConstraint

函数(字段值,...)

结束于(字段值)

创建一个QueryEndAtConstraint ,它将结果集修改为相对于查询顺序在提供的字段处结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

范围类型描述
字段值未知[]结束此查询的字段值,按照查询的排序依据。

返回:

查询结束约束

传递给query() QueryEndAtConstraint

结束之前(字段值)

创建一个QueryEndAtConstraint ,将结果集修改为相对于查询顺序在提供的字段之前结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

范围类型描述
字段值未知[]之前结束此查询的字段值,按照查询的排序依据。

返回:

查询结束约束

传递给query() QueryEndAtConstraint

开始之后(字段值)

创建一个QueryStartAtConstraint ,它将结果集修改为相对于查询顺序在提供的字段之后开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

范围类型描述
字段值未知[]之后启动此查询的字段值,按照查询的排序依据。

返回:

查询开始约束

传递给query() QueryStartAtConstraint

开始于(字段值)

创建一个QueryStartAtConstraint ,它将结果集修改为从相对于查询顺序提供的字段开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

范围类型描述
字段值未知[]启动此查询的字段值,按照查询的排序依据。

返回:

查询开始约束

传递给query() QueryStartAtConstraint

函数(左,...)

聚合字段等于(左,右)

比较两个“AggregateField” ` 平等的实例。

签名:

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

参数

范围类型描述
左边聚合字段<未知>将此 AggregateField 与right进行比较。
正确的聚合字段<未知>将此 AggregateField 与left进行比较。

返回:

布尔值

聚合查询快照等于(左,右)

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

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

签名:

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

参数

范围类型描述
左边聚合查询快照<AggregateSpecType、AppModelType、DbModelType>要比较的第一个AggregateQuerySnapshot
正确的聚合查询快照<AggregateSpecType、AppModelType、DbModelType>要比较的第二个AggregateQuerySnapshot

返回:

布尔值

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

查询等于(左,右)

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

签名:

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

参数

范围类型描述
左边询问<应用程序模型类型,Db模型类型>要比较的Query
正确的询问<应用程序模型类型,Db模型类型>要比较的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;

参数

范围类型描述
左边文档参考<AppModelType,DbModelType> |收藏参考<应用程序模型类型,Db模型类型>供比较参考。
正确的文档参考<AppModelType,DbModelType> |收藏参考<应用程序模型类型,Db模型类型>供比较参考。

返回:

布尔值

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

快照等于(左,右)

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

签名:

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

参数

范围类型描述
左边文档快照<AppModelType,DbModelType> |查询快照<应用程序模型类型,Db模型类型>进行比较的快照。
正确的文档快照<AppModelType,DbModelType> |查询快照<应用程序模型类型,Db模型类型>进行比较的快照。

返回:

布尔值

如果快照相等则为 true。

函数(极限,...)

限制(限制)

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

签名:

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

参数

范围类型描述
限制数字要返回的最大项目数。

返回:

查询限制约束

创建的QueryLimitConstraint

限制到最后(限制)

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

limitToLast查询必须至少指定一个orderBy子句,否则执行过程中会抛出异常。

签名:

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

参数

范围类型描述
限制数字要返回的最大项目数。

返回:

查询限制约束

创建的QueryLimitConstraint

函数(日志级别,...)

设置日志级别(日志级别)

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

签名:

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

参数

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

返回:

空白

函数(n,...)

增量(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数字要增加的值。

返回:

字段值

用于调用setDoc()updateDoc()FieldValue标记

函数(查询,...)

getAggregate(查询,aggregateSpec)

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

使用此函数执行聚合非常高效,因为仅下载最终聚合值,而不下载文档数据。当结果集太大而无法完全下载(数千个文档)时,此函数可以执行文档聚合。

签名:

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

参数

范围类型描述
询问询问<应用程序模型类型,Db模型类型>结果集被聚合的查询。
聚合规范聚合规格类型一个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;

获取计数(查询)

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

使用此功能对文档进行计数非常高效,因为只下载最终计数,而不下载文档数据。当结果集太大而无法完全下载(数千个文档)时,此函数可以对文档进行计数。

签名:

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

参数

范围类型描述
询问询问<应用程序模型类型,Db模型类型>计算其结果集大小的查询。

返回:

Promise< AggregateQuerySnapshot <{ 计数:聚合字段<数字>; }, AppModelType, DbModelType>>

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

获取文档(查询)

执行查询并将结果作为QuerySnapshot返回

所有查询都直接由服务器执行,即使该查询之前已执行过。最近的修改仅在后端已应用的情况下才会反映在检索到的结果中。如果客户端离线,则操作失败。要查看之前缓存的结果和本地修改,请使用完整的 Firestore SDK。

签名:

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

参数

范围类型描述
询问询问<应用程序模型类型,Db模型类型>要执行的Query

返回:

Promise<查询快照<应用程序模型类型,Db模型类型>>

将通过查询结果解决的 Promise。

查询(查询、复合过滤器、查询约束)

创建一个新的不可变Query实例,该实例已扩展为还包含其他查询约束。

签名:

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

参数

范围类型描述
询问询问<应用程序模型类型,Db模型类型>用作新约束基础的查询实例。
复合过滤器查询复合过滤器约束要应用的QueryCompositeFilterConstraint 。使用and()or()创建QueryCompositeFilterConstraint
查询约束查询非过滤约束[]附加QueryNonFilterConstraint s 来应用(例如orderBy()限制() )。

返回:

询问<应用程序模型类型,Db模型类型>

例外情况

如果提供的任何查询约束无法与现有或新约束组合。

查询(查询,查询约束)

创建一个新的不可变Query实例,该实例已扩展为还包含其他查询约束。

签名:

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

参数

范围类型描述
询问询问<应用程序模型类型,Db模型类型>用作新约束基础的查询实例。
查询约束查询约束[]查询约束列表申请。

返回:

询问<应用程序模型类型,Db模型类型>

例外情况

如果提供的任何查询约束无法与现有或新约束组合。

函数(查询约束,...)

和(查询约束)

创建一个新的QueryCompositeFilterConstraint ,它是给定过滤器约束的结合。如果合取过滤器满足所有给定过滤器,则该文档包含该文档。

签名:

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

参数

范围类型描述
查询约束查询过滤约束[]选修的。 QueryFilterConstraint列表s 执行连词。这些必须通过调用where()创建或者() , 或和 ()

返回:

查询复合过滤器约束

新创建的QueryCompositeFilterConstraint

或(查询约束)

创建一个新的QueryCompositeFilterConstraint ,它是给定过滤器约束的析取。如果析取过滤器满足任何给定过滤器,则该文档包含该文档。

签名:

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

参数

范围类型描述
查询约束查询过滤约束[]选修的。 QueryFilterConstraint列表s 执行析取。这些必须通过调用where()创建或者() , 或和 ()

返回:

查询复合过滤器约束

新创建的QueryCompositeFilterConstraint

函数(参考,...)

addDoc(参考,数据)

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

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

签名:

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

参数

范围类型描述
参考收藏参考<应用程序模型类型,Db模型类型>对要添加此文档的集合的引用。
数据带字段值<应用程序模型类型>包含新文档数据的对象。

返回:

Promise<文档参考<应用程序模型类型,Db模型类型>>

在写入后端后,用指向新创建的文档的DocumentReference解决了Promise

例外情况

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

集合(参考、路径、pathSegments)

获取一个CollectionReference实例,该实例引用指定相对路径处的reference子集合。

签名:

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

参数

范围类型描述
参考收藏参考<应用程序模型类型,Db模型类型>对集合的引用。
小路细绳以斜线分隔的集合路径。
路径段细绳[]相对于第一个参数应用的附加路径段。

返回:

收藏参考<文档数据,文档数据>

CollectionReference实例。

例外情况

如果最终路径有偶数个段并且不指向集合。

集合(参考、路径、pathSegments)

获取一个CollectionReference实例,该实例引用指定相对路径处的reference子集合。

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>对 Firestore 文档的引用。
小路细绳以斜线分隔的集合路径。
路径段细绳[]将相对于第一个参数应用的附加路径段。

返回:

收藏参考<文档数据,文档数据>

CollectionReference实例。

例外情况

如果最终路径有偶数个段并且不指向集合。

删除文档(参考)

删除指定DocumentReference引用的文档

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

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>对要删除的文档的引用。

返回:

承诺<无效>

一旦文档从后端成功删除, Promise就会得到解决。

文档(参考、路径、路径段)

获取一个DocumentReference实例,该实例引用指定相对路径处的reference内的文档。如果未指定路径,则返回的DocumentReference将使用自动生成的唯一 ID

签名:

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

参数

范围类型描述
参考收藏参考<应用程序模型类型,Db模型类型>对集合的引用。
小路细绳以斜线分隔的文档路径。必须省略才能使用自动生成的 ID。
路径段细绳[]将相对于第一个参数应用的附加路径段。

返回:

文档参考<应用程序模型类型,Db模型类型>

DocumentReference实例。

例外情况

如果最终路径有奇数个段并且不指向文档。

文档(参考、路径、路径段)

获取一个DocumentReference实例,该实例引用指定相对路径处的reference内的文档。

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>对 Firestore 文档的引用。
小路细绳以斜线分隔的文档路径。
路径段细绳[]将相对于第一个参数应用的附加路径段。

返回:

文档参考<文档数据,文档数据>

DocumentReference实例。

例外情况

如果最终路径有奇数个段并且不指向文档。

获取文档(参考)

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

所有文档都直接从服务器获取,即使文档之前已被读取或修改。如果后端已应用最近的修改,则仅会反映在检索到的DocumentSnapshot中。如果客户端离线,则读取失败。如果您喜欢使用缓存或查看本地修改,请使用完整的 Firestore SDK。

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>要获取的文档的参考。

返回:

Promise<文档快照<应用程序模型类型,Db模型类型>>

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

setDoc(参考,数据)

写入指定DocumentReference引用的文档。如果该文档尚不存在,则会创建该文档。

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

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>参考要写的文档。
数据带字段值<应用程序模型类型>文档的字段和值的映射。

返回:

承诺<无效>

一旦数据成功写入后端, Promise就会得到解决。

例外情况

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

setDoc(参考、数据、选项)

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

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

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>参考要写的文档。
数据带字段值的部分<应用程序模型类型>文档的字段和值的映射。
选项设置选项用于配置设置行为的对象。

返回:

承诺<无效>

一旦数据成功写入后端, Promise就会得到解决。

例外情况

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

updateDoc(参考,数据)

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

此更新的结果将仅反映在返回的承诺解决后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>对要更新的文档的引用。
数据更新数据<数据库模型类型>包含用于更新文档的字段和值的对象。字段可以包含点来引用文档中的嵌套字段。

返回:

承诺<无效>

一旦数据成功写入后端, Promise就会得到解决。

例外情况

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

updateDoc(参考、字段、值、moreFieldsAndValues)

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

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

此更新的结果将仅反映在返回的承诺解决后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端上线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。

签名:

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

参数

范围类型描述
参考文档参考<应用程序模型类型,Db模型类型>对要更新的文档的引用。
场地字符串 |字段路径要更新的第一个字段。
价值未知第一个值。
更多字段和值未知[]附加键值对。

返回:

承诺<无效>

一旦数据成功写入后端, Promise就会得到解决。

例外情况

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

函数(快照,...)

结束时间(快照)

创建一个QueryEndAtConstraint ,将结果集修改为以提供的文档(包含)结束。结束位置与查询的顺序相关。该文档必须包含查询的 orderBy 中提供的所有字段。

签名:

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

参数

范围类型描述
快照文档快照<应用程序模型类型,Db模型类型>文档结束的快照。

返回:

查询结束约束

传递给query() QueryEndAtConstraint

结束之前(快照)

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

签名:

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

参数

范围类型描述
快照文档快照<应用程序模型类型,Db模型类型>文档结束之前的快照。

返回:

查询结束约束

传递给query() QueryEndAtConstraint

开始之后(快照)

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

签名:

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

参数

范围类型描述
快照文档快照<应用程序模型类型,Db模型类型>之后开始的文档的快照。

返回:

查询开始约束

传递给query() QueryStartAtConstraint

开始时间(快照)

创建一个QueryStartAtConstraint ,它将结果集修改为从提供的文档(包括)开始。起始位置与查询的顺序相关。该文档必须包含此查询的orderBy中提供的所有字段。

签名:

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

参数

范围类型描述
快照文档快照<应用程序模型类型,Db模型类型>文档的起始位置的快照。

返回:

查询开始约束

传递给query() QueryStartAtConstraint

添加前缀到键

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

签名:

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

子更新字段

用于计算给定类型 T1 的嵌套字段的帮助程序。这是分配联合类型(例如undefined | {...}所必需的。 undefined | {...} (发生在可选 props 中)或{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;

Firestore错误代码

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

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

签名:

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

嵌套更新字段

对于每个字段(例如“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]>;

按方向订购

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

签名:

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

带字段值的部分

类似于 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;

查询约束类型

描述此 SDK 中可用的不同查询约束。

签名:

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

查询过滤约束

QueryFilterConstraint是表示QueryFieldFilterConstraintQueryCompositeFilterConstraint的辅助联合类型

签名:

export declare type QueryFilterConstraint = QueryFieldFilterConstraint | QueryCompositeFilterConstraint;

查询非过滤约束

QueryNonFilterConstraint是一种辅助联合类型,表示 QueryConstraint,用于缩小或排序文档集,但不会显式过滤文档字段。 QueryNonFilterConstraint s 通过调用orderBy()创建,开始处() ,开始之后() ,结束之前() ,结束 ()limit()limitToLast()然后可以传递给query()以创建一个也包含QueryConstraint的新查询实例

签名:

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

设置选项

配置setDoc()行为的选项对象,并拨打电话。可以将这些调用配置为执行粒度合并,而不是通过提供带有merge: trueSetOptions来完全覆盖目标文档

签名:

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

并集到交集

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

使用分布式条件类型和条件类型的推断。这是有效的,因为逆变位置中同一类型变量的多个候选者会导致推断出交集类型。 https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-in​​ference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection -类型

签名:

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

更新数据

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

签名:

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

过滤器所在位置

where()子句中的过滤条件使用字符串 '<'、'<='、'=='、'!='、'>='、'>'、'array-contains' 指定、“在”、“数组包含任何”和“不在”。

签名:

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

带字段值

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

签名:

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