Google 致力于为黑人社区推动种族平等。查看具体举措

@firebase/firestore/lite

职能

功能描述
addDoc(参考,数据)添加新文档到指定CollectionReference与给定的数据,会自动分配一个文件编号。此写入的结果将仅反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
arrayRemove(元素)返回可与使用的特殊值setDoc()或它告诉服务器,以除去从已存在的服务器上的任何数组值给定的元件。指定的每个元素的所有实例都将从数组中删除。如果被修改的字段还不是一个数组,它将被一个空数组覆盖。
数组联合(元素)返回可与使用的特殊值setDoc()updateDoc() ,它告诉服务器联合给定元件以任何阵列的值已经存在于服务器上。数组中不存在的每个指定元素都将添加到末尾。如果被修改的字段还不是一个数组,它将被一个包含指定元素的数组覆盖。
集合(firestore,路径,pathSegments)获取CollectionReference是指集合在指定的绝对路径的实例。
集合(参考,路径,路径段)获取一个CollectionReference引用的子集合实例reference在指定的相对路径。
集合(参考,路径,路径段)获取一个CollectionReference引用的子集合实例reference在指定的相对路径。
collectionGroup(firestore,collectionId)创建并返回一个新Query ,包括所包含的集合或子集合给定的数据库中的所有文档实例collectionId
connectFirestoreEmulator(firestore,主机,端口,选项)修改此实例以与 Cloud Firestore 模拟器进行通信。注意:必须在使用此实例执行任何操作之前调用它。
删除文档(参考)删除文件由指定的称为DocumentReference删除只会反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则删除失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
删除字段()返回定点与使用updateDoc()setDoc(){merge: true}标记字段删除。
doc(firestore, path, pathSegments)获取一个DocumentReference是指在指定的绝对路径的文档实例。
doc(参考,路径,路径段)获取一个DocumentReference引用文档内的实例reference在指定的相对路径。如果没有指定路径,自动生成的唯一的ID将被用于返回DocumentReference
文档(参考,路径,路径段)获取一个DocumentReference引用文档内的实例reference在指定的相对路径。
文档 ID()返回一个特殊定点FieldPath引用文档的ID。它可用于查询以按文档 ID 排序或过滤。
结束(快照)创建QueryConstraint修改该结果集以在所提供的文档(含)结束。结束位置相对于查询的顺序。该文档必须包含查询的 orderBy 中提供的所有字段。
结束(字段值)创建QueryConstraint修改该结果集以在相对于该查询的顺序所提供的字段结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。
结束前(快照)创建QueryConstraint修改该结果集所提供的文件(不包括)之前结束。结束位置相对于查询的顺序。该文档必须包含查询的 orderBy 中提供的所有字段。
结束前(字段值)创建QueryConstraint修改该结果集以相对于查询的顺序所提供的字段之前结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。
获取文档(参考)读取指定文档引用所引用的文档。所有文档都直接从服务器获取,即使该文档之前已被读取或修改过。最近的修改仅仅体现在检索到的DocumentSnapshot如果他们已经由后端应用。如果客户端离线,则读取失败。如果您喜欢使用缓存或查看本地修改,请使用完整的 Firestore SDK。
获取文档(查询)执行查询并返回结果为QuerySnapshot .所有查询都由服务器直接执行,即使该查询之前已执行。如果后端已经应用了最近的修改,则仅会在检索到的结果中反映出来。如果客户端离线,则操作失败。要查看之前缓存的结果和本地修改,请使用完整的 Firestore SDK。
getFirestore(应用程序)返回现有Firestore与该提供相关的实例FirebaseApp .如果不存在实例,则使用默认设置初始化一个新实例。
增量(n)返回可与使用特殊值setDoc()updateDoc() ,它告诉服务器由给定的值递增字段的当前值。如果操作数或当前字段值使用浮点精度,则所有算术都遵循 IEEE 754 语义。如果两个值都是整数,价值观JavaScript的安全号码范围之外( Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER )也受到精度损失。此外,一旦由 Firestore 后端处理,所有整数运算的上限都在 -2^63 和 2^63-1 之间。如果当前字段值的类型不是number ,或者如果该字段不存在,转型将字段设置为给定值。
initializeFirestore(应用程序,设置)使用提供的设置初始化 Cloud Firestore 的新实例。只能在任何其他的功能,其中包括被称为getFirestore() .如果自定义设置为空,此功能相当于调用getFirestore() .
限制(限制)创建一个QueryConstraint只返回第一个匹配的文件。
限制到最后(限制)创建一个QueryConstraint只返回最后一个匹配的文件。您必须至少指定一个orderBy的条款limitToLast查询,否则异常将在执行过程中被抛出。
orderBy(fieldPath, directionStr)创建QueryConstraint通过指定字段排序查询结果,任选以降序而不是升序的。
查询(查询,查询约束)创建一个新的不可改变的情况下查询被扩展为包括额外的查询约束。
查询相等(左,右)如果提供的查询指向相同的集合并应用相同的约束,则返回 true。
refEqual(左,右)如果提供的引用相等,则返回 true。
runTransaction(firestore, updateFunction)执行给定updateFunction ,然后尝试提交事务中应用更改。如果事务内读取任何文件发生了改变,云计算公司的FireStore重试updateFunction 。如果在 5 次尝试后未能提交,则事务失败。单个事务中允许的最大写入次数为 500。
服务器时间戳()返回与所使用的定点()setDocupdateDoc()以包括所写入的数据由服务器生成时间戳。
setDoc(参考,数据)写入到文件由指定称为DocumentReference 。如果该文档尚不存在,则会创建它。此写入的结果将仅反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
setDoc(参考,数据,选项)写入到文件由指定称为DocumentReference 。如果该文档尚不存在,则会创建它。如果您提供mergemergeFields ,所提供的数据可被合并到现有的文件。此写入的结果将仅反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
设置日志级别(日志级别)设置 Cloud Firestore 日志的详细程度(调试、错误或静默)。
快照相等(左,右)如果提供的快照相等,则返回 true。
开始之后(快照)创建一个QueryConstraint可修改的结果集所提供的文件后(不含)开始。起始位置相对于查询的顺序。该文档必须包含查询的 orderBy 中提供的所有字段。
开始后(字段值)创建一个QueryConstraint可修改的结果集,以相对于查询的顺序提供的字段后开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。
开始(快照)创建QueryConstraint修改该结果集以在所提供的文件(包括)开始。起始位置相对于查询的顺序。该文件必须包含所有在提供的字段的orderBy此查询的。
startAt(fieldValues)创建一个QueryConstraint可修改的结果集,以相对于查询的顺序提供的字段开始。字段值的顺序必须与查询的 order by 子句的顺序匹配。
终止(firestore)终止提供Firestore实例。打完电话后terminate()只有clearIndexedDbPersistence()可使用的功能。任何其他功能将引发FirestoreError 。终止不会取消任何挂起的写入,并且任何等待服务器响应的承诺都不会被解析。终止之后重新启动,创建的新实例FirestoregetFirestore() .注:在正常情况下,呼叫terminate()不是必需的。只有当你想迫使这种情况下,以释放其所有资源或结合这个功能是非常有用的clearIndexedDbPersistence() ,以确保所有本地状态测试运行之间的破坏。
updateDoc(参考,数据)在文档中的更新字段被指定称为DocumentReference 。如果应用于不存在的文档,更新将失败。此更新的结果只会反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
updateDoc(reference, field, value, moreFieldsAndValues)在文档中更新域提到了指定DocumentReference更新,如果应用到一个不存在的文件将失败。嵌套字段可以通过提供点分隔的字段路径字符串或者通过提供被更新FieldPath对象。此更新的结果只会反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则更新失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。
where(fieldPath, opStr, value)创建一个QueryConstraint强制执行该文件必须包含指定的字段和值应满足关系约束提供。
writeBatch(firestore)创建一个写入批处理,用于将多个写入作为单个原子操作执行。单个 WriteBatch 中允许的最大写入次数为 500。这些写入的结果只会反映在返回的承诺解析后发生的文档读取中。如果客户端离线,则写入失败。如果您希望在客户端在线之前查看本地修改或缓冲区写入,请使用完整的 Firestore SDK。

班级

班级描述
字节表示字节数组的不可变对象。
收藏参考一个CollectionReference对象可用于添加文件,文件越来越引用和查询文件(使用查询() )。
文档参考一个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通过添加过滤和排序的对象。
查询约束一个QueryConstraint用来缩小一套由一个公司的FireStore查询返回的文档。 QueryConstraint S被调用创建其中()ORDERBY()startAt()startAfter() ,, ENDAT()限制()limitToLast() ,然后可以传递给查询()创建一个新的查询实例也包含此QueryConstraint
查询文档快照一个QueryDocumentSnapshot包含在你的公司的FireStore数据库从文件中读取作为查询的一部分数据。该文件是保证型存在,其数据可以与被提取.data().get(<field>)得到一个特定的字段。一个QueryDocumentSnapshot提供相同的API表面作为DocumentSnapshot 。由于查询结果仅包含现有的文件中, exists属性将始终是真实data()将永远不会返回“未定义”。
查询快照QuerySnapshot包含零个或更多DocumentSnapshot对象表示查询的结果。文档可以作为通过阵列进行访问docs属性或使用所列举forEach方法。的文档的数量可通过确定emptysize性质。
时间戳Timestamp表示时间独立于任何时区或日历,表示为在历元UTC时间纳秒的分辨率秒和秒的分数的一个点。它使用 Proleptic Gregorian Calendar 编码,将公历向后扩展到第一年。它的编码假设所有分钟都是 60 秒长,即闰秒被“涂抹”,因此不需要闰秒表进行解释。范围是从 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。对于实施例和进一步的规范,请参考时间戳定义.
交易对交易的引用。Transaction传递到交易的对象updateFunction提供方法来读取和事务上下文中写入数据。见runTransaction() .
批量写入写入批处理,用于将多个写入作为单个原子单元执行。WriteBatch对象可以通过调用被获取writeBatch() .它提供了将写入添加到写入批处理的方法。写操作都不会被提交(或可见局部),直到WriteBatch.commit()被调用。

接口

界面描述
文档数据文档数据(用于在使用setDoc() ) 由映射到值的字段组成。
Firestore数据转换器转换器中使用由withConverter()至类型的用户对象变换T到公司的FireStore数据。使用转换器允许您在从 Firestore 存储和检索对象时指定泛型类型参数。
设置为您的 Cloud Firestore 实例指定自定义配置。您必须在调用任何其他方法之前设置这些。

类型别名

类型别名描述
添加前缀到键返回一个新映射,其中每个键都以附加到点的外部键为前缀。
Firestore 错误代码Firestore 状态代码集。代码与 gRPC 在此处公开的代码相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md可能的值: - 'cancelled':操作被取消(通常由调用者)。 - 'unknown':未知错误或来自不同错误域的错误。 - 'invalid-argument':客户端指定了一个无效的参数。请注意,这与“失败前提条件”不同。 'invalid-argument' 表示无论系统状态如何都有问题的参数(例如无效的字段名称)。 - 'deadline-exceeded':在操作完成之前截止日期已过。对于改变系统状态的操作,即使操作成功完成,也可能返回此错误。例如,来自服务器的成功响应可能已经延迟了足够长的时间,以至于截止日期到期。 - 'not-found':未找到某些请求的文档。 - 'already-exists':我们试图创建的某些文档已经存在。 - 'permission-denied':调用者没有执行指定操作的权限。 - 'resource-exhausted':某些资源已耗尽,可能是每个用户的配额,或者可能是整个文件系统空间不足。 - 'failed-precondition':操作被拒绝,因为系统未处于操作执行所需的状态。 - 'aborted':操作被中止,通常是由于事务中止等并发问题。 - 'out-of-range':操作尝试超过有效范围。 - '未实现':操作未实现或不支持/启用。 - '内部':内部错误。意味着底层系统预期的一些不变量已被破坏。如果您看到这些错误之一,则说明某些内容已损坏。 - 'unavailable':服务当前不可用。这很可能是一种瞬态情况,可以通过回退重试来纠正。 - '数据丢失':不可恢复的数据丢失或损坏。 - 'unauthenticated':请求没有操作的有效身份验证凭据。
嵌套更新字段对于每个字段(例如“bar”),找到所有嵌套的键(例如 { 'bar.baz':T1,'bar.qux':T2 } )。将它们相交以制作一个包含所有标记为可选的所有可能键的单个映射
按方向订购a的方向ORDERBY()子句指定为“降序”或“ASC”(升序或降序)。
PartialWithFieldValue类似于打字原稿的Partial<T>被省略,但允许嵌套字段和FieldValues在作为属性值被传递。
原始原始类型。
查询约束类型描述此 SDK 中可用的不同查询约束。
设置选项一个Options对象用于配置的行为setDoc() ,并调用。这些通话可以被配置为执行,而不是通过提供覆盖其全部目标文件颗粒状合并SetOptionsmerge: true
并集到交集给定一个联合型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 可以作为属性值传入。
过滤器操作在过滤器中的条件,其中()子句所使用的字符串指定的'&LT;', '&LT; =' '!=', '==', '&GT; =', '&GT;', '阵列包含' , 'in', 'array-contains-any' 和 'not-in'。
带字段值允许 FieldValues 作为属性值传入,同时保持类型安全。

添加文档()

添加新文档到指定CollectionReference与给定的数据,会自动分配一个文件编号。

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

签名:

export declare function addDoc<T>(reference: CollectionReference<T>, data: WithFieldValue<T>): Promise<DocumentReference<T>>;

参数

范围类型描述
参考收藏参考<T>对要添加此文档的集合的引用。
数据带字段值<T>一个包含新文档数据的对象。

返回:

无极< DocumentReference的<T>>

一个Promise解决与DocumentReference指向新创建的文档已被写入到后端后。

数组移除()

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

签名:

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

参数

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

返回:

字段值

FieldValue哨兵在通话用途setDoc()updateDoc()

数组联合()

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

签名:

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

参数

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

返回:

字段值

FieldValue哨兵在通话用途setDoc()updateDoc() .

收藏()

获取CollectionReference是指集合在指定的绝对路径的实例。

签名:

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

参数

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

返回:

收藏参考< DocumentData >

CollectionReference实例。

例外

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

收藏()

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

签名:

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

参数

范围类型描述
参考收藏参考<未知>对集合的引用。
小路细绳以斜线分隔的集合路径。
路径段细绳[]相对于第一个参数应用的其他路径段。

返回:

收藏参考< DocumentData >

CollectionReference实例。

例外

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

收藏()

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

签名:

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

参数

范围类型描述
参考文档参考对 Firestore 文档的引用。
小路细绳以斜线分隔的集合路径。
路径段细绳[]将相对于第一个参数应用的其他路径段。

返回:

收藏参考< DocumentData >

CollectionReference实例。

例外

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

集合组()

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

签名:

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

参数

范围类型描述
火店火店甲参照根Firestore实例。
集合编号细绳标识要查询的集合。将包含此 ID 作为其路径最后一段的每个集合或子集合。不能包含斜线。

返回:

询问< DocumentData >

创建Query .

connectFirestoreEmulator()

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

签名:

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

参数

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

返回:

空白

删除文档()

删除文件由指定称为DocumentReference .

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

签名:

export declare function deleteDoc(reference: DocumentReference<unknown>): Promise<void>;

参数

范围类型描述
参考文档参考<未知>对要删除的文档的引用。

返回:

承诺<无效>

一个Promise下不为例的文件已经成功地从后台删除。

删除字段()

返回定点与使用updateDoc()setDoc(){merge: true}标记字段删除。

签名:

export declare function deleteField(): FieldValue;

返回:

字段值

文档()

获取一个DocumentReference是指在指定的绝对路径的文档实例。

签名:

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

参数

范围类型描述
火店火店甲参照根Firestore实例。
小路细绳斜线分隔的文档路径。
路径段细绳[]将相对于第一个参数应用的其他路径段。

返回:

文档参考< DocumentData >

DocumentReference实例。

例外

如果最终路径的段数为奇数且不指向文档。

文档()

获取一个DocumentReference引用文档内的实例reference在指定的相对路径。如果没有指定路径,自动生成的唯一的ID将被用于返回DocumentReference .

签名:

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

参数

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

返回:

文档参考<T>

DocumentReference实例。

例外

如果最终路径的段数为奇数且不指向文档。

文档()

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

签名:

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

参数

范围类型描述
参考文档参考<未知>对 Firestore 文档的引用。
小路细绳斜线分隔的文档路径。
路径段细绳[]将相对于第一个参数应用的其他路径段。

返回:

文档参考< DocumentData >

DocumentReference实例。

例外

如果最终路径的段数为奇数且不指向文档。

文档 ID()

返回一个特殊定点FieldPath引用文档的ID。它可用于查询以按文档 ID 排序或过滤。

签名:

export declare function documentId(): FieldPath;

返回:

字段路径

结束()

创建QueryConstraint修改该结果集以在所提供的文档(含)结束。结束位置相对于查询的顺序。该文档必须包含查询的 orderBy 中提供的所有字段。

签名:

export declare function endAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;

参数

范围类型描述
快照文件快照<未知>要结束的文档的快照。

返回:

查询约束

QueryConstraint传递到query()

结束()

创建QueryConstraint修改该结果集以在相对于该查询的顺序所提供的字段结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

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

返回:

查询约束

QueryConstraint传递到query()

结束前()

创建QueryConstraint修改该结果集所提供的文件(不包括)之前结束。结束位置相对于查询的顺序。该文档必须包含查询的 orderBy 中提供的所有字段。

签名:

export declare function endBefore(snapshot: DocumentSnapshot<unknown>): QueryConstraint;

参数

范围类型描述
快照文件快照<未知>之前结束的文档快照。

返回:

查询约束

QueryConstraint传递到query()

结束前()

创建QueryConstraint修改该结果集以相对于查询的顺序所提供的字段之前结束。字段值的顺序必须与查询的 order by 子句的顺序匹配。

签名:

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

参数

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

返回:

查询约束

QueryConstraint传递到query()

获取文档()

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

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

签名:

export declare function getDoc<T>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;

参数

范围类型描述
参考文档参考<T>要获取的文档的引用。

返回:

无极< DocumentSnapshot <T>>

承诺解决与DocumentSnapshot包含当前文档的内容。

获取文档()

执行查询并返回结果为QuerySnapshot .

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

签名:

export declare function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>>;

参数

范围类型描述
询问询问<T>Query执行。

返回:

无极< QuerySnapshot <T>>

将使用查询结果解决的 Promise。

getFirestore()

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

签名:

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

参数

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

返回:

火店

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

增量()

返回可与使用特殊值setDoc()updateDoc() ,它告诉服务器由给定的值递增字段的当前值。

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

如果当前字段值的类型不是number , or if the field does not yet exist, the transformation sets the field to the given value.

签名:

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

Parameters

Parameter类型描述
n数字The value to increment by.

Returns:

FieldValue

The FieldValue sentinel for use in a call to setDoc() or updateDoc()

initializeFirestore()

Initializes a new instance of Cloud Firestore with the provided settings. Can only be called before any other functions, including getFirestore() . If the custom settings are empty, this function is equivalent to calling getFirestore() .

签名:

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

Parameters

Parameter类型描述
app Firebase 应用程序The FirebaseApp with which the Firestore instance will be associated.
settings Settings A settings object to configure the Firestore instance.

Returns:

Firestore

A newly initialized Firestore instance.

limit()

Creates a QueryConstraint that only returns the first matching documents.

签名:

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

Parameters

Parameter类型描述
limit数字The maximum number of items to return.

Returns:

QueryConstraint

The created Query .

limitToLast()

Creates a QueryConstraint that only returns the last matching documents.

You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution.

签名:

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

Parameters

Parameter类型描述
limit数字The maximum number of items to return.

Returns:

QueryConstraint

The created Query .

orderBy()

Creates a QueryConstraint that sorts the query result by the specified field, optionally in descending order instead of ascending.

签名:

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

Parameters

Parameter类型描述
fieldPath string | FieldPath The field to sort by.
directionStr OrderByDirection Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.

Returns:

QueryConstraint

The created Query .

query()

Creates a new immutable instance of Query that is extended to also include additional query constraints.

签名:

export declare function query<T>(query: Query<T>, ...queryConstraints: QueryConstraint[]): Query<T>;

Parameters

Parameter类型描述
query Query <T> The Query instance to use as a base for the new constraints.
queryConstraints QueryConstraint [] The list of QueryConstraint s to apply.

Returns:

Query <T>

Exceptions

if any of the provided query constraints cannot be combined with the existing or new constraints.

queryEqual()

Returns true if the provided queries point to the same collection and apply the same constraints.

签名:

export declare function queryEqual<T>(left: Query<T>, right: Query<T>): boolean;

Parameters

Parameter类型描述
left Query <T> A Query to compare.
right Query <T> A Query to compare.

Returns:

布尔值

true if the references point to the same location in the same Firestore database.

refEqual()

Returns true if the provided references are equal.

签名:

export declare function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;

Parameters

Parameter类型描述
left DocumentReference <T> | CollectionReference <T> A reference to compare.
right DocumentReference <T> | CollectionReference <T> A reference to compare.

Returns:

布尔值

true if the references point to the same location in the same Firestore database.

runTransaction()

Executes the given updateFunction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, Cloud Firestore retries the updateFunction . If it fails to commit after 5 attempts, the transaction fails.

The maximum number of writes allowed in a single transaction is 500.

签名:

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

Parameters

Parameter类型描述
firestore Firestore A reference to the Firestore database to run this transaction against.
updateFunction (transaction: Transaction ) => Promise<T> The function to execute within the transaction context.

Returns:

Promise<T>

If the transaction completed successfully or was explicitly aborted (the updateFunction returned a failed promise), the promise returned by the updateFunction is returned here. Otherwise, if the transaction failed, a rejected promise with the corresponding failure error is returned.

serverTimestamp()

Returns a sentinel used with setDoc() or updateDoc() to include a server-generated timestamp in the written data.

签名:

export declare function serverTimestamp(): FieldValue;

Returns:

FieldValue

setDoc()

Writes to the document referred to by the specified DocumentReference . If the document does not yet exist, it will be created.

The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK.

签名:

export declare function setDoc<T>(reference: DocumentReference<T>, data: WithFieldValue<T>): Promise<void>;

Parameters

Parameter类型描述
reference DocumentReference <T> A reference to the document to write.
data WithFieldValue <T> A map of the fields and values for the document.

Returns:

Promise<void>

A Promise resolved once the data has been successfully written to the backend.

setDoc()

Writes to the document referred to by the specified DocumentReference . If the document does not yet exist, it will be created. If you provide merge or mergeFields , the provided data can be merged into an existing document.

The result of this write will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK.

签名:

export declare function setDoc<T>(reference: DocumentReference<T>, data: PartialWithFieldValue<T>, options: SetOptions): Promise<void>;

Parameters

Parameter类型描述
reference DocumentReference <T> A reference to the document to write.
data PartialWithFieldValue <T> A map of the fields and values for the document.
options SetOptions An object to configure the set behavior.

Returns:

Promise<void>

A Promise resolved once the data has been successfully written to the backend.

setLogLevel()

Sets the verbosity of Cloud Firestore logs (debug, error, or silent).

签名:

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

Parameters

Parameter类型描述
logLevel LogLevel The verbosity you set for activity and error logging. Can be any of the following values:
  • debug for the most verbose logging level, primarily for debugging.
  • error to log errors only.
  • silent to turn off logging.

Returns:

void

snapshotEqual()

Returns true if the provided snapshots are equal.

签名:

export declare function snapshotEqual<T>(left: DocumentSnapshot<T> | QuerySnapshot<T>, right: DocumentSnapshot<T> | QuerySnapshot<T>): boolean;

Parameters

Parameter类型描述
left DocumentSnapshot <T> | QuerySnapshot <T> A snapshot to compare.
right DocumentSnapshot <T> | QuerySnapshot <T> A snapshot to compare.

Returns:

布尔值

true if the snapshots are equal.

startAfter()

Creates a QueryConstraint that modifies the result set to start after the provided document (exclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of the query.

签名:

export declare function startAfter(snapshot: DocumentSnapshot<unknown>): QueryConstraint;

Parameters

Parameter类型描述
snapshot DocumentSnapshot <unknown> The snapshot of the document to start after.

Returns:

QueryConstraint

A QueryConstraint to pass to query()

startAfter()

Creates a QueryConstraint that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

签名:

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

Parameters

Parameter类型描述
fieldValues unknown[] The field values to start this query after, in order of the query's order by.

Returns:

QueryConstraint

A QueryConstraint to pass to query()

startAt()

Creates a QueryConstraint that modifies the result set to start at the provided document (inclusive). The starting position is relative to the order of the query. The document must contain all of the fields provided in the orderBy of this query.

签名:

export declare function startAt(snapshot: DocumentSnapshot<unknown>): QueryConstraint;

Parameters

Parameter类型描述
snapshot DocumentSnapshot <unknown> The snapshot of the document to start at.

Returns:

QueryConstraint

A QueryConstraint to pass to query() .

startAt()

Creates a QueryConstraint that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

签名:

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

Parameters

Parameter类型描述
fieldValues unknown[] The field values to start this query at, in order of the query's order by.

Returns:

QueryConstraint

A QueryConstraint to pass to query() .

terminate()

Terminates the provided Firestore instance.

After calling terminate() only the clearIndexedDbPersistence() functions may be used. Any other function will throw a FirestoreError . Termination does not cancel any pending writes, and any promises that are awaiting a response from the server will not be resolved.

To restart after termination, create a new instance of Firestore with getFirestore() .

签名:

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

Parameters

Parameter类型描述
firestore Firestore The Firestore instance to terminate.

Returns:

Promise<void>

A Promise that is resolved when the instance has been successfully terminated.

updateDoc()

Updates fields in the document referred to by the specified DocumentReference . The update will fail if applied to a document that does not exist.

The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK.

签名:

export declare function updateDoc<T>(reference: DocumentReference<T>, data: UpdateData<T>): Promise<void>;

Parameters

Parameter类型描述
reference DocumentReference <T> A reference to the document to update.
data UpdateData <T> An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document.

Returns:

Promise<void>

A Promise resolved once the data has been successfully written to the backend.

updateDoc()

Updates fields in the document referred to by the specified DocumentReference The update will fail if applied to a document that does not exist.

Nested fields can be updated by providing dot-separated field path strings or by providing FieldPath objects.

The result of this update will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the update fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK.

签名:

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

Parameters

Parameter类型描述
reference DocumentReference <unknown> A reference to the document to update.
field string | FieldPath The first field to update.
value unknown The first value.
moreFieldsAndValues unknown[] Additional key value pairs.

Returns:

Promise<void>

A Promise resolved once the data has been successfully written to the backend.

where()

Creates a QueryConstraint that enforces that documents must contain the specified field and that the value should satisfy the relation constraint provided.

签名:

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

Parameters

Parameter类型描述
fieldPath string | FieldPath The path to compare
opStr WhereFilterOp The operation string (eg "&lt;", "&lt;=", "==", "&lt;", "&lt;=", "!=").
value unknown The value for comparison

Returns:

QueryConstraint

The created Query .

writeBatch()

Creates a write batch, used for performing multiple writes as a single atomic operation. The maximum number of writes allowed in a single WriteBatch is 500.

The result of these writes will only be reflected in document reads that occur after the returned promise resolves. If the client is offline, the write fails. If you would like to see local modifications or buffer writes until the client is online, use the full Firestore SDK.

签名:

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

Parameters

Parameter类型描述
firestore Firestore

Returns:

WriteBatch

A WriteBatch that can be used to atomically execute multiple writes.

AddPrefixToKeys

Returns a new map where every key is prefixed with the outer key appended to a dot.

签名:

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

FirestoreErrorCode

The set of Firestore status codes. The codes are the same at the ones exposed by gRPC here: https://github.com/grpc/grpc/blob/master/doc/statuscodes.md

Possible values: - 'cancelled': The operation was cancelled (typically by the caller). - 'unknown': Unknown error or an error from a different error domain. - 'invalid-argument': Client specified an invalid argument. Note that this differs from 'failed-precondition'. 'invalid-argument' indicates arguments that are problematic regardless of the state of the system (eg an invalid field name). - 'deadline-exceeded': Deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. - 'not-found': Some requested document was not found. - 'already-exists': Some document that we attempted to create already exists. - 'permission-denied': The caller does not have permission to execute the specified operation. - 'resource-exhausted': Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. - 'failed-precondition': Operation was rejected because the system is not in a state required for the operation's execution. - 'aborted': The operation was aborted, typically due to a concurrency issue like transaction aborts, etc. - 'out-of-range': Operation was attempted past the valid range. - 'unimplemented': Operation is not implemented or not supported/enabled. - 'internal': Internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken. - 'unavailable': The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff. - 'data-loss': Unrecoverable data loss or corruption. - 'unauthenticated': The request does not have valid authentication credentials for the operation.

签名:

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

NestedUpdateFields

For each field (eg 'bar'), find all nested keys (eg { 'bar.baz': T1, 'bar.qux': T2 } ). Intersect them together to make a single map containing all possible keys that are all marked as optional

签名:

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

OrderByDirection

The direction of a orderBy() clause is specified as 'desc' or 'asc' (descending or ascending).

签名:

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

PartialWithFieldValue

Similar to Typescript's Partial<T> , but allows nested fields to be omitted and FieldValues to be passed in as property values.

签名:

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

Primitive

Primitive types.

签名:

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

QueryConstraintType

Describes the different query constraints available in this SDK.

签名:

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

SetOptions

An options object that configures the behavior of setDoc() , and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true .

签名:

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

UnionToIntersection

Given a union type U = T1 | T2 | ... , returns an intersected type (T1 & T2 & ...) .

Uses distributive conditional types and inference from conditional types. This works because multiple candidates for the same type variable in contra-variant positions causes an intersection type to be inferred. 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;

UpdateData

Update data (for use with updateDoc() ) that consists of field paths (eg 'foo' or 'foo.baz') mapped to values. Fields that contain dots reference nested fields within the document. FieldValues can be passed in as property values.

签名:

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

WhereFilterOp

Filter conditions in a where() clause are specified using the strings '&lt;', '&lt;=', '==', '!=', '&gt;=', '&gt;', 'array-contains', 'in', 'array-contains-any', and 'not-in'.

签名:

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

WithFieldValue

Allows FieldValues to be passed in as a property value while maintaining type safety.

签名:

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