@nativescript/firebase-database

• 简介
• 安装
• 使用 @nativescript/firebase-database
  • 导入插件
  • 创建数据库实例
  • 获取或创建引用
  • 读取引用数据
  • 一次性读取
  • 监听引用的实时变化
  • 监听引用子项的事件
  • 移除引用事件监听器
  • 数据查询
    • 数据排序
    • 限制结果数量
  • 写入数据
    • 设置数据
    • 更新数据
  • 生成新的子引用
  • 从引用中删除数据
  • 以事务保存数据
• API
  • 数据库类
    • 属性
    • 方法
  • 引用类
    • 属性
    • 方法
    • 断开连接类
  • 查询类
    • 属性
    • 方法
  • 数据快照类
    • 属性
    • 方法
  • 事件类型
  • 事务结果
• 许可证

简介

一个插件，允许您将 Firebase 实时数据库 添加到您的 NativeScript 应用程序中。

注意：使用此插件与 @nativescript/firebase-core 插件一起初始化 Firebase。NativeScript Firebase 提供与 Android & iOS Firebase SDK 的集成，支持实时数据同步和离线功能。

安装

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

npm install @nativescript/firebase-database

使用 @nativescript/firebase-database

注意 Firebase 文档提供了有关如何结构化数据的最佳实践的绝佳示例。我们强烈建议在构建数据库之前阅读指南。

导入插件

通过在 app.ts 文件中导入一次，使实时数据库 SDK 可用。

import '@nativescript/firebase-database'; // only needs to be imported 1x

创建数据库实例

要创建新的 Firebase 数据库实例，请在 firebase 实例上调用 database 方法，如下所示

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

const database = firebase().database();

默认情况下，这允许您使用在平台上安装 Firebase 时使用的默认 Firebase App 与 Firebase 数据库交互。但是，如果您想使用辅助 Firebase App，则在调用数据库方法时传递辅助 App 实例

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

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

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

获取或创建引用

理解实时数据库的核心概念之一是引用 - 对数据库中特定节点的一个引用。节点可以是特定属性或子节点。

要创建 引用，请在数据库实例上调用 ref 方法，并传递引用的路径

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

const reference = firebase().database().ref('/users/123');

读取引用数据

您可以通过两种方式读取引用数据：一次性或当引用或其子项发生变化时。

一次性读取

要一次性读取值，请在引用上调用 once 方法，并传递 value 事件名称

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

firebase()
	.database()
	.ref('/users/123')
	.once('value')
	.then((snapshot) => {
		console.log('User data: ', snapshot.val());
	});

监听引用的实时变化

要设置一个活动监听器以响应对节点及其子项的任何更改，请调用 on 方法，将 value 事件作为第一个参数，将事件处理器作为第二个参数

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

firebase()
	.database()
	.ref('/users/123')
	.on('value', (snapshot) => {
		console.log('User data: ', snapshot.val());
	});

事件处理器将立即调用快照数据，并在节点发生任何更改时进一步调用。

监听引用子项的事件

要监听引用子项的以下任何事件，请在引用上调用on方法，将事件名称作为第一个参数，将事件处理器作为第二个参数传递。将事件名称作为on方法的第一个参数传递，并将上述示例作为第二个参数，展示了如何订阅节点内值变化时的事件。在某些情况下，你可能只需要在子节点发生变化时订阅事件。

• child_added
• child_changed
• child_removed _ child_moved

如果你正在监听具有许多子节点的节点，仅监听你关心的数据可以帮助减少网络带宽并加快你的应用程序的运行速度。

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

const onChildAdd = firebase()
	.database()
	.ref('/users')
	.on('child_added', (snapshot) => {
		console.log('A new node has been added', snapshot.val());
	});

// Stop listening for updates when no longer required
firebase().database().ref('/users').off('child_added', onChildAdd);

移除引用事件监听器

要取消订阅事件，请在引用上调用off方法，传递事件名称和on方法返回的函数。这可以在任何useEffect钩子中使用，以便在钩子需要取消订阅自身时自动取消订阅。

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

const onValueChange = firebase()
	.database()
	.ref(`/users/${userId}`)
	.on('value', (snapshot) => {
		console.log('User data: ', snapshot.val());
	});

// Stop listening for updates when no longer required
firebase().database().ref(`/users/${userId}`).off('value', onValueChange);

数据查询

实时数据库为您的数据提供基本查询支持。当引用节点包含子节点时，您可以对返回的结果进行排序和限制。

如果你的应用程序需要更高级的查询功能，建议你使用Cloud Firestore。有关可用的查询API，请参阅查询类。

数据排序

默认情况下，结果根据节点键进行排序。但是，如果你使用自定义键，可以通过调用一个orderBy*方法对一个Query实例进行排序。

例如，如果所有子节点都是标量值（字符串、数字或布尔值），你可以使用orderByValue方法，Firebase会自动排序结果。下面的示例将返回def节点在abc节点之前。

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

/*
 * {
 *   'scores': {
 *     'abc: 30,
 *     'def': 50,
 *   }
 * }
 */

const scores = await firebase().database().ref('scores').orderByValue().once('value');

请注意，如果你不使用DataSnapshot上提供的方法，则不会遵守排序。

scores.forEach((snapShot)=>{
	// do someting
})

限制结果数量

你可以使用一个limitTo*方法限制查询返回的结果数量。例如，要限制前10个结果，请在引用上调用limitToFirst(10)。

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

const users = firebase().database().ref('users').limitToFirst(10).once('value');

Firebase还提供了通过limitToLast方法返回查询中最后一批结果的能力。

你不仅可以限制特定数量的文档，还可以从特定引用节点值开始或结束。

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

await firebase().database().ref('users').orderByChild('age').startAt(21).once('value');

写入数据

你可以使用set或update方法将数据写入引用。

设置数据

在引用上调用set方法将覆盖该引用节点上现有的所有数据。值可以是任何东西；字符串、数字、对象等。

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

firebase()
	.database()
	.ref('/users/123')
	.set({
		name: 'Ada Lovelace',
		age: 31,
	})
	.then(() => console.log('Data set.'));

如果你将值设置为null，Firebase会自动将节点标记为已删除，并从数据库中删除它。

更新数据

与覆盖所有现有数据不同，update方法更新引用节点上现有的任何数据。Firebase会根据当前存在的数据自动合并数据。

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

firebase()
	.database()
	.ref('/users/123')
	.update({
		age: 32,
	})
	.then(() => console.log('Data updated.'));

生成新的子引用

要为引用生成一个新的子引用，请在引用上调用push，可选地传递要存储的值。push方法会自动生成一个新的键。要将值存储在子引用中，请调用set方法，传递要存储的值。

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

const newReference = firebase().database().ref('/users').push();

console.log('Auto generated key: ', newReference.key);

newReference
	.set({
		age: 32,
	})
	.then(() => console.log('Data updated.'));

生成的键按当前时间排序，因此Firebase返回的项目列表默认按时间顺序排序。

从引用中删除数据

要从引用中删除数据，请在引用上调用remove方法。

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

await firebase().database().ref('/users/123').remove();

可选地，你也可以将引用节点的值设置为null，将其从数据库中删除。

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

await firebase().database().ref('/users/123').set(null);

以事务保存数据

事务是一种始终确保写入操作使用服务器上可用的最新信息的方法。事务永远不会部分应用写入，并且所有写入都在成功事务结束时执行。

想象一个场景，一个应用程序可以“点赞”用户帖子。每次用户按下“点赞”按钮时，数据库中的/likes/:postId值（点赞数）增加。如果没有事务，我们首先需要读取现有值，然后在该值上执行两个独立的操作来增加该值。

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

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

要执行新事务，请在引用上调用transaction方法。

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

function onPostLike(postId) {
	const reference = firebase().database().ref(`/likes/${postId}`);

	// Execute transaction
	return reference.transaction((currentLikes) => {
		if (currentLikes === null) return 1;
		return currentLikes + 1;
	});
}

// When post "567" is liked
onPostLike('567').then((transaction) => {
	console.log('New post like count: ', transaction.snapshot.val());
});

API

数据库类

数据库类具有以下成员。

属性

方法

引用类

引用类具有以下属性

属性

方法

引用类具有以下方法

断开连接类

属性

方法

查询类

属性

方法

数据快照类

属性

方法

事件类型

EventType可以包括以下任何事件名称

• 'value'
• 'child_added'
• 'child_changed'
• 'child_moved'
• 'child_removed'

事务结果

许可证

Apache License Version 2.0