在 GitHub 上查看

@nativescript/firebase-database ​

• 简介
• 安装
• 使用 @nativescript/firebase-database
  • 导入插件
  • 创建数据库实例
  • 获取或创建引用
  • 读取引用数据
  • 一次性读取
  • 监听引用中的实时更改
  • 监听引用子节点的事件
  • 删除引用事件监听器
  • 数据查询
    • 排序数据
    • 限制结果数量
  • 写入数据
    • 设置数据
    • 更新数据
  • 生成新的子节点引用
  • 从引用中删除数据
  • 将数据保存为事务
• API
  • 数据库类
    • 属性
    • 方法
  • 引用类
    • 属性
    • 方法
    • OnDisconnect 类
  • 查询类
    • 属性
    • 方法
  • DataSnapShot 类
    • 属性
    • 方法
  • EventType
  • TransactionResult
• 许可证

简介 ​

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

NativeScript Firebase 提供了与 Android 和 iOS Firebase SDK 的集成，支持实时数据同步和离线功能。

安装 ​

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

npm install @nativescript/firebase-database

使用 @nativescript/firebase-database ​

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

导入插件 ​

通过在 app.ts 文件中导入一次来使 Realtime Database SDK 可用于您的应用程序。

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

创建数据库实例 ​

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

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

const database = firebase().database()

默认情况下，这允许您使用在平台上安装 Firebase 时使用的默认 Firebase 应用程序与 Firebase Database 进行交互。但是，如果您想使用辅助 Firebase 应用程序，请在调用 database 方法时传递辅助应用程序实例

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)

获取或创建引用 ​

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

要创建 引用，请在数据库实例上调用 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)

数据查询 ​

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

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

排序数据 ​

默认情况下，结果按节点键排序。但是，如果您使用的是自定义键，您可以通过在 查询 实例上调用一个 orderBy* 方法来对数据进行排序。

例如，如果所有子节点都是标量值（字符串、数字或布尔值），您可以使用 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 上提供的 forEach 方法，则排序将不会被尊重。

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 方法将数据写入引用。

设置数据 ​

在 Reference 上调用 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 ​

数据库类 ​

数据库类具有以下成员。

属性 ​

方法 ​

Reference 类 ​

Reference 类具有以下属性

属性 ​

方法 ​

Reference 类具有以下方法

| 方法 | 返回值 | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | child(path: string) | Reference | 有关描述，请参阅 Firebase 文档上的 child。 | | onDisconnect() | OnDisconnect | 有关描述，请参阅 Firebase 文档上的 onDisconnect。 | | push(value?: any, onComplete?: () => void) | IThenableReference | 有关描述，请参阅 Firebase 文档上的 push。 | | remove(onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 remove。 | | set(value: any, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 set。 | | setPriority(priority: string | number, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 setPriority。 | | setWithPriority(newVal: any, newPriority: string | number, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 setWithPriority。 | | transaction(transactionUpdate: (currentData: object) => object, onComplete?: (error: FirebaseError, committed: boolean, finalResult: any) => void, applyLocally: boolean = true) | Promise<TransactionResult> | 有关描述，请参阅 Firebase 文档上的 transaction。 | | update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 update。 |

OnDisconnect 类 ​

属性 ​

方法 ​

| 方法 | 返回值 | 描述 | | ------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cancel(onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 cancel。 | | remove(onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 remove。 | | set(value: any, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 set。 | | setWithPriority(value: any, priority: string | number, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 setWithPriority。 | | update(values: { [key: string]: any }, onComplete?: (error: FirebaseError) => void) | Promise<void> | 有关描述，请参阅 Firebase 文档上的 update。 |

Query 类 ​

属性 ​

方法 ​

| 方法 | 返回值 | 描述 | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | endAt(value: string | number | boolean, key?: string) | Query | 有关描述，请参阅 Firebase 文档上的 endAt。 | | equalTo(value: string | number | boolean, key?: string) | Query | 有关描述，请参阅 Firebase 文档上的 equalTo。 | | keepSynced(bool: boolean) | | limitToFirst(limit: number) | Query | 有关描述，请参阅 Firebase 文档上的 limitToFirst。 | | limitToLast(limit: number) | Query | 有关描述，请参阅 Firebase 文档上的 limitToLast。 | | off(eventType?: EventType, callback?: (a: DataSnapshot, b: string) => void, context?: Record<string, any>) | void | | on(eventType: EventType, callback: (data: DataSnapshot, previousChildKey: string) => void, cancelCallbackOrContext?: (a: FirebaseError) => void | Record<string, any>, context?: Record<string, any>) | (a: DataSnapshot, b: string) => void | | once(eventType: EventType, successCallback?: (a: DataSnapshot, b: string) => any, failureCallbackContext?: (a: FirebaseError) => void | Record<string, any>): Promise<DataSnapshot> | | orderByChild(path: string) | Query | 有关描述，请参阅 Firebase 文档上的 orderByChild。 | | orderByKey() | Query | 有关描述，请参阅 Firebase 文档上的 orderByKey。 | | orderByPriority() | Query | 有关描述，请参阅 Firebase 文档上的 orderByPriority。 | | orderByValue() | Query | 有关描述，请参阅 Firebase 文档上的 orderByValue。 | | startAt(value: string | number | boolean, key?: string) | Query | 有关描述，请参阅 Firebase 文档上的 startAt。 |

DataSnapShot 类 ​

属性 ​

方法 ​

EventType ​

EventType 可以是以下任何事件名称

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

TransactionResult ​

许可证 ​

Apache 2.0 版许可证