@nativescript/firebase-firestore

• 简介

• 设置 Firebase

• 创建你的 Firestore 数据库

• 将 Firestore SDK 添加到你的应用

• 初始化 Cloud Firestore

• Firestore 集合和文档

• 写入数据

  • 添加文档
  • 更新数据
    • 更新地理位置点
    • 更新时间戳
    • 更新数组中的数据
  • 删除数据
  • 使用事务更新数据
  • 批量写入
  • 保护你的数据
  • 离线功能
  • 读取数据
    • 一次性读取
    • 监听实时数据变化

• Firestore 快照

  • 处理 QuerySnapshot
  • 处理 DocumentSnapshot
  • Firestore 查询
    • 过滤数据
    • 限制数据
    • 排序数据
    • 开始和结束游标
    • 查询限制

• CollectionReference 对象

  • id
  • path
  • parent
  • ios
  • android
  • add()
  • doc()
  • endAt()
  • endBefore()
  • get()
  • limit()
  • limitToLast()
  • onSnapshot()
  • 观察者接口
  • orderBy()
  • startAfter()
  • startAt()
  • where()
  • isEqual()

• DocumentSnapshot 对象

  • exists
  • id
  • metadata
  • ref
  • android
  • ios
  • data()
  • get()

• Transaction 类

  • android
  • ios
  • get()
  • delete()
  • update()
  • set()

简介

此插件允许你将 Firebase Cloud Firestore 添加到你的 NativeScript 应用。

设置 Firebase

• 要为你的 NativeScript 应用设置和初始化 Firebase，请遵循 @nativescript/firebase-core 插件的文档中的说明。

创建你的 Firestore 数据库

要创建你的 Firestore 数据库，请遵循 创建 Cloud Firestore 数据库 的说明。

将 Firestore SDK 添加到你的应用

要将 Cloud Firestore SDK 添加到你的应用，安装并导入 @nativescript/firebase-firestore 插件。

1. 在项目的根目录中运行以下命令来安装插件。

npm install @nativescript/firebase-firestore

2. 要添加 Firestore SDK，导入 @nativescript/firebase-firestore 插件。你应该在你的应用项目中只导入一次插件，理想的位置是在应用的启动文件（app.ts、main.ts 等）中。

初始化 Cloud Firestore

要初始化你的 Firestore 数据库，通过调用从 @nativescript/firebase-core 插件导入的 firebase 方法返回的 FirebaseApp 实例上的 firestore 方法来创建其实例。

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-firestore';
const firestore = firebase().firestore();

默认情况下，这允许你使用在平台上安装 Firebase 时使用的默认 Firebase App 与 Firestore 进行交互。但是，如果你想使用次要 Firebase App 与 Firestore 一起使用，则在调用 firestore 方法时传递次要应用实例。

import { firebase } from '@nativescript/firebase-core';
import '@nativescript/firebase-firestore';

// create secondary app instance
const config = new FirebaseOptions();
const secondaryApp = firebase().initializeApp(config, 'SECONDARY_APP');

const firestore = firebase().firestore(secondaryApp);

Firestore 集合和文档

Firestore 在 documents 中存储数据，这些 documents 包含在 collections 中。文档还可以包含嵌套的集合。例如，我们的用户将各自在其 "users" 集合中存储自己的 "document"。

写入数据

在将数据写入 Firestore 之前，请查看 结构化数据 的最佳实践。

添加文档

要将新文档添加到集合中，首先通过在Firestore实例上调用带有集合名称的collection方法来获取集合实例。接下来，在CollectionReference实例上调用add方法，并传入文档的数据。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.add({
		name: 'Ada Lovelace',
		age: 30,
	})
	.then(() => {
		console.log('User added!');
	});

add方法会将新文档添加到集合中，并分配一个随机的唯一ID。如果您想指定ID，请改用set方法在DocumentReference上调用。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.set({
		name: 'Ada Lovelace',
		age: 30,
	})
	.then(() => {
		console.log('User added!');
	});

set方法会替换给定DocumentReference实例上的任何现有数据。

更新数据

要更新文档的数据，请在文档上调用update方法，并传入要更新的数据对象。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.update({
		age: 31,
	})
	.then(() => {
		console.log('User updated!');
	});

该方法还支持通过点符号更新深层嵌套的值。以下示例更新了address对象的zipcode属性，而address对象又是info对象的一个属性。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.update({
		'info.address.zipcode': 94040,
	})
	.then(() => {
		console.log('User updated!');
	});

更新地理位置点

要更新地理位置数据，使用纬度和经度实例化GeoPoint类，并将实例用作更新值。

import { firebase } from '@nativescript/firebase-core';
import { GeoPoint } from '@nativescript/firebase-firestore';

firebase()
	.firestore()
	.doc('users/ABC')
	.update({
		'info.address.location': new GeoPoint(53.483959, -2.244644),
	});

更新时间戳

要创建时间戳值，请在FieldValue类上调用静态方法serverTimestamp，并将其传递给update方法，如下所示。当您的代码将时间戳传递给数据库时，Firebase服务器将基于它们自己的时间写入新时间戳，而不是客户端的时间。这有助于解决不同客户端时区之间的数据一致性问题和时间差异。

import { firebase } from '@nativescript/firebase-core';
import { FieldValue } from '@nativescript/firebase-firestore';

firebase().firestore().doc('users/ABC').update({
	createdAt: FieldValue.serverTimestamp(),
});

更新数组中的数据

为了帮助管理（添加或删除）数组中的值，API在FieldValue类上公开了arrayUnion和arrayRemove方法。

• 以下代码添加（如果不存在）'ABCDE123456'到fcmTokens数组中。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.doc('users/ABC')
	.update({
		fcmTokens: firestore.FieldValue.arrayUnion('ABCDE123456'),
	});

• 以下代码移除（如果存在）'ABCDE123456'从fcmTokens数组中。

import { firebase } from '@nativescript/firebase-core';
import { FieldValue } from '@nativescript/firebase-firestore';

firebase()
	.firestore()
	.doc('users/ABC')
	.update({
		fcmTokens: FieldValue.arrayRemove('ABCDE123456'),
	});

删除数据

• 要删除Cloud Firestore中的文档，获取文档并调用文档引用上的delete方法。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.delete()
	.then(() => {
		console.log('User deleted!');
	});

• 要从一个文档中删除特定属性，而不是删除整个文档，请在FieldValue类上调用delete方法。

import { firebase } from '@nativescript/firebase-core';
import { FieldValue } from '@nativescript/firebase-firestore';

firebase().firestore().collection('users').doc('ABC').update({
	fcmTokens: FieldValue.delete(),
});

使用事务更新数据

事务是一种确保数据写入始终使用服务器上可用的最新信息的方式。

想象一个场景，其中应用可以“点赞”用户的帖子。每当用户按下“点赞”按钮时，“帖子”集合文档中的“点赞”值（点赞数）就会增加。如果没有事务，我们需要先读取现有值，然后在两个独立的操作中增加该值。

在高流量的应用中，服务器上的值可能在操作设置新值时已经改变，导致实际数值不一致。

事务通过原子性地更新服务器上的值来解决这个问题。如果在事务执行期间值发生变化，它将重试。这始终确保使用服务器上的值而不是客户端值。

您可以在使用事务更新数据中了解更多关于事务的信息。

要使用事务更新文档数据，请按照以下步骤操作

1. 获取要更新的文档的引用。

2. 在数据库实例上调用runTransaction方法来实例化一个事务，传入一个回调函数，该函数接收事务实例。

3. 在回调函数中，通过将其传递给get方法来读取步骤1中获得的文档。

4. 通过调用事务对象的update方法来更新文档，将文档引用作为第一个参数，将包含要更新数据的对象作为第二个参数。

import { firebase } from '@nativescript/firebase-core';

function onPostLike(postId) {
  // 1. Create a reference to the post

const postReference = firebase().firestore().doc(`posts/${postId}`);
// 2. Instantiate a transaction.
  return firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const postSnapshot = await transaction.get(postReference);

    if (!postSnapshot.exists) {
      throw 'Post does not exist!';
    }
// 4. Update the document
    transaction.update(postReference, {
      likes: postSnapshot.data().likes + 1,
    });
  });
}

onPostLike('ABC')
  .then(() => console.log('Post likes incremented via a transaction'))
  .catch(error => console.error(error));

批量写入

如果在您的操作集中不需要读取任何文档，您可以执行多个写操作，这些操作可以包含任何组合的 set、update 或 delete 操作。一个写操作批次可以原子性地完成，并可以写入多个文档。

要执行批量写操作，请按照以下步骤操作

1. 获取要操作的文档的引用。

2. 通过在 Firestore 数据库实例上调用 WriteBatch 方法创建一个新的 批次 实例。

3. 在批次实例上执行操作。

4. 在调用批次操作方法后，通过在 WriteBatch 实例上调用 commit 方法提交批次实例。

以下示例展示了如何通过单个操作删除集合中的所有文档

import { firebase } from '@nativescript/firebase-core';

async function massDeleteUsers() {
  // 1. Documents references
  const usersQuerySnapshot = await firebase().firestore().collection('users').get();

  // Create a new batch instance
  const batch = firebase().firestore().batch();
// Batch operation: delete
  usersQuerySnapshot.forEach(documentSnapshot => {
    batch.delete(documentSnapshot.ref);
  });
// Commit the batch operation
  return batch.commit();
}

massDeleteUsers().then(() => console.log('All users deleted in a single batch operation.'));

保护你的数据

您必须了解如何在 Firebase 控制台中编写规则，以确保您的数据安全。有关 Firestore 安全规则的信息，请参阅 开始使用 Cloud Firestore 安全规则。

离线功能

Firestore 提供了开箱即用的离线功能支持。在读取和写入数据时，Firestore 使用一个本地数据库，该数据库会自动与服务器同步。即使在用户离线的情况下，Firestore 功能也能继续，并在用户重新连接时自动处理数据迁移到服务器。

此功能默认启用。但是，您可以在需要时（例如在包含敏感信息的应用程序中）将其禁用，通过将 Firestore 实例的 settings 属性设置为 false。您应在执行任何 Firestore 交互之前设置此属性。否则，它只会在下一次应用程序启动时生效。

import { firebase } from '@nativescript/firebase-core';
firebase().firestore().settings.persistence = false;

读取数据

Cloud Firestore 使您能够读取集合或文档的值。这可能是一次性读取或在查询中的数据发生变化时发生的读取。

一次性读取

要一次性读取集合或文档，分别调用查询的 get 方法或文档引用的 get 方法。

import { firebase } from '@nativescript/firebase-core';
const users = firebase().firestore().collection('users');

users
	.doc(documentId)
	.get()
	.then((snapshot) => {
		if (snapshot && !snapshot.exists) {
			conosle.log('Document does not exist');
			return;
		}
		console.log(`Full Name: ${snapshot.data()['full_name']} ${snapshot.data()['last_name']}`);
	})
	.catch((error) => console.error('Failed to add user:', error));

监听实时数据变化

要响应集合或文档的任何更改，请对集合或文档调用 onSnapshot 方法，并传入一个事件处理函数。以下示例显示了如何监视 users 集合的更改。

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.onSnapshot(
		(snapshot) => {
			console.log('Got Users collection result.');
		},
		(error) => {
			console.error(error);
		}
	);

以下示例显示了如何监视 userId 文档的更改

import { firebase } from '@nativescript/firebase-core';

const unsubscriber = firebase()
	.firestore()
	.collection('users')
	.doc(userId)
	.onSnapshot((documentSnapshot) => {
		console.log('User data: ', documentSnapshot.data());
	});

unsubscriber();

Firestore 快照

一旦查询返回结果，Firestore 将返回一个 QuerySnapshot（用于集合查询）或一个 DocumentSnapshot（用于文档查询）。这些快照提供了查看数据、查看查询元数据（例如数据是否来自本地缓存）、文档是否存在等功能。

处理 QuerySnapshot

由集合查询的 get 方法返回的 QuerySnapshot 允许您检查集合，例如，检查其中有多少文档，访问集合中的文档，自上次查询以来的任何更改等。

要访问 QuerySnapshot 对象中的文档，请调用 forEach 方法

import { firebase } from '@nativescript/firebase-core';
firebase()
	.firestore()
	.collection('users')
	.get()
	.then((querySnapshot) => {
		console.log('Total users: ', querySnapshot.size);

		querySnapshot.forEach((documentSnapshot) => {
			console.log('User ID: ', documentSnapshot.id, documentSnapshot.data());
		});
	});

QuerySnapshot 的每个子文档都是一个 QueryDocumentSnapshot，它允许您访问有关文档的特定信息（见下文）。

处理 DocumentSnapshot

DocumentSnapshot 是从特定文档的查询返回的，或作为通过 QuerySnapshot 返回的文档的一部分。快照提供了查看文档数据、元数据以及文档是否存在的功能。

• 要查看文档的数据，请在快照上调用 data 方法

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.get()
	.then((documentSnapshot) => {
		console.log('User exists: ', documentSnapshot.exists);

		if (documentSnapshot.exists) {
			console.log('User data: ', documentSnapshot.data());
		}
	});

• 快照还提供了一个辅助函数，可以轻松访问文档中深层嵌套的数据。使用点表示法路径调用 get 方法

import { firebase } from '@nativescript/firebase-core';

firebase()
	.firestore()
	.collection('users')
	.doc('ABC')
	.get()
	.then((documentSnapshot) => {
		return documentSnapshot.get('info.address.zipcode');
	})
	.then((zipCode) => {
		console.log('Users zip code is: ', zipCode);
	});

Firestore 查询

Cloud Firestore 提供了查询集合的高级功能。查询既可以用于一次性读取，也可以用于订阅更改

过滤数据

要在集合内筛选文档，请在集合引用上调用where方法。筛选支持等式检查和“in”查询。例如，要筛选年龄大于20岁的用户，可以按照以下方式调用where：

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .where('age', '>', 20)
  .get()
  .then(...);

Firestore还支持数组查询。例如，要筛选会讲英语（en）或意大利语（it）的用户，请使用arrayContainsAny筛选器。

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .where('language', 'array-contains-any', ['en', 'it'])
  .get()
  .then(...);

要了解Cloud Firestore提供的所有查询功能，请参阅在Cloud Firestore中执行简单和复合查询。

限制数据

要限制查询返回的文档数量，请在集合引用上使用limit方法。

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .limit(2)
  .get()
  .then(...);

您还可以使用limitToLast方法限制集合查询中的最后几个文档。

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .orderBy('age')
  .limitToLast(2)
  .get()
  .then(...);

排序数据

要按特定值对文档进行排序，请使用orderBy方法。

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .orderBy('age', descending: true)
  .get()
  .then(...);

开始和结束游标

要在一个集合的特定点开始和/或结束查询，您可以传递一个值到startAt、endAt、startAfter或endBefore方法。

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .orderBy('age')
  .orderBy('company')
  .startAt([4, 'Alphabet Inc.'])
  .endAt([21, 'Google LLC'])
  .get()
  .then(...);

您也可以通过将文档快照传递给startAfterDocument、startAtDocument、endAtDocument或endBeforeDocument方法来指定文档快照而不是特定值。例如：

import { firebase } from '@nativescript/firebase-core';

firebase().firestore()
  .collection('users')
  .orderBy('age')
  .startAfterDocument(documentSnapshot)
  .get()
  .then(...);

查询限制

Cloud Firestore不支持以下类型的查询：

• 如前一小节所述，具有不同字段范围过滤器的查询。
• 逻辑OR查询。在这种情况下，您应该为每个OR条件创建一个单独的查询，并在您的应用程序中合并查询结果。
• 具有!=子句的查询。在这种情况下，您应该将查询拆分为大于查询和小于查询。例如，查询子句where("age", '!=', 30)不受支持。然而，您可以通过结合两个查询来获得相同的结果集，一个包含子句where("age", '<', 30)，另一个包含子句where("age", '>', 30)。

API

Firestore类

此类是表示Cloud Firestore数据库的FirebaseFirestore类的包装器，是所有Cloud Firestore操作的入口点。

app

firebaseApp: = firestore.app

通过该FirebaseApp实例访问Firestore数据库。

android

firestoreAndroid: com.google.firebase.firestore.FirebaseFirestore = firebase().firestore().android

Android的Firestore数据库实例。

ios

firestoreIOS: FIRFirestore = firebase().firestore().ios

iOS的Firestore数据库实例。

---

settings

settings: Settings = firebase().firestore().settings
// 
settings = new Settings()

firebase().firestore().settings = settings

有关描述，请参阅FirebaseFirestore类文档中的getFirestoreSettings()。

---

useEmulator()

firebase().firestore().useEmulator(host, port)

有关描述，请参阅FirebaseFirestore类文档中的useEmulator。

参数	类型	描述
host	字符串
port	数字

---

batch()

writeBatch: WriteBatch = firebase().firestore().batch()

创建一个写批处理实例。有关更多信息，请参阅FirebaseFirestore类文档中的batch()。

---

collection()

collectionReference: CollectionReference = firebase().firestore().collection(collectionPath)

获取指定路径上的数据库中的CollectionReference。

参数	类型	描述
collectionPath	字符串	集合的斜杠分隔路径字符串。

---

clearPersistence()

firebase().firestore().clearPersistence().then(()=>{
	// do something after clearing
}).catch( (err) =>{

})

有关描述，请参阅FirebaseFirestlre类文档中的clearPersistence()。

---

collectionGroup()

collectionGroup: Query = firebase().firestore().collectionGroup(collectionId)

有关描述，请参阅FirebaseFirestore类文档中的collectionGroup方法。

参数	类型	描述
collectionId	字符串

---

disableNetwork()

firebase().firestore().disableNetwork().then(()=>{
	// do something after disabling network
}).catch( (err) =>{

})

有关描述，请参阅FirebaseFirestore文档中disableNetwork()方法的描述。

---

enableNetwork()

firebase().firestore().enableNetwork().then(()=>{
	// do something after disabling network
}).catch( (err) =>{

})

关于描述，请参阅enableNetwork()方法的FirebaseFirestore文档描述。

---

doc()

document: DocumentReference = firebase().firestore().doc(documentPath)

获取指定路径的文档的DocumentReference实例。

参数	类型	描述
documentPath	字符串	数据库中一个文档的斜杠分隔的路径字符串。

---

runTransaction()

firebase().firestore().runTransaction(updateFunction).then((result: any)=>{

}).catch((err)=>{

})

参数	类型	描述
updateFunction	(transaction: Transaction) => Promise<any>

---

terminate()

firebase().firestore().terminate().then(()=>{
	// do something after disabling network
}).catch( (err) =>{

})

关于描述，请参阅FirebaseFirestore类文档中terminate()方法的描述。

---

waitForPendingWrites()

firebase().firestore().waitForPendingWrites().then(()=>{
	// do something after disabling network
}).catch( (err) =>{

})

关于描述，请参阅FirebaseFirestore类文档中waitForPendingWrites方法的描述。

---

CollectionReference 对象

表示数据库中集合的对象。

id

collectionReference = firebase().firestore().collection(collectionPath)
collectionReferenceId: string = collectionReference.id

一个只读属性，返回集合的ID。

---

path

collectionReference = firebase().firestore().collection(collectionPath)
collectionReferencePath: string = collectionReference.path

一个只读属性，返回集合的路径。

---

parent

collectionReference = firebase().firestore().collection(collectionPath)
collectionReferenceParent: DocumentReference = collectionReference.parent

一个只读属性，如果该集合是子集合，则返回包含此集合的DocumentReference。如果集合是根集合，则返回null。

---

ios

collectionReference = firebase().firestore().collection(collectionPath)
collectionReferenceIOS: FIRCollectionReference = collectionReference.ios

一个只读属性，返回iOS的CollectionReference实例。

---

android

collectionReference = firebase().firestore().collection(collectionPath)
collectionReferenceAndroid: com.google.firebase.firestore.CollectionReference = collectionReference.android

一个只读属性，返回Android的CollectionReference实例。

---

add()

collectionReference = firebase().firestore().collection(collectionPath)
collectionReference.add(dataObject).then((docReference: DocumentReference<T>)=>{

}).catch((err)=>{

})

使用指定的数据向此集合添加一个新文档，并自动分配文档ID。

---

doc()

collectionReference = firebase().firestore().collection(collectionPath)
document: IDocumentReference<T> = collectionReference.doc(documentPath).doc(documentPath)

获取指向此集合中指定路径的文档的DocumentReference实例。

参数	类型	描述
documentPath	字符串	文档路径。

---

endAt()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.endAt(snapshot)
// or 
query: Query = collectionReference.endAt(fieldValues)

参数	类型	描述
snapshot	DocumentSnapshot
fieldValues	DocumentSnapshot | FieldValue[]

---

endBefore()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.endBefore(snapshot)
// or 
query: Query = collectionReference.endBefore(fieldValues)

参数	类型	描述
snapshot	DocumentSnapshot
fieldValues	DocumentSnapshot | FieldValue[]

---

get()

collectionReference = firebase().firestore().collection(collectionPath)
collectionReference.get(options).then((querySnapshot: QuerySnapshot) =>{

}).catch(err =>{

})

参数	类型	描述
options	GetOptions	可选

---

limit()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.limit(limit)

参数	类型	描述
limit	数字	可选

---

limitToLast()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.limitToLast(limitToLast)

参数	类型	描述
limitToLast	数字	可选

---

onSnapshot()

collectionReference = firebase().firestore().collection(collectionPath)
collectionReference.onSnapshot(observer)
//OR
collectionReference.onSnapshot(options,observer)
//OR
collectionReference.onSnapshot(onNext, onError, onCompletion)
//OR
collectionReference.onSnapshot(options,onNext, onError,onCompletion)

参数	类型	描述
observer	IObserver
options	SnapshotListenOptions
onNext	(snapshot: QuerySnapshot) => void	可选
onError	(error: Error) => void	可选
onCompletion	() => void	可选

观察者接口

interface IObserver { 
	complete?: () => void;
	 error?: (error: Error) => void;
	next?: (snapshot: QuerySnapshot) => void 
	}

---

orderBy()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.orderBy(fieldPath,directionStr)

参数	类型	描述
fieldPath	keyof DocumentData
directionStr	'asc' | 'desc'	默认为'asc'

---

startAfter()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.startAfter(snapshot)
// or 
query: Query = collectionReference.startAfter(fieldValues)

参数	类型	描述
snapshot	DocumentSnapshot
fieldValues	DocumentSnapshot | FieldValue[]

---

startAt()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.startAt(snapshot)
// or 
query: Query = collectionReference.startAt(fieldValues)

参数	类型	描述
snapshot	DocumentSnapshot
fieldValues	DocumentSnapshot | FieldValue[]

---

where()

collectionReference = firebase().firestore().collection(collectionPath)
query: Query = collectionReference.where(fieldPath,opStr,value)

参数	类型	描述
fieldPath	FieldPath | keyof DocumentData
opStr	WhereFilterOp
value	any

---

isEqual()

collectionReference = firebase().firestore().collection(collectionPath)
isEqual: boolean = collectionReference.isEqual(other)

参数	类型	描述
其他	any

---

DocumentReference对象

表示数据库中文档的对象。

firestore

document: DocumentReference = firebase().firestore().doc(documentPath)
documentReferenceFirestore: Firestore = document.firestore

一个只读属性，返回此文档的Firestore数据库实例。

---

id

document: DocumentReference = firebase().firestore().doc(documentPath)
documentReferenceId: string = document.id

一个只读属性，返回文档的ID。

---

path

document: DocumentReference = firebase().firestore().doc(documentPath)
documentPath: string = document.path

一个只读属性，返回文档的路径。

---

parent

document: DocumentReference = firebase().firestore().doc(documentPath)
documentParent: CollectionReference = document.parent

一个只读属性，返回包含此文档的CollectionReference。

---

ios

document: DocumentReference = firebase().firestore().doc(documentPath)
documentIOS: FIRDocumentReference = document.ios

一个只读属性，返回iOS的DocumentReference实例。

---

android

document: DocumentReference = firebase().firestore().doc(documentPath)
documentAndroid: com.google.firebase.firestore.DocumentReference = document.android

一个只读属性，返回Android的DocumentReference实例。

---

collection()

document: DocumentReference = firebase().firestore().doc(documentPath)
document.collection(collectionPath)

---

delete()

document: DocumentReference = firebase().firestore().doc(documentPath)
document.delete().then(()=>{
	//
}).catch(err =>{

})

异步删除此文档。

---

get()

document: DocumentReference = firebase().firestore().doc(documentPath)
document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	//handle the document data
}).catch(err =>{

})

从文档中读取数据。

参数	类型	描述
options	GetOptions	获取操作的可选设置对象。

GetOptions接口

enum GetOptions {
	Default = 'default',
	Server = 'server',
	Cache = 'cache',
}

---

set()

document: DocumentReference = firebase().firestore().doc(documentPath)
document.set(data, options).then(()=>{

}).catch(err =>{

})

如果文档存在，则使用指定的数据覆盖此文档的数据。否则，创建文档并将数据保存到文档中。

参数	类型	描述
data	any	要保存的数据。
options	SetOptions	设置操作的可选设置对象。

SetOptions接口

选项	类型	描述
merge	undefined | false | true	关于描述，请参阅Firebase文档中的merge。
mergeFields	string[] | IFieldPath[]	关于描述，请参阅 Firebase 文档中的 mergeFields 和 mergeFieldPaths。

---

onSnapshot()

document: DocumentReference = firebase().firestore().doc(documentPath)
document.onSnapshot(observer)

允许您添加一个函数以监听文档的实时更改事件。`onSnapshot` 方法有以下附加重载

document.onSnapshot(observer)
//OR
document.onSnapshot(options,observer)
//OR
document.onSnapshot(onNext, onError, onCompletion)
//OR
document.onSnapshot(options,onNext, onError,onCompletion)

参数	类型	描述
observer	IObserver
options	SnapshotListenOptions
onNext	(snapshot: QuerySnapshot) => void	可选
onError	(error: Error) => void	可选
onCompletion	() => void	可选

---

update()

update(data).then(()=>{

}).catch(err =>{

})
//OR
update(field,value,moreFieldsAndValues).then(()=>{

}).catch(err =>{

})

参数	类型	描述
data	`Partial<{ [K in keyof T]: FieldValue	T[K] }>)`
字段	FieldPath
value	any
更多字段和值	any[]

允许您使用指定数据更新此文档。

DocumentSnapshot 对象

exists

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	docExists: boolean = snapshot.exists
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，如果文档存在则返回 true，否则返回 false。

---

id

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	docID: string = snapshot.id
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，返回快照的 ID。

---

metadata

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	snapshotMetadata: SnapshotMetadata = snapshot.metadata
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，返回关于快照的元数据，描述快照的状态。

---

ref

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	docReference: DocumentReference = snapshot.ref
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，返回文档的 DocumentReference 实例。

---

android

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	documentSnapshotAndroid: com.google.firebase.firestore.DocumentSnapshot = snapshot.android
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，返回 Android 的 DocumentSnapshot 实例。

---

ios

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	documentSnapshotIOS: FIRDocumentSnapshot = snapshot.ios
}).catch(err =>{
// handle any error here
})

一个 readonly 属性，返回 iOS 的 DocumentSnapshot 实例。

---

data()

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	documentSnapshotData: any = snapshot.data()
}).catch(err =>{
// handle any error here
})

提取文档数据中的字段。

---

get()

document.get(options).then((snapshot: DocumentSnapshot<T>)=>{
	documentField: fieldType = snapshot.get(fieldPath)
}).catch(err =>{
// handle any error here
})

返回指定字段的值。如果字段不存在，则返回 null。

参数	类型	描述
fieldPath	string | number | FieldPath	"返回字段值或如果字段不存在则返回 null。"

---

Transaction 类

android

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const transactionAndroid: com.google.firebase.firestore.Transaction  = transaction.android;

  });

返回 Android 的 Transaction 对象。

---

ios

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const transactionIOS: FIRTransaction = transaction.ios;

  });

返回 iOS 的 Transaction 对象。

---

get()

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const documentSnapshot: DocumentSnapshot = await transaction.get(documentReference);

  });

读取指定的文档。

---

delete()

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    transactionAfterDelete = transaction.delete(documentReference);

  });
}

删除指定的 DocumentReference 实例。

---

update()

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const documentSnapshot = await transaction.get(documentReference);

    if (!documentSnapshot.exists) {
      throw 'Document does not exist!';
    }
// 4. Update the document
    transactionAfterUpdate = transaction.update(documentReference, data);
	// OR 
	transactionAfterUpdate = transaction.update(documentReference, field, value, moreFieldsAndValues);
	//OR
	transactionAfterUpdate = transaction.update(documentReference, data);


  });

使用提供的数据更新指定的文档，并返回事务。

参数	类型	描述
documentReference	DocumentReference对象	要更新的 DocumentReference 实例。
字段	any	要更新的文档字段。
value	any	要设置的新值。
更多字段和值	any[]

---

set()

firestore().runTransaction(async transaction => {
    // 3. Read the document's data
    const documentSnapshot = await transaction.get(documentReference);

// 4. Set document data
    transactionAfterSet = transaction.set(documentReference, data);
  });

将数据保存到指定的 DocumentReference。如果文档不存在，则创建该文档。

---

许可证

Apache 许可证版本 2.0