(可選)使用 Firebase 本地模擬器套件進行原型設計和測試
在討論您的應用如何讀取和寫入實時數據庫之前,我們先介紹一組可用於原型設計和測試實時數據庫功能的工具:Firebase Local Emulator Suite。如果您正在嘗試不同的數據模型、優化安全規則或努力尋找與後端交互的最具成本效益的方式,那麼能夠在本地工作而不部署實時服務可能是一個好主意。
實時數據庫模擬器是本地模擬器套件的一部分,它使您的應用程序能夠與模擬數據庫內容和配置以及可選的模擬項目資源(函數、其他數據庫和安全規則)進行交互。
使用實時數據庫模擬器只需幾個步驟:
- 將一行代碼添加到應用程序的測試配置中以連接到模擬器。
- 從本地項目目錄的根目錄中,運行
firebase emulators:start
。 - 像往常一樣使用實時數據庫平台 SDK 或使用實時數據庫 REST API 從應用程序的原型代碼進行調用。
提供了涉及實時數據庫和雲功能的詳細演練。您還應該看看本地仿真器套件的介紹。
獲取數據庫參考
要從數據庫讀取或寫入數據,您需要一個firebase.database.Reference
實例:
Web modular API
import { getDatabase } from "firebase/database"; const database = getDatabase();
Web namespaced API
var database = firebase.database();
寫入數據
本文檔介紹了檢索數據以及如何排序和過濾 Firebase 數據的基礎知識。
通過將異步偵聽器附加到firebase.database.Reference
來檢索 Firebase 數據。偵聽器在數據初始狀態時觸發一次,並在數據發生變化時再次觸發。
基本寫操作
對於基本的寫入操作,您可以使用set()
將數據保存到指定的引用,替換該路徑上的任何現有數據。例如,社交博客應用程序可能會使用set()
添加用戶,如下所示:
Web modular 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 }); }
Web namespaced API
function writeUserData(userId, name, email, imageUrl) { firebase.database().ref('users/' + userId).set({ username: name, email: email, profile_picture : imageUrl }); }
使用set()
會覆蓋指定位置的數據,包括任何子節點。
讀取數據
監聽值事件
要讀取路徑上的數據並偵聽更改,請使用onValue()
來觀察事件。您可以使用此事件讀取給定路徑中內容的靜態快照,因為它們在事件發生時已存在。該方法在附加偵聽器時觸發一次,每次數據(包括子項)發生更改時都會觸發一次。向事件回調傳遞包含該位置的所有數據(包括子數據)的快照。如果沒有數據,則當您調用exists()
時快照將返回false
,而當您對其調用val()
時快照將返回null
。
以下示例演示了一個社交博客應用程序從數據庫中檢索帖子的星級計數:
Web modular 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); });
Web namespaced API
var starCountRef = firebase.database().ref('posts/' + postId + '/starCount'); starCountRef.on('value', (snapshot) => { const data = snapshot.val(); updateStarCount(postElement, data); });
偵聽器接收包含事件發生時數據庫中指定位置的數據的snapshot
。您可以使用val()
方法snapshot
中的數據。
讀取一次數據
使用 get() 讀取一次數據
該 SDK 旨在管理與數據庫服務器的交互,無論您的應用程序是在線還是離線。
通常,您應該使用上述值事件技術來讀取數據,以從後端獲取數據更新的通知。偵聽器技術可減少您的使用量和計費,並經過優化,可為您的用戶提供在線和離線時的最佳體驗。
如果您只需要一次數據,則可以使用get()
從數據庫獲取數據的快照。如果由於任何原因get()
無法返回服務器值,客戶端將探測本地存儲緩存,如果仍未找到該值,則返回錯誤。
不必要地使用get()
會增加帶寬的使用並導致性能損失,這可以通過使用實時偵聽器來防止,如上所示。
Web modular 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); });
Web namespaced 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); });
用觀察者讀取一次數據
在某些情況下,您可能希望立即返回本地緩存中的值,而不是檢查服務器上的更新值。在這些情況下,您可以使用once()
立即從本地磁盤緩存中獲取數據。
這對於只需要加載一次並且預計不會頻繁更改或需要主動偵聽的數據非常有用。例如,前面示例中的博客應用程序在用戶開始創作新帖子時使用此方法加載用戶的個人資料:
Web modular 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 });
Web namespaced 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'; // ... });
更新或刪除數據
更新特定字段
要同時寫入節點的特定子節點而不覆蓋其他子節點,請使用update()
方法。
調用update()
時,您可以通過指定鍵的路徑來更新較低級別的子值。如果數據存儲在多個位置以更好地擴展,您可以使用數據扇出更新該數據的所有實例。
例如,社交博客應用程序可能會創建一個帖子,並同時使用如下代碼將其更新為最近的活動源和發帖用戶的活動源:
Web modular 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); }
Web namespaced 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); }
此示例使用push()
在包含/posts/$postid
處所有用戶的帖子的節點中創建帖子,並同時檢索密鑰。然後,該密鑰可用於在/user-posts/$userid/$postid
處的用戶帖子中創建第二個條目。
使用這些路徑,您可以通過一次調用update()
對 JSON 樹中的多個位置執行同步更新,例如本示例如何在兩個位置創建新帖子。以這種方式進行的同時更新是原子的:要么所有更新成功,要么所有更新失敗。
添加完成回調
如果您想知道數據何時提交,可以添加完成回調。 set()
和update()
都採用一個可選的完成回調,當寫入已提交到數據庫時調用該回調。如果調用不成功,則會向回調傳遞一個錯誤對象,指示發生失敗的原因。
Web modular 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... });
Web namespaced API
firebase.database().ref('users/' + userId).set({ username: name, email: email, profile_picture : imageUrl }, (error) => { if (error) { // The write failed... } else { // Data saved successfully! } });
刪除數據
刪除數據的最簡單方法是在對該數據位置的引用上調用remove()
。
您還可以通過將null
指定為另一個寫入操作(例如set()
或update()
的值來刪除。您可以將此技術與update()
結合使用,以在單個 API 調用中刪除多個子項。
收到Promise
要了解您的數據何時提交到 Firebase 實時數據庫服務器,您可以使用Promise
。 set()
和update()
都可以返回一個Promise
,您可以使用它來了解寫入何時提交到數據庫。
分離監聽器
通過調用 Firebase 數據庫引用上的off()
方法來刪除回調。
您可以通過將單個監聽器作為參數傳遞給off()
來刪除它。在不帶參數的位置調用off()
會刪除該位置的所有偵聽器。
在父監聽器上調用off()
不會自動刪除在其子節點上註冊的監聽器;還必須在任何子偵聽器上調用off()
以刪除回調。
將數據保存為交易
當處理可能被並發修改損壞的數據(例如增量計數器)時,您可以使用事務操作。您可以為此操作提供更新函數和可選的完成回調。更新函數將數據的當前狀態作為參數,並返回您想要寫入的新的所需狀態。如果在成功寫入新值之前另一個客戶端寫入該位置,則會使用新的當前值再次調用您的更新函數,並重試寫入。
例如,在示例社交博客應用程序中,您可以允許用戶對帖子加註星標和取消星標,並跟踪帖子收到的星數,如下所示:
Web modular 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; }); }
Web namespaced 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; }); }
如果多個用戶同時為同一個帖子加註星標或者客戶端的數據過時,使用事務可以防止星數計數不正確。如果事務被拒絕,服務器將當前值返回給客戶端,客戶端使用更新後的值再次運行事務。如此重複,直到交易被接受或您中止交易。
原子服務器端增量
在上面的用例中,我們將兩個值寫入數據庫:為帖子加註星標/取消加註星標的用戶的 ID,以及增加的星數。如果我們已經知道用戶正在為帖子加註星標,我們可以使用原子增量操作而不是事務。
Web modular 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); }
Web namespaced 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); }
此代碼不使用事務操作,因此如果存在更新衝突,它不會自動重新運行。但是,由於增量操作直接發生在數據庫服務器上,因此不會發生衝突。
如果您想要檢測並拒絕特定於應用程序的衝突,例如用戶為他們之前已經加註過星標的帖子加註星標,您應該為該用例編寫自定義安全規則。
離線處理數據
如果客戶端失去網絡連接,您的應用程序將繼續正常運行。
連接到 Firebase 數據庫的每個客戶端都會維護自己的任何活動數據的內部版本。寫入數據時,首先寫入此本地版本。然後,Firebase 客戶端會“盡力”將該數據與遠程數據庫服務器和其他客戶端同步。
因此,在將任何數據寫入服務器之前,對數據庫的所有寫入都會立即觸發本地事件。這意味著無論網絡延遲或連接如何,您的應用程序都保持響應。
重新建立連接後,您的應用程序會收到適當的事件集,以便客戶端與當前服務器狀態同步,而無需編寫任何自定義代碼。
我們將在了解有關在線和離線功能的更多信息中詳細討論離線行為。