使用網路上的資料清單

取得資料庫參照

如要從資料庫讀取或寫入資料，您需要 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() 依子項值排序結果。

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

以下範例說明如何擷取使用者熱門貼文的清單，並依星等排序：

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 事件，以及退出查詢的項目 child_removed 事件，因此總數會維持在 100。

以下範例說明範例部落格應用程式如何定義查詢，以擷取所有使用者最近的 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()，才能移除回呼。

後續步驟