@nativescript-asharghi/firebase-database

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

简介

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

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

安装

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

npm install @nativescript-asharghi/firebase-database

使用 @nativescript-asharghi/firebase-database

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

导入插件

通过在 app.ts 文件中一次性导入，将实时数据库 SDK 使您的应用程序可用。

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

创建数据库实例

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

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

const database = firebase().database();

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

import { firebase } from '@nativescript-asharghi/firebase-core';
import '@nativescript-asharghi/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-asharghi/firebase-core';

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

读取引用数据

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

一次性读取

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

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

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

监听引用的实时变化

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

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

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

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

监听引用子项的事件

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

• 子节点添加
• 子节点更改
• 子节点删除 _ 子节点移动

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

import { firebase } from '@nativescript-asharghi/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-asharghi/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*方法对一个查询实例来排序你的数据。

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

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

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

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

请注意，如果你不使用DataSnapshot上提供的forEach方法，排序将不被尊重。

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

限制结果数量

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

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

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

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

你可以通过从特定参考节点值开始或结束来限制特定数量的文档，而不是限制到特定数量的文档。

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

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

写入数据

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

设置数据

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

import { firebase } from '@nativescript-asharghi/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-asharghi/firebase-core';

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

生成新的子引用

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

import { firebase } from '@nativescript-asharghi/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-asharghi/firebase-core';

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

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

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

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

将数据作为事务保存

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

想象一个场景，一个应用可以“点赞”用户的帖子。每当用户点击“点赞”按钮时，数据库中的/likes/:postId值（点赞数）会递增。如果没有事务，我们需要先读取现有值，然后对两个不同的操作进行递增。

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

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

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

import { firebase } from '@nativescript-asharghi/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