database package

Firebase 即時資料庫

函式

函式 說明
功能(應用程式, ...)
getDatabase(應用程式、網址) 傳回與所提供 FirebaseApp 相關聯的即時資料庫 SDK 執行個體。如果沒有任何執行個體,或現有執行個體使用自訂資料庫網址,則以預設設定初始化新執行個體。
function(db, ...)
connectDatabaseEmulator(db、主機、通訊埠、選項) 修改提供的執行個體,以便與即時資料庫模擬器通訊。

注意:執行任何其他作業前,必須先呼叫這個方法。

goOffline(db) 與伺服器中斷連線 (所有資料庫作業都會離線完成)。用戶端會自動維持與資料庫伺服器的連線,讓資料庫無限期持續運作,並在連線中斷時重新連線。不過,在不需要持續連線的情況下,可以使用 goOffline()goOnline() 方法控制用戶端連線。離線時,用戶端不會再收到資料庫的資料更新。不過,在本機執行的所有資料庫作業都會立即觸發事件,讓應用程式繼續正常運作。此外,在本機執行的各項作業都會自動排入佇列,並在重新連線到資料庫伺服器時重試。如要重新連線至資料庫並開始接收遠端事件,請參閱 goOnline()
goOnline(db) 重新連線至伺服器,並將離線資料庫狀態與伺服器狀態同步處理。停用與 goOffline() 的有效連線後,應使用這個方法。重新連線後,用戶端就會傳輸正確的資料並觸發相應的事件,以便用戶端「盡快」。
ref(db, path) 傳回 Reference,代表資料庫中與指定路徑相對應的位置。如果未提供路徑,Reference 會指向資料庫的根目錄。
refFromURL(db, url) 根據所提供的 Firebase 網址,傳回代表資料庫中位置的 Reference如果網址不是有效的 Firebase 資料庫網址,或是網址與目前的 Database 執行個體不同,就會擲回例外狀況。請注意,所有查詢參數 (orderBylimitToLast 等) 都會遭到忽略,且不會套用至傳回的 Reference
function()
forceLongPolling() 強制使用 longPolling 而非 websocket。如果 websocket 通訊協定用於 databaseURL,系統會忽略這個通訊協定。
forceWebSockets() 強制使用 websocket,而非 longPolling。
orderByKey() 建立新的 QueryConstraint,以便按鍵排序。按照 (遞增) 鍵/值排序查詢結果。如要進一步瞭解 orderByKey(),請參閱排序資料
orderByPriority() 建立依優先順序排序的新 QueryConstraint應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序資料瞭解優先順序的替代選項)。
orderByValue() 建立依值排序的新 QueryConstraint如果查詢的子項都是純量值 (字串、數字或布林值),您可以按照遞增值排序結果。如要進一步瞭解 orderByValue(),請參閱排序資料
serverTimestamp() 傳回預留位置值,以自動填入目前時間戳記 (自 Unix 紀元以來經過的時間,以毫秒為單位),由 Firebase 伺服器決定。
function(delta, ...)
increment(delta) 傳回預留位置值,您可以使用所提供的差異值,以不可分割的形式遞增目前的資料庫值。
功能(已啟用, ...)
enableLogging(已啟用、永久) 將偵錯資訊記錄到控制台。
function(限制, ...)
limitToFirst(限制) 如果限制只列出第一個特定子項數量,會建立新的 QueryConstraintlimitToFirst() 方法可用來設定為特定回呼同步處理的子項數量上限。如果將上限設為 100,一開始我們最多只會收到 100 個 child_added 事件。如果資料庫儲存的訊息少於 100 則,每則訊息都會觸發 child_added 事件。但是,如果訊息超過 100 則,我們只會收到前 100 則已排序訊息的 child_added 事件。隨著項目有所改變,我們會針對每個從有效清單上的項目收到 child_removed 事件,讓總數維持在 100 件。如要進一步瞭解「limitToFirst()」,請參閱「篩選資料」。
limitToLast(限制) 建立新的 QueryConstraint,限制只傳回最後指定的子項數量。limitToLast() 方法可用來設定為特定回呼同步處理的子項數量上限。如果將上限設為 100,一開始我們最多只會收到 100 個 child_added 事件。如果資料庫儲存的訊息少於 100 則,每則訊息都會觸發 child_added 事件。但是,如果有超過 100 則訊息,我們只會收到最近 100 則已排序訊息的 child_added 事件。隨著項目有所改變,我們會針對每個從有效清單上的項目收到 child_removed 事件,讓總數維持在 100 件。如要進一步瞭解「limitToLast()」,請參閱「篩選資料」。
function(logger, ...)
enableLogging(logger) 將偵錯資訊記錄到控制台。
function(父項, ...)
child(父項, 路徑) 針對指定相對路徑中的位置取得 Reference相對路徑可以是簡單的子項名稱 (例如「ada」),或是更深入的斜線分隔路徑 (例如「ada/name/first」)。
push(上層, 值) 使用專屬鍵產生新的子項位置,並傳回其 Reference這是在項目集合中新增資料最常見的模式。如果為 push() 提供值,該值會寫入產生的位置。如未傳遞值,系統就不會將任何內容寫入資料庫,而子項則會維持空白 (但您可以在其他位置使用 Reference)。push() 產生的不重複鍵會按照目前時間排序,因此產生的項目清單會按照時間排序。這些鍵也經過設計,而且容易辨識 (包含 72 位元的熵)。請參閱附加至資料清單。請參閱「2^120 確保專屬 ID 的方法
function(path, ...)
orderByChild(路徑) 建立新的 QueryConstraint,並按指定子項鍵排序。查詢一次只能依一個鍵排序。在同一筆查詢中多次呼叫 orderByChild() 屬於錯誤。只要使用 Firebase 查詢,即可按任何子項鍵即時排序資料。不過,如果您事先知道索引目標,可以透過安全性規則中的 .indexOn 規則加以定義,藉此提高效能。詳情請參閱 https://firebase.google.com/docs/database/security/indexing-data 規則。如要進一步瞭解 orderByChild(),請參閱排序資料
function(查詢, ...)
get(查詢) 取得這項查詢的最新結果。
off(query, eventType, 回呼) 卸離先前附加至對應 on() (onValueonChildAdded) 事件監聽器的回呼。注意:這不是移除事件監聽器的建議方式。請改用相應 on 回呼傳回的回呼函式。卸離先前與 on*() 附加的回呼。在父項事件監聽器上呼叫 off() 並不會自動移除在子節點上註冊的事件監聽器,還必須在任何子項事件監聽器上呼叫 off(),才能移除回呼。如果未指定回呼,則系統會移除指定 eventType 的所有回呼。同樣地,如未指定 eventType,系統會移除 Reference 的所有回呼。您也可以叫用個別事件監聽器來叫用取消訂閱回呼,藉此移除個別事件監聽器。
onChildAdded(query, 回呼, cancelCallback) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。在這個位置每個初始子項都會觸發一次 onChildAdded 事件,而且每次新增子項時都會觸發這個事件。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildAdded(query, 回呼, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。在這個位置每個初始子項都會觸發一次 onChildAdded 事件,而且每次新增子項時都會觸發這個事件。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildAdded(query, 回呼, cancelCallback, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。在這個位置每個初始子項都會觸發一次 onChildAdded 事件,而且每次新增子項時都會觸發這個事件。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildChanged(query, 回呼, cancelCallback) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。
onChildChanged(query, 回呼, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。
onChildChanged(query, 回呼, cancelCallback, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。
onChildMoved(查詢, 回呼, cancelCallback) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當子項的排序順序變更,使其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildMoved(查詢, 回呼, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當子項的排序順序變更,使其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildMoved(查詢, 回呼, cancelCallback, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。當子項的排序順序變更,使其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null
onChildRemoved(query, 回呼, cancelCallback) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。每當孩子移除時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。發生以下任一情況時,就會移除子項:- 用戶端明確對其子項或其其中一個祖系呼叫 remove() (用戶端呼叫該子項或其中一個祖系的 set(null) - 該子項已移除其所有子項) - 有查詢立即篩除了子項 (因為排序順序已變更或達到上限)
onChildRemoved(query, 回呼, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。每當孩子移除時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。發生以下任一情況時,就會移除子項:- 用戶端明確對其子項或其其中一個祖系呼叫 remove() (用戶端呼叫該子項或其中一個祖系的 set(null) - 該子項已移除其所有子項) - 有查詢立即篩除了子項 (因為排序順序已變更或達到上限)
onChildRemoved(query, 回呼, cancelCallback, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。每當孩子移除時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。發生以下任一情況時,就會移除子項:- 用戶端明確對其子項或其其中一個祖系呼叫 remove() (用戶端呼叫該子項或其中一個祖系的 set(null) - 該子項已移除其所有子項) - 有查詢立即篩除了子項 (因為排序順序已變更或達到上限)
onValue(查詢, 回呼, cancelCallback) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。onValue 事件會在儲存於這個位置的初始資料時觸發一次,但每當資料變更時就會觸發一次。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。
onValue(查詢, 回呼, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。onValue 事件會在儲存於這個位置的初始資料時觸發一次,但每當資料變更時就會觸發一次。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。
onValue(查詢, 回呼, cancelCallback, 選項) 監聽特定位置的資料變更。這是從資料庫讀取資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱「在網路上擷取資料」。onValue 事件會在儲存於這個位置的初始資料時觸發一次,但每當資料變更時就會觸發一次。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。
query(query, queryConstraints) 建立 Query 的不可變新例項,該例項的擴充為一併包含其他查詢限制。
功能(參照, ...)
關於中斷連線(參考) 傳回 OnDisconnect 物件。如要進一步瞭解如何使用離線功能,請參閱在 JavaScript 中啟用離線功能
移除(參照) 移除這個資料庫位置的資料。子位置中的所有資料也會一併刪除。系統會立即顯示移除的效果,以及對應的事件「value」移除項目與 Firebase 伺服器的同步處理作業也會啟動,完成後即可解決傳回的 Promise。如有提供,則同步處理完成後,即會以非同步方式呼叫 onComplete 回呼。
runTransaction(ref, transactionUpdate, 選項) 修改這個位置的資料。以個別的方式修改這個位置的資料。與一般的 set() 不同,它只會覆寫資料,不論其先前的值為何,runTransaction() 都可用來將現有值修改成新值,確保與其他寫入相同位置的用戶端沒有衝突。為此,您要傳遞用於將目前值轉換為新值的更新函式 runTransaction()。如果其他用戶端在成功寫入新值之前寫入位置,系統就會以新的目前值再次呼叫您的更新函式,並重試寫入。系統將重複進行這項操作,直到您的寫入成功沒有衝突,或是未傳回更新函式的值而取消交易為止。注意:透過 set() 修改資料時,會取消該位置的所有待處理交易。因此,如果混合使用 set()runTransaction() 來更新相同資料,請格外小心。注意:使用具有安全性與 Firebase 規則的交易時,除了執行 .write 交易外,還必須執行 .read 存取權才能執行 .write 交易。這是因為交易的用戶端性質需要用戶端讀取資料,然後才能進行交易更新。
set(ref, value) 將資料寫入這個資料庫位置。這項操作會覆寫這個位置和所有子位置的任何資料。系統會立即顯示寫入的效果,並觸發對應的事件 (「value」、「child_added」等)。也會啟動資料至 Firebase 伺服器的同步處理作業,完成時會傳回傳回的 Promise。如有提供,系統會在同步處理完成後,以非同步方式呼叫 onComplete 回呼。為新值傳遞 null 等同於呼叫 remove();也就是這個位置的所有資料和所有子位置都會遭到刪除。set() 將會移除儲存在這個位置的所有優先順序,因此如果希望保留優先順序,請改用 setWithPriority()請注意,使用 set() 修改資料時,會取消該位置的所有待處理交易,因此如果混用 set()transaction() 來修改相同的資料,請格外小心。單一 set() 會產生單一「值」事件。set()
setPriority(ref, 優先) 設定這個資料庫位置的資料優先順序。應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序及篩選資料)。
setWithPriority(ref, value, priority) 這個外掛程式能將資料寫入資料庫位置。與 set() 相同,但同時也指定該資料的優先順序。應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序及篩選資料)。
update(ref, 值) 一次將多個值寫入資料庫。values 引數包含多個屬性/值組合,這些值會一起寫入資料庫。每個子項屬性可以是簡單的屬性 (例如「名稱」),也可以是來自目前位置至要更新資料的相對路徑 (例如「name/first」)。set() 方法不同,update() 只能選擇性更新目前位置的參照屬性 (而不是取代目前位置的所有子屬性,而會立即觸發寫入的所有子項屬性)。也會啟動資料至 Firebase 伺服器的同步處理作業,完成時會傳回傳回的 Promise。如有提供,系統會在同步處理完成後,以非同步方式呼叫 onComplete 回呼。單一 update() 會產生單一「值」事件位置發生事件 (無論修改多少子項)。請注意,使用 update() 修改資料會取消該位置的所有待處理交易。因此,如果混合 update()transaction() 修改相同資料,請格外小心。null 傳送至 update() 會移除這個位置的資料。請參閱多位置更新簡介及其他功能update()
function(值, ...)
endAt(值, 鍵) 建立具有指定終點的 QueryConstraint使用 startAt()startAfter()endBefore()endAt()equalTo() 可讓您為查詢選擇任意的起點和終點。終點會包含在內,因此完全符合指定值的子項會納入查詢中。選用的鍵引數可用來進一步限制查詢的範圍。如有指定,其鍵名的鍵名也必須小於或等於指定鍵。如要進一步瞭解 endAt(),請參閱「篩選資料」一節
endBefore(值, 鍵) 建立具有指定終點 (不含) 的 QueryConstraint使用 startAt()startAfter()endBefore()endAt()equalTo() 可讓您為查詢選擇任意的起點和終點。終點除外。如果只提供一個值,系統會將值小於指定值的子項納入查詢中。如有指定鍵,則子項的值必須小於或等於指定值,且鍵名必須小於指定鍵。
equalTo(值, 值) 建立 QueryConstraint,其中包含符合指定值的子項。您可以使用 startAt()startAfter()endBefore()endAt()equalTo(),為查詢選擇任意的起點和終點。選用的鍵引數可用於進一步限制查詢的範圍。如果已指定,則具有明確指定值的子項,其鍵名也必須是確切的指定鍵。可用來篩選具有許多相符結果的結果集。如要進一步瞭解 equalTo(),請參閱篩選資料
startAfter(值, 鍵) 建立具有指定起點 (不含) 的 QueryConstraint使用 startAt()startAfter()endBefore()endAt()equalTo() 可讓您為查詢選擇任意的起點和終點。起始點除外。如果只提供值,系統會將值大於指定值的子項納入查詢中。如有指定鍵,則子項的值必須大於或等於指定值,且索引鍵名稱必須大於指定鍵。
startAt(值, 鍵) 以指定起點建立 QueryConstraint使用 startAt()startAfter()endBefore()endAt()equalTo() 可讓您針對查詢選擇任意的起點和終點。起點包括在內,因此完全符合指定值的子項會包含在查詢中。選用的鍵引數可用來進一步限制查詢的範圍。如果已指定,其鍵名也須大於或等於指定鍵。如要進一步瞭解 startAt(),請參閱「篩選資料」一節

類別

類別 說明
資料庫 代表 Firebase 即時資料庫的類別。
資料快照 DataSnapshot 包含資料庫位置中的資料。每當您讀取資料庫位置的資料時,您都會以 DataSnapshot 形式收到資料。DataSnapshot 會傳遞到您透過 on()once() 附加的事件回呼。您可以呼叫 val() 方法,將快照內容擷取為 JavaScript 物件。或者,您也可以呼叫 child() 傳回子快照 (之後可以呼叫 val()),藉此掃遍快照。DataSnapshot 是有效率地產生且不可變動的資料副本,位於資料庫位置。不可修改且永遠不會變更 (如要修改資料,您必須一律直接對 Reference 呼叫 set() 方法)。
中斷連線 onDisconnect 類別可讓您在用戶端與資料庫伺服器中斷連線時,寫入或清除資料。無論用戶端是否完全中斷連線,都會發生這些更新,因此即使連線中斷或用戶端當機,您仍可仰賴它們清理資料。onDisconnect 類別最常用來管理應用程式中的狀態,這有助於偵測已連線的用戶端數量,以及其他用戶端中斷連線的情況。詳情請參閱「在 JavaScript 中啟用離線功能」。為了避免在要求轉移至資料庫伺服器之前連線中斷而發生問題,應在寫入任何資料之前呼叫這些函式。請注意,onDisconnect 作業只會觸發一次。如果您希望在每次中斷連線時執行作業,就需在每次重新連線時重新建立 onDisconnect 作業。
QueryConstraint QueryConstraint 可用於縮小資料庫查詢傳回的文件組合。QueryConstraintQueryConstraint
交易結果 runTransaction() 的解析值類型。

介面

介面 說明
資料庫參考資料 DatabaseReference 代表資料庫中的特定位置,可用於對該資料庫位置讀取或寫入資料。您可以透過呼叫 ref()ref("child/path") 來參照資料庫中的根或子項位置。透過 set() 方法寫入,可透過 on*() 方法讀取。詳情請參閱 https://firebase.google.com/docs/database/web/read-and-write
IteratedDataSnapshot 代表疊代作業的 Reference 子項快照。金鑰一律不會處於未定義狀態。
ListenOptions 可用來自訂事件監聽器的選項物件。
查詢 Query 會在資料庫位置中排序及篩選資料,因此只會包含部分子項資料。這可用於依據某些屬性 (例如恐龍的高度) 來排序資料收集結果,以及將大量項目清單 (例如即時通訊訊息) 縮減為適合與用戶端同步的數字。將此處定義的一或多個篩選方法鏈結在一起,即可建立查詢。如同 DatabaseReference,您可以使用 on*() 方法從 Query 接收資料。您只會收到符合查詢的一部分資料的事件和 DataSnapshot詳情請參閱 https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data
AndableReference push() 傳回的 Promise 中,也可以做為 DatabaseReference 使用。參照會立即可用,且 Promise 會在寫入後端時解析。
交易選項 設定交易的選項物件。

型別別名

類型別名 說明
EventType 下列其中一個字串:「value」、「child_added」、「child_changed」、「child_removed」或「child_moved」。
QueryConstraintType 說明這個 SDK 中可用的不同查詢限制。
取消訂閱 可叫用以移除事件監聽器的回呼。

function(應用程式, ...)

getDatabase(應用程式, 網址)

傳回與所提供 FirebaseApp 相關聯的即時資料庫 SDK 執行個體。如果沒有任何執行個體,或現有執行個體使用自訂資料庫網址,則以預設設定初始化新執行個體。

簽名:

export declare function getDatabase(app?: FirebaseApp, url?: string): Database;

參數

參數 類型 說明
應用程式 Firebase 應用程式 傳回的即時資料庫執行個體與 FirebaseApp 執行個體相關聯。
網址 字串 要連線的即時資料庫執行個體網址。如未提供,SDK 會連線至 Firebase 應用程式的預設執行個體。

傳回:

資料庫

指定應用程式的 Database 例項。

function(db, ...)

linkDatabaseEmulator(db,主機、通訊埠、選項)

修改提供的執行個體,以便與即時資料庫模擬器通訊。

注意:執行任何其他作業前,必須先呼叫這個方法。

簽名:

export declare function connectDatabaseEmulator(db: Database, host: string, port: number, options?: {
    mockUserToken?: EmulatorMockTokenOptions | string;
}): void;

參數

參數 類型 說明
db 資料庫 要修改的執行個體。
主機 字串 模擬器主機 (例如:localhost)
通訊埠 數字 模擬器通訊埠 (例如:8080)
選項 { mockUserToken?:EmulatorMockTokenOptions |字串;}

傳回:

void

goOffline(db)

與伺服器中斷連線 (所有資料庫作業都會離線完成)。

用戶端會自動維持與資料庫伺服器之間的持續連線,而資料庫伺服器會無限期持續運作,並在中斷連線時重新連線。然而,在不需要持續連線的情況下,可以使用 goOffline()goOnline() 方法控制用戶端連線。

離線時,用戶端不會再收到資料庫的資料更新。不過,在本機執行的所有資料庫作業都會立即觸發事件,讓應用程式繼續正常運作。此外,在本機執行的各項作業都會自動排入佇列,在重新連線到資料庫伺服器後重試。

如要重新連線至資料庫並開始接收遠端事件,請參閱 goOnline()

簽名:

export declare function goOffline(db: Database): void;

參數

參數 類型 說明
db 資料庫 要中斷連線的執行個體。

傳回:

void

goOnline(db)

重新連線至伺服器,並將離線資料庫狀態同步處理至伺服器狀態。

停用與 goOffline() 的有效連線後,應使用這個方法。重新連線後,用戶端就會傳輸正確的資料並觸發相應的事件,以便用戶端「盡快」。

簽名:

export declare function goOnline(db: Database): void;

參數

參數 類型 說明
db 資料庫 要重新連線的執行個體。

傳回:

void

ref(db, path)

傳回 Reference,代表資料庫中與指定路徑相對應的位置。如果未提供路徑,Reference 會指向資料庫的根目錄。

簽名:

export declare function ref(db: Database, path?: string): DatabaseReference;

參數

參數 類型 說明
db 資料庫 要取得參照的資料庫執行個體。
路徑 字串 選用路徑,代表傳回的 Reference 會指向的位置。如未提供,傳回的 Reference 會指向資料庫的根目錄。

傳回:

資料庫參考資料

如果提供路徑,會指向提供路徑的 Reference。否則,Reference 會指向資料庫根目錄。

refFromURL(db, url)

傳回 Reference,代表資料庫中與所提供 Firebase 網址相對應的位置。

如果網址不是有效的 Firebase 資料庫網址,或是網址與目前的 Database 執行個體不同,就會擲回例外狀況。

請注意,所有查詢參數 (orderBylimitToLast 等) 都會遭到忽略,且不會套用至傳回的 Reference

簽名:

export declare function refFromURL(db: Database, url: string): DatabaseReference;

參數

參數 類型 說明
db 資料庫 要取得參照的資料庫執行個體。
網址 字串 傳回的 Reference 將指向的 Firebase 網址。

傳回:

資料庫參考資料

指向提供的 Firebase 網址的 Reference

function()

forceLongPolling()

強制使用 longPolling 而非 websocket。如果 websocket 通訊協定用於 databaseURL,系統會忽略這個通訊協定。

簽名:

export declare function forceLongPolling(): void;

傳回:

void

forceWebSockets()

強制使用 websocket,而非 longPolling。

簽名:

export declare function forceWebSockets(): void;

傳回:

void

orderByKey()

建立依照鍵排序的新 QueryConstraint

按照查詢結果的鍵/值遞增排序。

如要進一步瞭解 orderByKey(),請參閱「排序資料」。

簽名:

export declare function orderByKey(): QueryConstraint;

傳回:

QueryConstraint

orderByPriority()

建立依照優先順序排列的新 QueryConstraint

應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序資料以瞭解優先順序的替代方式)。

簽名:

export declare function orderByPriority(): QueryConstraint;

傳回:

QueryConstraint

orderByValue()

建立依照值排序的新 QueryConstraint

如果查詢的子項都是純量值 (字串、數字或布林值),您可以根據結果 (遞增) 值排序結果。

如要進一步瞭解 orderByValue(),請參閱「排序資料」。

簽名:

export declare function orderByValue(): QueryConstraint;

傳回:

QueryConstraint

伺服器時間戳記()

傳回預留位置值,以自動填入目前時間戳記 (自 Unix 紀元以來經過的時間,以毫秒為單位),由 Firebase 伺服器決定。

簽名:

export declare function serverTimestamp(): object;

傳回:

物件

function(delta, ...)

increment(delta)

傳回預留位置值,您可以使用所提供的差異值,以不可分割的形式遞增目前的資料庫值。

簽名:

export declare function increment(delta: number): object;

參數

參數 類型 說明
Delta 數字 修改目前值的總和

傳回:

物件

以不可分割的形式在伺服器端修改資料的預留位置值。

function(已啟用, ...)

enableLogging(已啟用、永久)

將偵錯資訊記錄到控制台。

簽名:

export declare function enableLogging(enabled: boolean, persistent?: boolean): any;

參數

參數 類型 說明
已啟用 布林值 如果為 true 則啟用記錄功能,如果 false 則停用記錄功能。
永久 布林值 如果 true,系統會記住頁面重新整理之間的記錄狀態。

傳回:

不限

function(限制, ...)

limitToFirst(限制)

如果限制只有第一個特定子項數量,會建立新的 QueryConstraint

limitToFirst() 方法可用來設定特定回呼要同步處理的子項數量上限。如果將上限設為 100,一開始我們最多只會收到 100 個 child_added 事件。如果資料庫儲存的訊息少於 100 則,每則訊息都會觸發 child_added 事件。但是,如果訊息超過 100 則,我們只會收到前 100 則已排序訊息的 child_added 事件。隨著項目有所改變,我們會針對從有效清單上的每個項目收到 child_removed 事件,讓總數維持在 100 件。

如要進一步瞭解 limitToFirst(),請參閱「篩選資料」。

簽名:

export declare function limitToFirst(limit: number): QueryConstraint;

參數

參數 類型 說明
限制 數字 要納入這項查詢的節點數量上限。

傳回:

QueryConstraint

limitToLast(限制)

建立限制只傳回最後指定數量子項的新 QueryConstraint

limitToLast() 方法可用來設定特定回呼要同步處理的子項數量上限。如果將上限設為 100,一開始我們最多只會收到 100 個 child_added 事件。如果資料庫儲存的訊息少於 100 則,每則訊息都會觸發 child_added 事件。但是,如果有超過 100 則訊息,我們只會收到最近 100 則已排序訊息的 child_added 事件。隨著項目有所改變,我們會針對從有效清單上的每個項目收到 child_removed 事件,讓總數維持在 100 件。

如要進一步瞭解 limitToLast(),請參閱「篩選資料」。

簽名:

export declare function limitToLast(limit: number): QueryConstraint;

參數

參數 類型 說明
限制 數字 要納入這項查詢的節點數量上限。

傳回:

QueryConstraint

函式(記錄器, ...)

enableLogging(記錄器)

將偵錯資訊記錄到控制台。

簽名:

export declare function enableLogging(logger: (message: string) => unknown): any;

參數

參數 類型 說明
Logger (訊息:字串) =>不明 自訂記錄器函式,可控制系統記錄資料的方式。

傳回:

不限

function(父項, ...)

子項(父項, 路徑)

針對指定相對路徑中的位置,取得 Reference

相對路徑可以是簡單的子項名稱 (例如「ada」),或是更深入的斜線分隔路徑 (例如「ada/name/first」)。

簽名:

export declare function child(parent: DatabaseReference, path: string): DatabaseReference;

參數

參數 類型 說明
parent 資料庫參考資料 父項位置。
路徑 字串 從這個位置到所需子位置的相對路徑。

傳回:

資料庫參考資料

指定的子位置。

Push(父項, 值)

使用專屬金鑰產生新的子項位置,並傳回其 Reference

這是在項目集合中新增資料最常見的模式。

如果您在 push() 提供值,該值會寫入產生的位置。如未傳遞值,系統就不會將任何內容寫入資料庫,而子項則會保持空白 (但您可以在其他位置使用 Reference)。

push() 產生的專屬索引鍵會依目前時間排序,因此產生的項目清單會按照時間排序。這些按鍵也經過設計,而且容易辨識 (內含 72 位元的熵)。

請參閱「附加至資料清單」。請參閱「2^120 確保專屬 ID 的方法

簽名:

export declare function push(parent: DatabaseReference, value?: unknown): ThenableReference;

參數

參數 類型 說明
parent 資料庫參考資料 父項位置。
不明 要在產生的位置寫入的選用值。

傳回:

AndableReference

合併 PromiseReference;會在寫入完成後解析,但可以立即做為子項位置的 Reference 使用。

function(路徑, ...)

orderByChild(路徑)

建立新的 QueryConstraint,按指定子項鍵排序。

在查詢中,一次只能依一個鍵排序查詢。在同一查詢中多次呼叫 orderByChild() 會發生錯誤。

Firebase 查詢可讓您依據任何子項鍵即時排序資料。不過,如果您事先知道索引目標,可以透過安全性規則中的 .indexOn 規則加以定義,藉此提高效能。詳情請參閱 https://firebase.google.com/docs/database/security/indexing-data 規則。

如要進一步瞭解 orderByChild(),請參閱「排序資料」。

簽名:

export declare function orderByChild(path: string): QueryConstraint;

參數

參數 類型 說明
路徑 字串 排序依據的路徑。

傳回:

QueryConstraint

function(查詢, ...)

get(查詢)

取得這項查詢的最新結果。

簽名:

export declare function get(query: Query): Promise<DataSnapshot>;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。

傳回:

Promise<DataSnapshot>

Promise,如果有值可用,就會解析為產生的 DataSnapshot,如果用戶端無法傳回值 (例如無法連上伺服器,且沒有快取內容) 就會拒絕。

off(query, eventType, 回呼)

卸離先前附加至對應 on*() (onValueonChildAdded) 事件監聽器的回呼。注意:這不是移除事件監聽器的建議方式。請改用各 on* 回呼傳回的回呼函式。

卸離先前附加至 on*() 的回呼。對父項事件監聽器呼叫 off() 不會自動移除在子節點上註冊的事件監聽器,也必須在任何子項事件監聽器上呼叫 off() 才能移除回呼。

如果未指定回呼,系統會移除指定 eventType 的所有回呼。同樣地,如未指定 eventType,系統會移除 Reference 的所有回呼。

您也可以叫用取消訂閱回呼來移除個別事件監聽器。

簽名:

export declare function off(query: Query, eventType?: EventType, callback?: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown): void;

參數

參數 類型 說明
查詢 查詢 註冊監聽器的查詢。
eventType EventType 下列其中一個字串:「value」、「child_added」、「child_changed」、「child_removed」或「child_moved」。如果省略,系統會移除 Reference 的所有回呼。
回呼 (快照:DataSnapshot,previousChildName?: string | null) =>不明 傳遞至 on()undefined 的回呼函式會移除所有回呼。

傳回:

void

onChildAdded(query, 回呼, cancelCallback)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

這個位置的每個初始子項都會觸發一次 onChildAdded 事件,且每次新增子項時都會再次觸發。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName?: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName?: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildAdded(query, 回呼, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

這個位置的每個初始子項都會觸發一次 onChildAdded 事件,且每次新增子項時都會再次觸發。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildAdded(query, 回呼, cancelCallback, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

這個位置的每個初始子項都會觸發一次 onChildAdded 事件,且每次新增子項時都會再次觸發。傳入回呼的 DataSnapshot 會反映相關子項的資料。為方便排序,系統會傳遞第二個引數,這是一個字串,該字串包含按排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildAdded(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildChanged(query, 回呼, cancelCallback)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。

簽名:

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildChanged(query, 回呼, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。

簽名:

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildChanged(query, 回呼, cancelCallback, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當儲存在子項 (或其任何子系) 中的資料有所變更時,就會觸發 onChildChanged 事件。請注意,單一 child_changed 事件可能代表子項有多項變更。傳遞至回呼的 DataSnapshot 會包含新的子項內容。為了排序,回呼也會傳遞第二個引數,這個字串包含依排序順序排序的前一個同層子項鍵;或 null (如果為第一個子項)。

簽名:

export declare function onChildChanged(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildMoved(query, 回呼, cancelCallback)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當子項的排序順序改變,使得其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildMoved(查詢, 回呼, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當子項的排序順序改變,使得其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildMoved(query, 回呼, cancelCallback, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

當子項的排序順序改變,使得其相對於同層級之間的位置有所改變時,就會觸發 onChildMoved 事件。傳遞至回呼的 DataSnapshot 適用於已移動的子項資料。也會傳遞第二個引數,這個字串包含依排序順序列出前一個同層子項的鍵;如果為第一個子項,則會傳遞 null

簽名:

export declare function onChildMoved(query: Query, callback: (snapshot: DataSnapshot, previousChildName: string | null) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot,previousChildName: string | null) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildRemoved(query, 回呼, cancelCallback)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

每次移除子項時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。如有下列情況,系統會移除孩子:

  • 用戶端明確呼叫該子項或其其中一個祖系的 remove() - 用戶端對該子項或其其中一個祖系呼叫 set(null) (該子項已將其所有子項全部移除),具有一項查詢可被篩選掉子項 (因為其排序順序已變更或達到上限)

簽名:

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildRemoved(query, 回呼, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

每次移除子項時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。如有下列情況,系統會移除孩子:

  • 用戶端明確呼叫該子項或其其中一個祖系的 remove() - 用戶端對該子項或其其中一個祖系呼叫 set(null) (該子項已將其所有子項全部移除),具有一項查詢可被篩選掉子項 (因為其排序順序已變更或達到上限)

簽名:

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onChildRemoved(query, 回呼, cancelCallback, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

每次移除子項時,系統都會觸發 onChildRemoved 事件。傳入回呼的 DataSnapshot 會是已移除的子項舊資料。如有下列情況,系統會移除孩子:

  • 用戶端明確呼叫該子項或其其中一個祖系的 remove() - 用戶端對該子項或其其中一個祖系呼叫 set(null) (該子項已將其所有子項全部移除),具有一項查詢可被篩選掉子項 (因為其排序順序已變更或達到上限)

簽名:

export declare function onChildRemoved(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。系統會依排序順序傳遞 DataSnapshot 和一個包含前一個子項鍵的字串;如果為第一個子項,則會傳遞 null
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onValue(query, 回呼, cancelCallback)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

onValue 事件會在這個位置儲存初始資料時觸發一次,然後在資料有變更時再次觸發。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。

簽名:

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback?: (error: Error) => unknown): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。回呼會傳遞 DataSnapshot。
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onValue(查詢, 回呼, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

onValue 事件會在這個位置儲存初始資料時觸發一次,然後在資料有變更時再次觸發。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。

簽名:

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。回呼會傳遞 DataSnapshot。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

onValue(查詢, 回呼, cancelCallback, 選項)

監聽特定位置的資料變更。

這是讀取資料庫資料的主要方式。系統會針對初始資料觸發回呼,在資料變更時再次觸發回呼。叫用傳回的取消訂閱回呼,即可停止接收更新。詳情請參閱在網路上擷取資料

onValue 事件會在這個位置儲存初始資料時觸發一次,然後在資料有變更時再次觸發。傳遞至回呼的 DataSnapshot 會用於呼叫 on() 的位置。在所有內容完成同步後,觸發條件才會觸發。如果營業地點沒有任何資料,就會以空白的 DataSnapshot 觸發 (val() 會傳回 null)。

簽名:

export declare function onValue(query: Query, callback: (snapshot: DataSnapshot) => unknown, cancelCallback: (error: Error) => unknown, options: ListenOptions): Unsubscribe;

參數

參數 類型 說明
查詢 查詢 要執行的查詢。
回呼 (快照:DataSnapshot) =>不明 指定事件發生時觸發的回呼。回呼會傳遞 DataSnapshot。
cancelCallback (錯誤:錯誤) =>不明 活動訂閱遭取消時,如果因為您的用戶端沒有讀取此資料的權限 (或具有權限但現在遺失權限),您將會收到選用的回呼。這個回呼會傳遞 Error 物件,指出失敗的原因。
選項 ListenOptions 可用來設定 onlyOnce 的物件,會在首次叫用後移除事件監聽器。

傳回:

取消訂閱

可叫用此函式來移除事件監聽器。

query(query, queryConstraints)

建立 Query 的不可變新例項,該例項的擴充為一併包含其他查詢限制。

簽名:

export declare function query(query: Query, ...queryConstraints: QueryConstraint[]): Query;

參數

參數 類型 說明
查詢 查詢 要做為新限制基礎的 Query 執行個體。
queryConstraints 查詢限制[] 要套用的 QueryConstraint 清單。

傳回:

查詢

例外狀況

,表示其中任一查詢限制無法與現有或新限制合併使用。

function(參照, ...)

中斷連線(參考)

傳回 OnDisconnect 物件。如要進一步瞭解如何使用離線功能,請參閱在 JavaScript 中啟用離線功能

簽名:

export declare function onDisconnect(ref: DatabaseReference): OnDisconnect;

參數

參數 類型 說明
參考資料 資料庫參考資料 用於新增 OnConnected 觸發條件的參考資料。

傳回:

中斷連線

移除(參照)

移除這個資料庫位置的資料。

所有位於子地點的資料也會一併刪除。

系統會立即顯示移除效果和對應的事件「value」移除項目與 Firebase 伺服器的同步處理作業也會啟動,完成後即可解決傳回的 Promise。如有提供,則同步處理完成後,即會以非同步方式呼叫 onComplete 回呼。

簽名:

export declare function remove(ref: DatabaseReference): Promise<void>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要移除的地點。

傳回:

承諾<void>

完成伺服器中的移除作業後就會解決。

runTransaction(ref, transactionUpdate, options)

以整體化的方式修改這個位置的資料。

修改這個位置的資料。與一般的 set() 不同,它只會覆寫資料 (不論其先前的值為何),runTransaction() 是用於將現有值修改為新值,以確保同時與其他用戶端寫入相同位置的內容不會發生衝突。

為了完成這項工作,您需要傳遞更新函式 runTransaction(),用來將目前值轉換為新值。如果其他用戶端在成功寫入新值之前寫入位置,系統就會以新的目前值再次呼叫您的更新函式,並重試寫入。這會重複進行,直到寫入成功沒有衝突,或您未從更新函式傳回值而取消交易為止。

簽名:

export declare function runTransaction(ref: DatabaseReference, transactionUpdate: (currentData: any) => unknown, options?: TransactionOptions): Promise<TransactionResult>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要個別修改的位置。
交易更新 (currentData:any) =>不明 開發人員提供的函式,會將目前儲存在這個位置的資料以 JavaScript 物件的形式傳遞。此函式應傳回要寫入的新值 (以 JavaScript 物件形式表示)。如果傳回 undefined (也就是沒有引數傳回),交易就會取消,這個位置的資料也不會修改。
選項 交易選項 設定交易的選項物件。

傳回:

Promise<TransactionResult>

您可以視需要使用 Promise,而不是 onComplete 回呼來處理成功和失敗。

set(ref, 值)

將資料寫入這個資料庫位置。

這項操作會覆寫這個位置及所有子位置的所有資料。

系統會立即顯示寫入的效果,並觸發相應的事件 (「value」、「child_added」等)。也會啟動資料至 Firebase 伺服器的同步處理作業,完成時會傳回傳回的 Promise。如有提供,系統會在同步處理完成後,以非同步方式呼叫 onComplete 回呼。

為新值傳遞 null 等同於呼叫 remove();也就是說,這個位置和所有子位置的所有資料都會遭到刪除。

set() 會移除儲存在這個位置的所有優先順序,因此如果要保留優先順序,就必須改用 setWithPriority()

請注意,使用 set() 修改資料將取消該位置的所有待處理交易,因此如果混合使用 set()transaction() 修改相同的資料,請格外小心。

單一 set() 會產生單一「值」事件。set()

簽名:

export declare function set(ref: DatabaseReference, value: unknown): Promise<void>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要寫入的位置。
不明 要寫入的值 (字串、數字、布林值、物件、陣列或空值)。

傳回:

承諾<void>

寫入伺服器後就會解決。

setPriority(ref, 優先)

設定這個資料庫位置資料的優先順序。

應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序及篩選資料)。

簽名:

export declare function setPriority(ref: DatabaseReference, priority: string | number | null): Promise<void>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要寫入的位置。
優先順序 字串 |數字 |空值 要寫入的優先順序 (字串、數字或空值)。

傳回:

承諾<void>

寫入伺服器後就會解決。

setWithPriority(ref, 值, 優先)

這個外掛程式能將資料寫入資料庫位置。和 set() 一樣,但也會指定該資料的優先順序。

應用程式不需使用優先順序,但可以按照一般屬性排序集合 (請參閱排序及篩選資料)。

簽名:

export declare function setWithPriority(ref: DatabaseReference, value: unknown, priority: string | number | null): Promise<void>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要寫入的位置。
不明 要寫入的值 (字串、數字、布林值、物件、陣列或空值)。
優先順序 字串 |數字 |空值 要寫入的優先順序 (字串、數字或空值)。

傳回:

承諾<void>

寫入伺服器後就會解決。

update(ref, 值)

一次將多個值寫入資料庫。

values 引數包含多個屬性/值組合,這些值會一起寫入資料庫。每個子項屬性可以是簡單的屬性 (例如「名稱」),也可以是目前位置到待更新資料的相對路徑 (例如「name/first」)。

set() 方法不同,update() 可用於選擇性地更新目前位置的參照屬性 (而非取代目前位置的所有子項屬性)。

系統會立即顯示寫入的效果,並觸發對應的事件 (「value」、「child_added」等)。也會啟動資料至 Firebase 伺服器的同步處理作業,完成時會傳回傳回的 Promise。如有提供,系統會在同步處理完成後,以非同步方式呼叫 onComplete 回呼。

單一 update() 會產生單一「值」事件,無論修改子項數量為何,都會在執行 update() 的位置發生事件。

請注意,使用 update() 修改資料將取消該位置的所有待處理交易,因此如果混合使用 update()transaction() 修改相同的資料,請格外小心。

如果將 null 傳遞至 update(),系統將移除這個位置的資料。

請參閱「隆重推出多位置更新和其他功能」。

簽名:

export declare function update(ref: DatabaseReference, values: object): Promise<void>;

參數

參數 類型 說明
參考資料 資料庫參考資料 要寫入的位置。
物件 包含多個值的物件。

傳回:

承諾<void>

伺服器更新完畢後就會解決。

function(值, ...)

endAt(值, 鍵)

建立具有指定終點的 QueryConstraint

使用 startAt()startAfter()endBefore()endAt()equalTo() 時,您可以任意選擇查詢的起點和終點,

終點包含,因此完全符合指定值的子項會納入查詢中。選用的鍵引數可用來進一步限制查詢的範圍。如有指定,則具有特定指定值的子項鍵名也必須小於或等於指定鍵。

如要進一步瞭解 endAt(),請參閱「篩選資料」。

簽名:

export declare function endAt(value: number | string | boolean | null, key?: string): QueryConstraint;

參數

參數 類型 說明
數字 |字串 |布林值 |空值 結尾的值。引數類型視這項查詢中使用的 orderBy() 函式而定。指定與 orderBy() 類型相符的值。與 orderByKey() 搭配使用時,值必須是字串。
金鑰 字串 結束位置的子項鍵,位於具有先前指定優先順序的子項之間。只有依照子項、值或優先順序排序時,才能使用這個引數。

傳回:

QueryConstraint

endBefore(值, 鍵)

建立具有指定終點 (不含) 的 QueryConstraint

使用 startAt()startAfter()endBefore()endAt()equalTo() 時,您可以任意選擇查詢的起點和終點,

終點不含終點。如果只提供一個值,系統會將值小於指定值的子項納入查詢中。如有指定鍵,則子項的值必須小於或等於指定值,且鍵名必須小於指定鍵。

簽名:

export declare function endBefore(value: number | string | boolean | null, key?: string): QueryConstraint;

參數

參數 類型 說明
數字 |字串 |布林值 |空值 要做為結尾的值。引數類型視這項查詢中使用的 orderBy() 函式而定。指定與 orderBy() 類型相符的值。與 orderByKey() 搭配使用時,值必須是字串。
金鑰 字串 要在先前指定優先順序的子項之間結束的子項鍵。只有依照子項、值或優先順序排序時,才能使用這個引數。

傳回:

QueryConstraint

equalTo(值, 鍵)

建立 QueryConstraint,其中包含符合指定值的子項。

使用 startAt()startAfter()endBefore()endAt()equalTo() 時,您可以任意選擇查詢的起點和終點,

選用的鍵引數可用來進一步限制查詢的範圍。如果已指定,則具有明確指定值的子項,其鍵名也必須是確切的指定鍵。可用來篩選具有許多相符結果的結果集。

如要進一步瞭解 equalTo(),請參閱「篩選資料」。

簽名:

export declare function equalTo(value: number | string | boolean | null, key?: string): QueryConstraint;

參數

參數 類型 說明
數字 |字串 |布林值 |空值 要比對的值。引數類型視這項查詢中使用的 orderBy() 函式而定。指定與 orderBy() 類型相符的值。與 orderByKey() 搭配使用時,值必須是字串。
金鑰 字串 要從先前指定優先順序的子項開始的子項鍵。只有依照子項、值或優先順序排序時,才能使用這個引數。

傳回:

QueryConstraint

startAfter(值, 鍵)

建立具有指定起點 (不含) 的 QueryConstraint

使用 startAt()startAfter()endBefore()endAt()equalTo() 時,您可以任意選擇查詢的起點和終點,

起點不含在內。如果只提供值,系統會將值大於指定值的子項納入查詢中。如有指定鍵,則子項的值必須大於或等於指定值,且索引鍵名稱必須大於指定鍵。

簽名:

export declare function startAfter(value: number | string | boolean | null, key?: string): QueryConstraint;

參數

參數 類型 說明
數字 |字串 |布林值 |空值 起始值。引數類型視這項查詢中使用的 orderBy() 函式而定。指定與 orderBy() 類型相符的值。與 orderByKey() 搭配使用時,值必須是字串。
金鑰 字串 之後要啟動的子項金鑰。只有依照子項、值或優先順序排序時,才能使用這個引數。

傳回:

QueryConstraint

startAt(值, 鍵)

建立具有指定起點的 QueryConstraint

使用 startAt()startAfter()endBefore()endAt()equalTo() 時,您可以任意選擇查詢的起點和終點,

起點包含在內,因此完全符合指定值的子項會納入查詢中。選用的鍵引數可用來進一步限制查詢的範圍。如有指定,則具有特定指定值的子項鍵名也必須大於或等於指定鍵。

如要進一步瞭解 startAt(),請參閱「篩選資料」。

簽名:

export declare function startAt(value?: number | string | boolean | null, key?: string): QueryConstraint;

參數

參數 類型 說明
數字 |字串 |布林值 |空值 起始值。引數類型視這項查詢中使用的 orderBy() 函式而定。指定與 orderBy() 類型相符的值。與 orderByKey() 搭配使用時,值必須是字串。
金鑰 字串 初始的子項金鑰。只有依照子項、值或優先順序排序時,才能使用這個引數。

傳回:

QueryConstraint

EventType

下列其中一個字串:「value」、「child_added」、「child_changed」、「child_removed」或「child_moved」。

簽名:

export declare type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed';

查詢限制類型

說明這個 SDK 中可用的不同查詢限制。

簽名:

export declare type QueryConstraintType = 'endAt' | 'endBefore' | 'startAt' | 'startAfter' | 'limitToFirst' | 'limitToLast' | 'orderByChild' | 'orderByKey' | 'orderByPriority' | 'orderByValue' | 'equalTo';

取消訂閱

可叫用以移除事件監聽器的回呼。

簽名:

export declare type Unsubscribe = () => void;