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

在網路上讀取及寫入資料

(選用) 使用 Firebase 本機模擬器套件設計原型並進行測試

在討論應用程式如何讀取即時資料庫及寫入資料之前，我們會先介紹一組工具，讓您用來設計原型及測試即時資料庫功能：Firebase 本機模擬器套件。如果您正在嘗試不同的資料模型、最佳化安全性規則，或想找出最符合成本效益的方式與後端互動，那麼即使不部署即時服務，也能在本機工作。

即時資料庫模擬器屬於本機模擬器套件的一部分，可讓應用程式與模擬資料庫內容和設定互動，並選擇性地與模擬專案資源 (函式、其他資料庫和安全性規則) 互動。

使用即時資料庫模擬器只需完成幾個步驟：

將一行程式碼新增至應用程式的測試設定，即可與模擬器連線。
從本機專案目錄的根目錄中執行 firebase emulators:start。
照常透過即時資料庫平台 SDK 或即時資料庫 REST API，從應用程式的原型程式碼發出呼叫。

歡迎查看詳細的即時資料庫和 Cloud Functions 逐步操作說明。建議您也參閱「本機模擬器套件簡介」一文。

取得資料庫參照

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

網頁模組 API

import { getDatabase } from "firebase/database";

const database = getDatabase();rtdb_get_reference.js

網路命名空間 API

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

寫入資料

本文說明擷取資料的基本概念，以及如何排序及篩選 Firebase 資料。

將非同步事件監聽器附加至 firebase.database.Reference，即可擷取 Firebase 資料。監聽器會針對資料的初始狀態觸發一次，並在資料變更時再次觸發。

基本寫入作業

針對基本寫入作業，您可以使用 set() 將資料儲存至指定的參照，取代該路徑中的所有現有資料。舉例來說，社交網誌應用程式可能會新增具有 set() 的使用者，如下所示：

網頁模組 API

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

function writeUserData(userId, name, email, imageUrl) {
  const db = getDatabase();
  set(ref(db, 'users/' + userId), {
    username: name,
    email: email,
    profile_picture : imageUrl
  });
}rtdb_write_new_user.js

網路命名空間 API

function writeUserData(userId, name, email, imageUrl) {
  firebase.database().ref('users/' + userId).set({
    username: name,
    email: email,
    profile_picture : imageUrl
  });
}read-and-write.js

使用 set() 會覆寫指定位置的資料，包括任何子節點。

讀取資料

監聽價值事件

如要在路徑中讀取資料及監聽變更，請使用 onValue() 來觀察事件。您可以使用此事件來讀取特定路徑的內容靜態快照，因為這些快照在事件發生時就存在。此方法會在連接事件監聽器時觸發一次，並在每次資料 (包括子項) 變更時再次觸發。事件回呼會傳遞一個快照，當中包含該位置的所有資料，包括子項資料。如果沒有資料，則當您在呼叫 exists() 和 val() 時，系統會傳回快照false和 null。

以下範例將示範社交網誌應用程式，如何從資料庫擷取文章的星號數：

網頁模組 API

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

const db = getDatabase();
const starCountRef = ref(db, 'posts/' + postId + '/starCount');
onValue(starCountRef, (snapshot) => {
  const data = snapshot.val();
  updateStarCount(postElement, data);
});rtdb_social_listen_star_count.js

網路命名空間 API

var starCountRef = firebase.database().ref('posts/' + postId + '/starCount');
starCountRef.on('value', (snapshot) => {
  const data = snapshot.val();
  updateStarCount(postElement, data);
});read-and-write.js

事件監聽器會收到 snapshot，其中包含事件發生時資料庫中指定的位置資料。您可以使用 val() 方法在 snapshot 中擷取資料。

讀取資料一次

使用 get() 讀取資料一次

無論應用程式處於線上或離線狀態，SDK 都能用來管理與資料庫伺服器的互動。

一般來說，您應使用上述的值事件技術來讀取資料，以便從後端取得資料更新的通知。事件監聽器技術可減少用量和費用，並經過最佳化調整，可在使用者上線及離線時提供最佳體驗。

如果您只需要資料一次，可以使用 get() 取得資料庫中的資料快照。如果因任何原因 get() 無法傳回伺服器值，用戶端會探測本機儲存空間快取，如果還是找不到該值，就會傳回錯誤。

不必要的使用 get() 可能會增加頻寬用量，並導致效能遺失，可以如上所示使用即時事件監聽器來避免這種情況。

網頁模組 API

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

const dbRef = ref(getDatabase());
get(child(dbRef, `users/${userId}`)).then((snapshot) => {
  if (snapshot.exists()) {
    console.log(snapshot.val());
  } else {
    console.log("No data available");
  }
}).catch((error) => {
  console.error(error);
});rtdb_read_once_get.js

網路命名空間 API

const dbRef = firebase.database().ref();
dbRef.child("users").child(userId).get().then((snapshot) => {
  if (snapshot.exists()) {
    console.log(snapshot.val());
  } else {
    console.log("No data available");
  }
}).catch((error) => {
  console.error(error);
});read-and-write.js

使用觀察器讀取資料一次

在某些情況下，您可能會希望立即傳回本機快取中的值，而不是檢查伺服器上的更新值。在這類情況下，您可以使用 once() 立即從本機磁碟快取取得資料。

如果資料只需載入一次、預期不會經常變更或需要主動監聽，這項功能就能派上用場。舉例來說，上述範例中的網誌應用程式會使用這個方法，在使用者開始撰寫新文章時載入個人資料：

網頁模組 API

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

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

const userId = auth.currentUser.uid;
return onValue(ref(db, '/users/' + userId), (snapshot) => {
  const username = (snapshot.val() && snapshot.val().username) || 'Anonymous';
  // ...
}, {
  onlyOnce: true
});rtdb_social_single_value_read.js

網路命名空間 API

var userId = firebase.auth().currentUser.uid;
return firebase.database().ref('/users/' + userId).once('value').then((snapshot) => {
  var username = (snapshot.val() && snapshot.val().username) || 'Anonymous';
  // ...
});read-and-write.js

更新或刪除資料

更新特定欄位

如要同時寫入節點的特定子項，而不覆寫其他子節點，請使用 update() 方法。

呼叫 update() 時，您可以指定索引鍵路徑，更新較低層級的子項值。如果資料儲存在多個位置以利擴充，您可以使用資料擴散傳遞功能更新該資料的所有執行個體。

舉例來說，社交網誌應用程式可能會建立貼文，同時使用以下程式碼，將貼文更新為最近的活動動態消息和發布使用者的活動動態消息：

網頁模組 API

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

function writeNewPost(uid, username, picture, title, body) {
  const db = getDatabase();

  // A post entry.
  const postData = {
    author: username,
    uid: uid,
    body: body,
    title: title,
    starCount: 0,
    authorPic: picture
  };

  // Get a key for a new Post.
  const newPostKey = push(child(ref(db), 'posts')).key;

  // Write the new post's data simultaneously in the posts list and the user's post list.
  const updates = {};
  updates['/posts/' + newPostKey] = postData;
  updates['/user-posts/' + uid + '/' + newPostKey] = postData;

  return update(ref(db), updates);
}rtdb_social_write_fan_out.js

網路命名空間 API

function writeNewPost(uid, username, picture, title, body) {
  // A post entry.
  var postData = {
    author: username,
    uid: uid,
    body: body,
    title: title,
    starCount: 0,
    authorPic: picture
  };

  // Get a key for a new Post.
  var newPostKey = firebase.database().ref().child('posts').push().key;

  // Write the new post's data simultaneously in the posts list and the user's post list.
  var updates = {};
  updates['/posts/' + newPostKey] = postData;
  updates['/user-posts/' + uid + '/' + newPostKey] = postData;

  return firebase.database().ref().update(updates);
}read-and-write.js

此範例使用 push() 在節點中建立貼文，其中包含 /posts/$postid 中所有使用者的貼文，然後同時擷取金鑰。這樣就能在使用者的貼文中，用此金鑰在 /user-posts/$userid/$postid 建立第二個項目。

您可以使用這些路徑，只呼叫 update() 就能同時更新 JSON 樹狀結構中的多個位置，例如這個範例如何在兩個位置建立新貼文。以這種方式進行的同步更新是不可分割的：所有更新成功或所有更新都會失敗。

新增完成回呼

如要瞭解資料修訂時間，可以新增完成回呼。set() 和 update() 會採用選用的完成回呼，當系統將寫入作業提交至資料庫時，就會呼叫該回呼。如果呼叫失敗，系統會傳送回呼錯誤物件，指出失敗的原因。

網頁模組 API

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

const db = getDatabase();
set(ref(db, 'users/' + userId), {
  username: name,
  email: email,
  profile_picture : imageUrl
})
.then(() => {
  // Data saved successfully!
})
.catch((error) => {
  // The write failed...
});rtdb_social_completion_callback.js

網路命名空間 API

firebase.database().ref('users/' + userId).set({
  username: name,
  email: email,
  profile_picture : imageUrl
}, (error) => {
  if (error) {
    // The write failed...
  } else {
    // Data saved successfully!
  }
});read-and-write.js

刪除資料

刪除資料最簡單的方法是對該資料位置的參照呼叫 remove()。

您也可以指定 null 為其他寫入作業 (例如 set() 或 update()) 的值來刪除。您可以將這項技術與 update() 搭配使用，在單一 API 呼叫中刪除多個子項。

接收 `Promise`

如要瞭解資料何時提交至 Firebase 即時資料庫伺服器，可以使用 Promise。set() 和 update() 都可以傳回 Promise，方便您知道何時將寫入作業提交至資料庫。

卸離事件監聽器

如要移除回呼，請對 Firebase 資料庫參考資料呼叫 off() 方法。

將單一事件監聽器做為參數傳遞至 off() 即可移除。如果對沒有引數的位置呼叫 off()，系統會移除該位置的所有事件監聽器。

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

將資料儲存為交易

處理可能會因為並行修改而損毀的資料 (例如漸進式計數器) 時，您可以使用交易作業。您可以將更新函式與選用的完成回呼提供給這項作業。update 函式會將資料目前狀態當做引數，並傳回您要寫入的新所需狀態。如果其他用戶端在成功寫入新值之前寫入位置，系統會以新的目前值再次呼叫更新函式，並重試寫入。

舉例來說，在社交網誌應用程式範例中，您可以讓使用者為文章加上星號或移除星號，也可以追蹤貼文獲得的星星數量，如下所示：

網頁模組 API

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

function toggleStar(uid) {
  const db = getDatabase();
  const postRef = ref(db, '/posts/foo-bar-123');

  runTransaction(postRef, (post) => {
    if (post) {
      if (post.stars && post.stars[uid]) {
        post.starCount--;
        post.stars[uid] = null;
      } else {
        post.starCount++;
        if (!post.stars) {
          post.stars = {};
        }
        post.stars[uid] = true;
      }
    }
    return post;
  });
}rtdb_social_star_transaction.js

網路命名空間 API

function toggleStar(postRef, uid) {
  postRef.transaction((post) => {
    if (post) {
      if (post.stars && post.stars[uid]) {
        post.starCount--;
        post.stars[uid] = null;
      } else {
        post.starCount++;
        if (!post.stars) {
          post.stars = {};
        }
        post.stars[uid] = true;
      }
    }
    return post;
  });
}read-and-write.js

如果多位使用者同時為同一則貼文加上星號，或用戶端取得過時的資料，使用交易可避免星號計數有誤。如果交易遭拒，伺服器會將目前的值傳回用戶端，用戶端會使用更新後的值再次執行交易。系統會重複執行，直到接受交易或您取消交易為止。

整體伺服器端增量

在上述用途中，我們要將兩個值寫入資料庫：為貼文加上星號/移除星號的使用者 ID，以及增加的星號數量。如果我們知道使用者已為貼文加上星號，則可使用不可分割的遞增作業，而非交易。

網頁模組 API

function addStar(uid, key) {
  import { getDatabase, increment, ref, update } from "firebase/database";
  const dbRef = ref(getDatabase());

  const updates = {};
  updates[`posts/${key}/stars/${uid}`] = true;
  updates[`posts/${key}/starCount`] = increment(1);
  updates[`user-posts/${key}/stars/${uid}`] = true;
  updates[`user-posts/${key}/starCount`] = increment(1);
  update(dbRef, updates);
}rtdb_social_star_increment.js

網路命名空間 API

function addStar(uid, key) {
  const updates = {};
  updates[`posts/${key}/stars/${uid}`] = true;
  updates[`posts/${key}/starCount`] = firebase.database.ServerValue.increment(1);
  updates[`user-posts/${key}/stars/${uid}`] = true;
  updates[`user-posts/${key}/starCount`] = firebase.database.ServerValue.increment(1);
  firebase.database().ref().update(updates);
}read-and-write.js

此程式碼不會使用交易作業，所以在有衝突的更新時，不會自動重新執行。不過，由於增量作業會直接在資料庫伺服器上進行，因此不會發生衝突。

如要偵測並拒絕應用程式特定衝突 (例如使用者為先前已加上星號的貼文加上星號)，則必須針對該用途編寫自訂安全性規則。

離線使用資料

如果用戶端的網路連線中斷，您的應用程式會繼續正常運作。

每個連接至 Firebase 資料庫的用戶端，都會維護自己的任何有效資料的內部版本。寫入資料時，系統會先將資料寫入這個本機版本。接著，Firebase 用戶端會「盡可能」將這些資料與遠端資料庫伺服器和其他用戶端同步處理。

因此，在將任何資料寫入伺服器之前，所有寫入資料庫的作業會立即觸發本機事件。換句話說，無論網路延遲或連線狀況，應用程式都會持續回應。

重新建立連線後，應用程式會收到一組適當的事件，讓用戶端與目前的伺服器狀態同步，而不必編寫任何自訂程式碼。

我們會在進一步瞭解線上和離線功能中，進一步說明離線行為。

在網路上讀取及寫入資料

(選用) 使用 Firebase 本機模擬器套件設計原型並進行測試

取得資料庫參照

網頁模組 API

網路命名空間 API

寫入資料

基本寫入作業

網頁模組 API

網路命名空間 API

讀取資料

監聽價值事件

網頁模組 API

網路命名空間 API

讀取資料一次

使用 get() 讀取資料一次

網頁模組 API

網路命名空間 API

使用觀察器讀取資料一次

網頁模組 API

網路命名空間 API

更新或刪除資料

更新特定欄位

網頁模組 API

網路命名空間 API

新增完成回呼

網頁模組 API

網路命名空間 API

刪除資料

接收 Promise

卸離事件監聽器

將資料儲存為交易

網頁模組 API

網路命名空間 API

整體伺服器端增量

網頁模組 API

網路命名空間 API

離線使用資料

後續步驟

接收 `Promise`