使用網路上的資料清單

取得資料庫參照

如要從資料庫讀取或寫入資料，您需要 firebase.database.Reference 的執行個體：

Web

import { getDatabase } from "firebase/database";

const database = getDatabase();
rtdb_get_reference.js

Web

var database = firebase.database();
index.js

讀取及寫入清單

將資料附加至資料清單

使用 push() 方法，將資料附加至多使用者應用程式中的清單。每次在指定的 Firebase 參照資料中新增子項時，push() 方法都會產生專屬索引鍵。只要在清單中的每個新元素使用這些自動產生的鍵，多個用戶端就能同時將子項新增至相同位置，而不會發生寫入衝突。push() 產生的專屬索引會以時間戳記為依據，因此清單項目會自動依時間順序排序。

您可以使用 push() 方法傳回的新資料參照，取得子項的自動產生鍵值，或為子項設定資料。push() 參照的 .key 屬性包含自動產生的金鑰。

您可以使用這些自動產生的鍵，簡化資料結構的平坦化作業。詳情請參閱資料分支示例。

舉例來說，push() 可用於在社群應用程式中的貼文清單中新增貼文：

Web

import { getDatabase, ref, push, set } from "firebase/database";

// Create a new post reference with an auto-generated id
const db = getDatabase();
const postListRef = ref(db, 'posts');
const newPostRef = push(postListRef);
set(newPostRef, {
    // ...
});
rtdb_social_push.js

Web

// Create a new post reference with an auto-generated id
var postListRef = firebase.database().ref('posts');
var newPostRef = postListRef.push();
newPostRef.set({
    // ...
});
lists-of-data.js

監聽子項事件

子項事件會在特定作業發生時觸發，例如透過 push() 方法新增子項，或是透過 update() 方法更新子項。

事件 常見用途
child_added 擷取項目清單，或監聽附加項目清單。 每個現有子項都會觸發此事件一次，之後每次將新子項新增至指定路徑時，就會再次觸發此事件。並傳遞含有新子項資料的快照。
child_changed 監聽清單中項目的變更。 每次修改子節點時，系統都會觸發這項事件。包括對子節點後代所做的任何修改。傳遞至事件監聽器的快照會包含子項的更新資料。
child_removed 監聽清單中項目的移除作業。當移除直接子項時，系統會觸發這項事件。傳遞至回呼區塊的快照包含已移除子項的資料。
child_moved 監聽已排序清單中項目順序的變更。 child_moved 事件一律會在 child_changed 事件之後發生，而這會導致商品的訂單發生變更 (依據目前的排序方式)。

這兩者都有助於監聽資料庫中特定節點的變更。舉例來說，社交網誌應用程式可以搭配使用下列方法，監控貼文留言中的活動，如下所示：

Web

import { getDatabase, ref, onChildAdded, onChildChanged, onChildRemoved } from "firebase/database";

const db = getDatabase();
const commentsRef = ref(db, 'post-comments/' + postId);
onChildAdded(commentsRef, (data) => {
  addCommentElement(postElement, data.key, data.val().text, data.val().author);
});

onChildChanged(commentsRef, (data) => {
  setCommentValues(postElement, data.key, data.val().text, data.val().author);
});

onChildRemoved(commentsRef, (data) => {
  deleteComment(postElement, data.key);
});
rtdb_social_listen_children.js

Web

var commentsRef = firebase.database().ref('post-comments/' + postId);
commentsRef.on('child_added', (data) => {
  addCommentElement(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_changed', (data) => {
  setCommentValues(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_removed', (data) => {
  deleteComment(postElement, data.key);
});
lists-of-data.js

監聽值事件

雖然我們建議您監聽子事件來讀取資料清單，但在某些情況下，監聽清單參照中的值事件會很實用。

將 value 觀察器附加至資料清單，系統會將整個資料清單做為單一快照傳回，您可以循環處理該快照來存取個別子項。

即使查詢只符合一個項目，快照仍是清單，只是只包含一個項目。如要存取項目，您必須對結果進行迴圈：

Web

import { getDatabase, ref, onValue } from "firebase/database";

const db = getDatabase();
const dbRef = ref(db, '/a/b/c');

onValue(dbRef, (snapshot) => {
  snapshot.forEach((childSnapshot) => {
    const childKey = childSnapshot.key;
    const childData = childSnapshot.val();
    // ...
  });
}, {
  onlyOnce: true
});
rtdb_social_listen_value.js

Web

ref.once('value', (snapshot) => {
  snapshot.forEach((childSnapshot) => {
    var childKey = childSnapshot.key;
    var childData = childSnapshot.val();
    // ...
  });
});
lists-of-data.js

如要擷取清單的所有子項，而非監聽其他子項新增事件，這類模式就很實用。

排序及篩選資料

您可以使用 Realtime Database Query 類別，擷取依鍵、值或子項值排序的資料。您也可以將排序結果篩選為特定數量的結果，或篩選出特定範圍的鍵或值。

排序資料

如要擷取已排序的資料，請先指定其中一種排序方法，以決定結果的排序方式：

方法 用量
orderByChild() 按指定子項鍵或巢狀子路徑的值排序結果。
orderByKey() 依子項索引鍵排序結果。
orderByValue() 依子項值排序結果。

您一次只能使用 一個 排序方法。在同一項查詢中多次呼叫排序方法會擲回錯誤。

以下範例說明如何擷取使用者最受歡迎的貼文清單 (依星級評等排序)：

Web

import { getDatabase, ref, query, orderByChild } from "firebase/database";
import { getAuth } from "firebase/auth";

const db = getDatabase();
const auth = getAuth();

const myUserId = auth.currentUser.uid;
const topUserPostsRef = query(ref(db, 'user-posts/' + myUserId), orderByChild('starCount'));
rtdb_social_most_starred.js

Web

var myUserId = firebase.auth().currentUser.uid;
var topUserPostsRef = firebase.database().ref('user-posts/' + myUserId).orderByChild('starCount');
lists-of-data.js

這會定義查詢，當與子項事件監聽器結合時，會根據使用者 ID 將用戶端與使用者的資料庫路徑中的貼文同步，並依每則貼文收到的星號數排序。使用 ID 做為索引鍵的技術稱為資料擴散傳遞，詳情請參閱建立資料庫結構。

呼叫 orderByChild() 方法時，請指定子項鍵來排序結果。在這種情況下，系統會依據各個 "starCount" 子項的值排序貼文。若您有類似以下的資料，查詢也可以按巢狀子項排序：

"posts": {
  "ts-functions": {
    "metrics": {
      "views" : 1200000,
      "likes" : 251000,
      "shares": 1200,
    },
    "title" : "Why you should use TypeScript for writing Cloud Functions",
    "author": "Doug",
  },
  "android-arch-3": {
    "metrics": {
      "views" : 900000,
      "likes" : 117000,
      "shares": 144,
    },
    "title" : "Using Android Architecture Components with Firebase Realtime Database (Part 3)",
    "author": "Doug",
  }
},

在這種情況下，我們可以透過在 orderByChild() 呼叫中指定巢狀子項的相對路徑，依據巢狀於 metrics 鍵下的值排序清單元素。

Web

import { getDatabase, ref, query, orderByChild } from "firebase/database";

const db = getDatabase();
const mostViewedPosts = query(ref(db, 'posts'), orderByChild('metrics/views'));
rtdb_social_most_viewed.js

Web

var mostViewedPosts = firebase.database().ref('posts').orderByChild('metrics/views');
lists-of-data.js

如要進一步瞭解其他資料類型的排序方式，請參閱「查詢資料的排序方式」。

篩選資料

如要篩選資料，您可以在建構查詢時，將任何限制或範圍方法與排序方法結合。

方法 用量
limitToFirst() 設定從排序結果清單開頭傳回的項目數量上限。
limitToLast() 設定從排序結果清單結尾傳回的項目數量上限。
startAt() 傳回大於或等於指定鍵或值的項目，具體取決於所選排序方法。
startAfter() 傳回大於指定鍵或值的項目，具體取決於所選排序方法。
endAt() 依據所選順序，傳回小於或等於指定鍵或值的項目。
endBefore() 傳回的項目小於指定的鍵或值，具體取決於所選排序方法。
equalTo() 傳回等於指定鍵或值的項目，具體取決於所選排序方法。

與排序方法不同，您可以結合多個限制或範圍函式。舉例來說，您可以結合 startAt() 和 endAt() 方法，將結果限制在指定的值範圍內。

限制結果數量

您可以使用 limitToFirst() 和 limitToLast() 方法，設定特定事件要同步的子項數量上限。舉例來說，如果您使用 limitToFirst() 將限制設為 100，則一開始只會收到 100 個 child_added 事件。如果 Firebase 資料庫中儲存的項目少於 100 個，系統會為每個項目觸發 child_added 事件。

項目有變動時，對於輸入查詢的項目，您會收到 child_added 事件，而為了讓總數保持為 100 的項目，您會收到 child_removed 事件。

以下範例說明如何透過查詢，擷取所有使用者最近 100 篇貼文的清單：

Web

import { getDatabase, ref, query, limitToLast } from "firebase/database";

const db = getDatabase();
const recentPostsRef = query(ref(db, 'posts'), limitToLast(100));
rtdb_social_recent.js

Web

var recentPostsRef = firebase.database().ref('posts').limitToLast(100);
lists-of-data.js

這個範例只定義查詢，因此需要附加 事件監聽器才能實際同步處理資料。

依鍵或值篩選

您可以使用 startAt()、startAfter()、endAt()、endBefore() 和 equalTo() 為查詢選擇任意起始、結束和等價點。這對於分頁資料或尋找具有特定值的子項項目很有幫助。

查詢資料的排序方式

本節說明如何依據 Query 類別中的各個排序方法排序資料。

orderByChild

使用 orderByChild() 時，包含指定子鍵的資料會依下列順序排序：

  1. 針對指定子項鍵，具有 null 值的子項會優先顯示。
  2. 指定子項金鑰值為 false 的子項接著會顯示。如果多個子項的值為 false，則這些子項的值會按照鍵字母順序排序。
  3. 接著是指定子項鍵的值為 true 的子項。如果有多個子項的值為 true，系統會依字典順序依鍵排序。
  4. 接著是具有數值的子項，以遞增順序排列。如果多個子項的數值與指定子項節點相同，系統會依鍵值排序。
  5. 字串會排在數字之後，並依字典順序遞增排列。如果多個子項的值與指定子節點相同，系統會依字典順序排序。
  6. 物件在最後，且依鍵的字母順序依遞增順序排列。

orderByKey

使用 orderByKey() 排序資料時，系統會依鍵值以遞增順序傳回資料。

  1. 可解析為 32 位元整數的鍵的子項會排在最前面，並以遞增順序排序。
  2. 具有字串值做為索引鍵的下一個子項，並依字母順序遞增排序。

orderByValue

使用 orderByValue() 時，子項會依值排序。排序條件與 orderByChild() 相同，只是使用節點的值，而非指定子項鍵的值。

卸離監聽器

您可以呼叫 Firebase 資料庫參考資料的 off() 方法，移除回呼。

您可以將單一事件監聽器做為參數傳遞至 off()，藉此移除該事件監聽器。在位置上呼叫 off() 時不帶任何引數，會移除該位置的所有事件監聽器。

在父項事件監聽器上呼叫 off() 不會自動移除在子項節點上註冊的事件監聽器；您必須在任何子項事件監聽器上呼叫 off()，才能移除回呼。

後續步驟