本頁面由 Cloud Translation API 翻譯而成。

使用資料清單

取得資料庫參照

如要從資料庫讀取或寫入資料，您需要使用 DatabaseReference:

DatabaseReference ref = FirebaseDatabase.instance.ref();

讀取及寫入清單

附加至資料清單

使用 push() 方法，將資料附加至多使用者應用程式中的清單。每當新增子項時，push() 方法都會產生專屬金鑰指定的 Firebase 參考資料針對每個項目使用自動產生的金鑰多個用戶端可將子項新增至同一個位置不會發生寫入衝突push() 產生的專屬金鑰依據時間戳記，因此清單項目會自動排序依時間排序。

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

您可以使用這些自動產生的金鑰來簡化資料彙整作業成本中心的架構詳情請參閱資料擴散傳遞範例。

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

DatabaseReference postListRef = FirebaseDatabase.instance.ref("posts");
DatabaseReference newPostRef = postListRef.push();
newPostRef.set({
  // ...
});

監聽子事件

如果發生子事件，子事件會觸發，節點的子項，例如透過 push() 方法或透過 update() 方法更新的子項。

活動	一般用量
`onChildAdded`	擷取項目清單，或監聽附加項目清單。系統會為每個現有的子項觸發此事件一次，然後再次每次將新子項加入指定路徑時，都會產生事件。事件監聽器會傳送了含有新子項資料的快照。
`onChildChanged`	監聽清單中項目的變更。每當修改子節點時，就會觸發這個事件。這包括任何對子節點子系所做的任何修改。已通過的快照，包含子項的更新資料。
`onChildRemoved`	監聽已從清單中移除的項目。這個事件會在會移除立即子項。傳遞至回呼區塊的快照包含已移除之子帳戶的資料。
`onChildMoved`	監聽已排序清單中項目順序的變更。 onChildMoved 事件都會遵守 onChildChanged 事件導致商品訂單 (根據目前的訂單處理方式)。

當您要監聽特定變更快取節點舉例來說，社交網誌應用程式可能會使用以下方法以監控貼文留言的活動，如下所示：

final commentsRef = FirebaseDatabase.instance.ref("post-comments/$postId");
commentsRef.onChildAdded.listen((event) {
  // A new comment has been added, so add it to the displayed list.
});
commentsRef.onChildChanged.listen((event) {
  // A comment has changed; use the key to determine if we are displaying this
  // comment and if so displayed the changed comment.
});
commentsRef.onChildRemoved.listen((event) {
  // A comment has been removed; use the key to determine if we are displaying
  // this comment and if so remove it.
});

監聽價值事件

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

將 value 事件監聽器附加至資料清單時，系統會傳回建立整份資料清單，然後透過單一快照進行迴圈存取個別子項

即使查詢只有一個相符結果，快照仍為清單；只會包含單一項目如要存取該項目，就必須進行迴圈套用到結果：

myTopPostsQuery.onValue.listen((event) {
  for (final child in event.snapshot.children) {
    // Handle the post.
  }
}, onError: (error) {
  // Error.
});

當您想要擷取清單的所有子項時，這種模式相當實用視為單一作業，而非監聽額外新增的子項事件。

排序及篩選資料

您可以使用 Query 類別擷取依下列條件排序的資料索引鍵、值或子項的值你也可以篩選在特定數量的結果或索引鍵範圍內排序的結果輕鬆分配獎金

排序資料

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

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

一次只能使用「一個」排序方法。依訂單呼叫方法重複計算錯誤。

以下範例說明如何擷取使用者的熱門訊息會按照星級評等排序：

final myUserId = FirebaseAuth.instance.currentUser?.uid;
final topUserPostsRef = FirebaseDatabase.instance
    .ref("user-posts/$myUserId")
    .orderByChild("starCount");

這會定義一項查詢，在與子事件監聽器合併使用時將用戶端與資料庫路徑中的使用者貼文同步處理排序依據為每則貼文獲得的星星數量。使用 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",
  }
},

在此情況下，我們可以根據 metrics 鍵，方法是在 orderByChild() 呼叫。

final mostViewedPosts =
    FirebaseDatabase.instance.ref('posts').orderByChild('metrics/views');

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

篩選資料

如要篩選資料，可以使用任何限製或範圍方法，依順序排序查詢。

方法	用量
`limitToFirst()`	設定從結果的排序清單。
`limitToLast()`	設定從訂單結尾傳回的項目數量上限結果清單。
`startAt()`	傳回大於或等於指定鍵/值的項目。視所選的訂單而定
`startAfter()`	傳回大於指定鍵或值的項目視所選的訂單而定
`endAt()`	傳回小於或等於指定鍵/值的項目；視所選的訂單而定
`endBefore()`	傳回小於指定鍵或值的項目視所選的訂單而定
`equalTo()`	根據。

有別於逐一排序的方法，您可以合併多個限製或範圍函式。例如，您可以結合 startAt() 和 endAt() 方法將結果傳回指定範圍內的值

限制結果數量

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

隨著物品變更，onChildAdded只要進入新的查詢內容和 onChildRemoved 事件總數會維持在 100

以下範例示範網誌應用程式如何定義查詢擷取所有使用者最新張貼的 100 篇文章清單：

final recentPostsRef = FirebaseDatabase.instance.ref('posts').limitToLast(100);

這個範例只會定義一項查詢，且會實際同步處理需要的資料已連結事件監聽器。

依鍵或值篩選

您可以使用 startAt()、startAfter()、endAt()、endBefore() 和 equalTo() 可選擇任意的起始、結束和等分點舉個簡單的例子，您可以定義情境並指示 AI 如何回應服務中心查詢這有助於分頁資料或尋找含有子項的項目都有特定的值

查詢資料的排序方式

本節會說明 Query 類別。

`orderByChild`

使用 orderByChild() 時，包含指定子項鍵的資料將會是排序如下：

針對指定子項鍵有 null 值的子項，如下所示首先。
指定子鍵值為 false 的子項取得下一個提示如果多個子項的值為 false，這些子項就會依鍵字母順序排序。
指定子鍵值為 true 的子項取得下一個提示如果多個子項的值為 true，這些子項就會依索引鍵字母順序排列
含有數值的子項接著會以遞增順序排序。如果多個子項的數值相同節點，按鍵排序。
字串是由數字後方，並依字母順序遞增順序。如果多個子項具有相同的值節點的節點，按照鍵的字母順序排列。
物件在最後，且依索引鍵順序排列，以遞增順序排列。

`orderByKey`

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

如果子項的索引鍵可剖析為 32 位元整數，其內容會先以遞增順序排序。
具有字串值做為索引鍵的下一個子項，並依字母順序遞增排序。

`orderByValue`

使用 orderByValue() 時，子項會按照值的順序排列。順序條件與 orderByChild() 相同，但節點值，而不是指定子鍵的值。

卸離事件監聽器

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

將單一事件監聽器做為參數傳遞至 off() 即可移除。在沒有引數的位置呼叫 off() 會移除該位置的所有事件監聽器或 HTTP/HTTPS 位置

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