@firebase/firestore

函式

函式 說明
功能(應用程式, ...)
getFirestore(應用程式) 傳回與所提供 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
getFirestore(應用程式, 資料庫 ID) (Beta 版) 傳回與所提供 FirebaseApp 相關聯的現有已命名 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
InitialFirestore(應用程式, 設定, 資料庫 ID) 使用提供的設定初始化新的 Firestore 例項。只能在其他函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()
功能(Firestore, ...)
clearIndexedDbPersistence(Firestore) 清除永久儲存空間。這包含待處理的寫入和快取文件。Firestore 執行個體未啟動 (應用程式終止或應用程式首次初始化時) 時,您必須呼叫此項目。啟動時,必須先呼叫這個函式,然後再呼叫其他函式 (不含 initializeFirestore()getFirestore())。如果 Firestore 執行個體仍在執行,承諾會遭到拒絕,並顯示錯誤代碼 failed-precondition注意:clearIndexedDbPersistence() 主要用於協助編寫使用 Cloud Firestore 的可靠測試。它使用高效率的機制捨棄現有資料,但不會嘗試安全覆寫或導致快取資料無法復原。如果應用程式需要在使用者工作階段之間揭露快取資料非常敏感,則強烈建議不要啟用持續性。
collection(Firestore, path, pathSegments) 取得參照指定絕對路徑集合的 CollectionReference 例項。
collectionGroup(firestore, collectionId) 建立並傳回新的 Query 執行個體,其中包含資料庫中含有指定 collectionId 的集合或子集合中的所有文件。
connectFirestoreEmulator(Firestore、主機、通訊埠、選項) 請修改這個執行個體,以便與 Cloud Firestore 模擬器通訊。注意:在使用這個執行個體執行任何作業前,必須先呼叫這個執行個體。
disableNetwork(Firestore) 停用這個執行個體的網路用量。您可以透過 enableNetwork() 重新啟用這項功能。網路停用時,所有快照事件監聽器、getDoc()getDocs() 呼叫都會從快取傳回結果,所有寫入作業都會排入佇列,直到網路恢復運作為止。
doc(Firestore, path, pathSegments) 取得參照指定絕對路徑文件的 DocumentReference 例項。
enableIndexedDbPersistence(firestore, 持續性設定) 嘗試啟用永久儲存空間 (如果可能)。失敗時,enableIndexedDbPersistence() 會拒絕承諾或擲回例外狀況。失敗的原因有很多,可透過「code」來找出錯誤。* 失敗前提條件:應用程式已在其他瀏覽器分頁中開啟,* 未實作:瀏覽器與離線持續性實作不相容。請注意,即使作業失敗,Firestore 執行個體仍可使用,但離線保留功能會隨即停用。注意:enableIndexedDbPersistence() 必須在呼叫其他任何函式之前呼叫 (InitialFirestore()getFirestore()clearIndexedDbPersistence() 環境無法使用)。永久使用環境
enableMultiTabIndexedDbPersistence(Firestore) 嘗試啟用多分頁永久儲存空間 (如果可能)。如果在所有分頁中啟用此設定,所有作業都會共用本機持續性存取權,包括共用查詢執行,以及在所有連線執行個體中因延遲而導致本機文件更新作業延遲。如果失敗,enableMultiTabIndexedDbPersistence() 會拒絕承諾或擲回例外狀況。導致這項作業失敗的原因有很多,可透過「code」找出錯誤。* 失敗的先決條件:應用程式已在其他瀏覽器分頁中開啟,且未啟用多分頁。* 無法使用:瀏覽器與離線持續性實作功能不相容。請注意,即使失敗後,Firestore 執行個體仍可使用,但離線保留功能會遭到停用。
enableNetwork(Firestore) 事先呼叫 disableNetwork() 後,讓這個 Firestore 執行個體使用網路。
getPersistentCacheIndexManager(firestore) 傳回指定 Firestore 物件使用的 PersistentCache Index Manager。PersistentCacheIndexManager 執行個體或 null (如果本機永久儲存空間未使用)。
loadBundle(firestore, bundleData) 將 Firestore 套件載入本機快取。
namedQuery(Firestore, name) 這個外掛程式能從本機快取讀取 Firestore 查詢 (以指定名稱識別)。命名的查詢會封裝至伺服器端的套件 (與產生的文件),並使用 loadBundle 載入至本機快取。進入本機快取後,請使用這個方法依名稱擷取 Query
onSnapshotsInSync(firestore, 觀察器) 針對同步快照事件附加事件監聽器。「同步快照」事件表示,受特定變更影響的所有事件監聽器皆已觸發,即使單一伺服器產生的變更會影響多個事件監聽器。注意:同步快照事件僅表示事件監聽器彼此同步,但與這些快照是否與伺服器保持同步無關。在個別事件監聽器中使用 SnapshotMetadata,以判斷快照是來自快取還是伺服器。
onSnapshotsInSync(firestore, onSync) 針對同步快照事件附加事件監聽器。「同步快照」事件表示,受特定變更影響的所有事件監聽器皆已觸發,即使單一伺服器產生的變更會影響多個事件監聽器。注意:同步快照事件僅表示事件監聽器彼此同步,但與這些快照是否與伺服器保持同步無關。在個別事件監聽器中使用 SnapshotMetadata,判斷快照是來自快取還是伺服器。
runTransaction(firestore, updateFunction, options) 執行指定的 updateFunction,然後嘗試修訂交易中套用的變更。如果在交易中讀取過任何文件,Cloud Firestore 會重試 updateFunction。如果嘗試 5 次後仍無法修訂,交易就會失敗。單一交易中允許的寫入數量上限為 500。
setIndexConfiguration(firestore, configuration) (Beta 版) 為本機查詢執行作業設定索引。系統會覆寫所有先前的索引設定。在持續保留索引設定後,Promise 就會解析。索引項目本身會以非同步方式建立。即使目前無法提供索引,您還是可以繼續使用需要建立索引的查詢。寫入索引項目後,查詢執行作業將自動開始使用索引。只有 IndexedDb 持續性支援索引。如果未啟用 IndexedDb,系統會忽略所有索引設定。
setIndexConfiguration(firestore, json) (Beta 版) 為本機查詢執行作業設定索引。系統會覆寫所有先前的索引設定。在持續保留索引設定後,Promise 就會解析。索引項目本身會以非同步方式建立。即使目前無法提供索引,您還是可以繼續使用需要建立索引的查詢。寫入索引項目後,查詢執行作業將自動開始使用索引。只有 IndexedDb 持續性支援索引。設定索引設定前,請先叫用 enableIndexedDbPersistence()enableMultiTabIndexedDbPersistence()。如果未啟用 IndexedDb,系統會忽略所有索引設定。此方法接受由 Firebase CLI (firebase firestore:indexes) 匯出的 JSON 格式。如果 JSON 格式無效,這個方法會擲回錯誤。
終止(火災) 終止提供的 Firestore 執行個體。呼叫 terminate() 後,只能使用 clearIndexedDbPersistence() 函式。任何其他函式都會擲回 FirestoreError如要在終止後重新啟動,請使用 getFirestore() 建立新的 FirebaseFirestore 執行個體。不會等待解決的寫入作業,也不會因等待伺服器作業而遭終止。啟用持續性後,下次啟動這個執行個體時,系統就會繼續將寫入作業傳送至伺服器。注意:在正常情況下,不需要呼叫 terminate()。只有當您想強制這個執行個體釋出所有資源,或是與 clearIndexedDbPersistence() 搭配運用,以確保在測試執行之間刪除所有本機狀態時,這個函式才能派上用場。
waitForPendingWrites(Firestore) 等候後端確認有效使用者所有目前待處理的寫入作業。如果沒有待處理的寫入作業,傳回的承諾會立即解決。否則,承諾會等待所有先前核發的寫入作業 (包括先前應用程式工作階段中寫入的寫入作業),但不會等待呼叫函式之後新增的寫入作業。如要等待其他寫入作業,請再次呼叫 waitForPendingWrites()任何尚未解決的 waitForPendingWrites() 承諾會在使用者變更期間遭到拒絕。
writeBatch(Firestore) 建立寫入批次,用來以單一不可分割作業的形式執行多次寫入。單一 WriteBatch 允許的寫入數量上限為 500。與交易不同的是,寫入批次會維持在離線狀態,因此如果您不需要針對讀取資料設定寫入條件,建議使用此做法。
function()
count() 建立 AggregateField 物件,以計算查詢結果集中的文件數量。
deleteField() 傳回一個 sendinel 與 updateDoc()setDoc(){merge: true},用於標示要刪除的欄位。
documentId() 傳回特殊的印記 FieldPath,用來參照文件 ID。可在查詢中使用,依文件 ID 排序或篩選。
getFirestore() 傳回與預設 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
memoryEagerGarbageCollector() 建立 MemoryEagerGarbageCollector 的執行個體。除非另有明確指定,否則這也是預設的垃圾收集器。
PersistentMultipleTabManager() 建立 PersistentMultipleTabManager 的執行個體。
serverTimestamp() 傳回與 setDoc()updateDoc() 搭配使用的 insinel,在寫入的資料中加入伺服器產生的時間戳記。
function(databaseId, ...)
getFirestore(databaseId) (Beta 版) 傳回與預設 FirebaseApp 相關聯的已命名 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
功能(元素, ...)
arrayRemove(元素) 傳回可以與 setDoc() 搭配使用的特殊值,或指示伺服器從伺服器上現有的任何陣列值中移除指定元素。系統會從陣列中移除每個指定元素的所有例項。如果修改的欄位尚未是陣列,則會以空白陣列覆寫。
arrayUnion(元素) 傳回可以與 setDoc()updateDoc() 搭配使用的特殊值,指示伺服器將特定元素與伺服器上現有的任何陣列值建立聯集。陣列中沒有的指定元素都會新增到結尾。如果修改的欄位尚未是陣列,則會以包含完全指定元素的陣列覆寫該欄位。
function(field, ...)
average(field) 建立 AggregateField 物件,以計算查詢結果集內某範圍文件的平均值。
sum(欄位) 建立 AggregateField 物件,以便計算查詢結果集中指定欄位內指定欄位的總和。
function(fieldPath, ...)
orderBy(fieldPath, directStr) 建立 QueryOrderByConstraint 會依據指定欄位將查詢結果排序 (選擇遞減排序而非遞增)。注意:不含指定欄位的文件不會顯示在查詢結果中。
where(fieldPath, opStr, value) 建立 QueryFieldFilterConstraint,要求文件必須包含指定欄位,且值應符合提供的關聯限制。
function(fieldValues, ...)
endAt(fieldValues) 建立 QueryEndAtConstraint,根據查詢順序,將結果集修改成指定欄位的結尾。欄位值的順序必須與查詢子句的順序相符。
endBefore(fieldValues) 建立 QueryEndAtConstraint,根據查詢順序,將結果集修改成在提供的欄位之前的結尾。欄位值的順序必須與查詢子句的順序相符。
startAfter(fieldValues) 建立 QueryStartAtConstraint,根據查詢的順序,將結果集修改成在提供的欄位之後開始。欄位值的順序必須與查詢子句的順序相符。
startAt(fieldValues) 建立 QueryStartAtConstraint,根據查詢順序,將結果集修改成從提供的欄位開始。欄位值的順序必須與查詢子句的順序相符。
function(indexManager, ...)
deleteAllPersistentCacheIndexes(indexManager) 移除所有永久快取索引。請注意,這個函式也會刪除已淘汰的 setIndexConfiguration() 產生的索引。
disablePersistentCacheIndexAutoCreation(indexManager) 停止自動為本機查詢執行建立永久快取索引。透過呼叫 enablePersistentCacheIndexAutoCreation() 建立的索引仍會生效。
enablePersistentCacheIndexAutoCreation(indexManager) 如果 SDK 認為快取索引有助於改善效能,允許 SDK 自動為本機查詢執行建立永久快取索引。這項功能預設為停用。
功能(左側, ...)
aggregateFieldEqual(left, 右) 比較兩個「AggregateField」例項代表相等。
aggregateQuerySnapshotEqual(左, ) 比較兩個 AggregateQuerySnapshot 例項是否相等。系統會將兩個 AggregateQuerySnapshot 例項視為「相等」是否有基本查詢相同且資料相同
queryEqual(左, 右) 如果提供的查詢指向相同的集合,並套用相同的限制,則傳回 true。
refEqual(左, 右) 如果提供的參照相等,則傳回 true。
snapshotEqual(左, 右) 如果提供的快照相等,則傳回 true。
function(限制, ...)
limit(限制) 建立只會傳回第一組相符文件的 QueryLimitConstraint
limitToLast(限制) 建立只會傳回最新符合文件的 QueryLimitConstraint您必須為 limitToLast 查詢指定至少一個 orderBy 子句,否則系統會在執行期間擲回例外狀況。
function(logLevel, ...)
setLogLevel(logLevel) 設定 Cloud Firestore 記錄檔的詳細程度 (偵錯、錯誤或無訊息)。
功能(n, ...)
increment(n) 傳回可以與 setDoc()updateDoc() 搭配使用的特殊值,指示伺服器根據指定值增加欄位目前的值。如果運算元或目前的欄位值都使用浮點精確度,所有算術都會遵循 IEEE 754 語意。如果兩個值都是整數,位於 JavaScript 安全數字範圍 (Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER) 外的值也可能會遺失。此外,在 Firestore 後端處理完成後,所有整數作業的限制介於 -2^63 和 2^63-1 之間。如果目前欄位值不是 number 類型,或該欄位尚不存在,轉換會將欄位設為指定值。
function(查詢, ...)
getAggregateFromServer(query, aggregateSpec) 這個外掛程式能針對指定查詢結果集中的文件計算指定的匯總次數,且不會實際下載文件。由於只有最終匯總值,而非文件,因此使用此函式執行匯總作業非常有效率。下載及下載如果結果集極大,無法全部下載 (數千份文件),這個函式可以執行文件匯總作業。從伺服器接收的結果會以未變更的方式呈現,而不會考慮任何本機狀態。也就是說,本機快取中的文件並不會納入考量,即使是本機修改作業尚未與伺服器保持同步也一樣。系統不會使用先前下載的結果 (如有)。每次叫用此函式時,都必須經過伺服器往返。
getCountFromServer(查詢) 這個外掛程式能計算指定查詢結果集中的文件數量,但不需實際下載文件。由於只有最終計數,而非文件,因此使用這個函式計算文件非常有效率。資料,在 Kubernetes 中如果結果集極大,因而完全無法下載 (數千份文件),這個函式就可以計算文件數量。從伺服器接收的結果會以不更動的方式呈現,而不會考慮任何本機狀態。也就是說,本機快取中的文件並不會納入考量,即使是本機修改作業尚未與伺服器保持同步也一樣。系統不會使用先前下載的結果 (如有)。每次叫用此函式時,都必須經過伺服器往返。
getDoc(查詢) 執行查詢,並以 QuerySnapshot 形式傳回結果。注意:getDocs() 會等待伺服器中的資料,盡可能嘗試提供最新資料,但如果您離線且無法連上伺服器,可能會傳回快取資料或失敗。如要指定這個行為,請叫用 getDocFromCache()getDocFromServer()
getDocFromCache(查詢) 執行查詢,並從快取以 QuerySnapshot 的形式傳回結果。如果目前沒有快取與查詢相符的文件,則傳回空白的結果集。
getDocFromServer(查詢) 執行查詢,並以 QuerySnapshot 形式從伺服器傳回結果。如果無法使用網路,則傳回錯誤。
onSnapshot(查詢, 觀察器) 附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式來取消事件監聽器。注意:雖然可提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫該回呼。
onSnapshot(查詢, 選項, 觀察器) 附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式來取消事件監聽器。注意:雖然可提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫該回呼。
onSnapshot(query, onNext, onError, oncomplete) 附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式來取消事件監聽器。注意:雖然可提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫該回呼。
onSnapshot(query, options, onNext, onError, onComplete) 附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式來取消事件監聽器。注意:雖然可提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫該回呼。
query(query, CompositeFilter, queryConstraints) 建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。
query(query, queryConstraints) 建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。
function(queryConstraints, ...)
and(queryConstraints) 建立結合指定篩選器限制的新 QueryCompositeFilterConstraint。如果文件符合所有指定篩選條件,系統就會加入一份文件。
or(queryConstraints) 建立新的 QueryCompositeFilterConstraint,為指定篩選器限制條件的分離。解譯篩選器會納入符合任一指定篩選條件的文件。
function(參考資料, ...)
addDoc(參考資料, 資料) 使用指定資料在指定的 CollectionReference 中新增文件,自動指派文件 ID。
collection(reference, path, pathSegments) 取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。
collection(reference, path, pathSegments) 取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。
deleteDoc(參考資料) 刪除指定 DocumentReference 參照的文件。
doc(reference, path, pathSegments) 取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。如未指定路徑,傳回的 DocumentReference 將使用系統自動產生的專屬 ID。
doc(reference, path, pathSegments) 取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。
getDoc(參考資料) 讀取這個 DocumentReference 參照的文件。注意:getDoc() 嘗試從伺服器擷取資料時,嘗試提供最新資料,但如果您離線且無法連上伺服器,可能會傳回快取資料或失敗。如要指定這項行為,請叫用 getDocFromCache()getDocFromServer()
getDocFromCache(參照) 從快取讀取這個 DocumentReference 參照的文件。如果目前未快取文件,則傳回錯誤。
getDocFromServer(參考資料) 從伺服器讀取這個 DocumentReference 參照的文件。如果無法使用網路,則傳回錯誤。
onSnapshot(參照, 觀察器) 附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,或使用 nexterror 回呼傳遞單一觀察器物件。注意:雖然您可以提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫此方法。
onSnapshot(參照、選項、觀察器) 附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,或使用 nexterror 回呼傳遞單一觀察器物件。注意:雖然您可以提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫此方法。
onSnapshot(reference, onNext, onError, onComplete) 附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,或使用 nexterror 回呼傳遞單一觀察器物件。注意:雖然您可以提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫此方法。
onSnapshot(reference, options, onNext, onError, onComplete) 附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,或使用 nexterror 回呼傳遞單一觀察器物件。注意:雖然您可以提供 onCompletion 回呼,但由於快照串流永遠不會結束,因此一律不會呼叫此方法。
setDoc(參照, 資料) 寫入這個 DocumentReference 參照的文件。如果文件不存在,系統會建立文件。
setDoc(參照、資料、選項) 寫入指定 DocumentReference 參照的文件。如果文件不存在,系統會建立文件。如果您提供 mergemergeFields,則提供的資料可以合併至現有文件。
updateDoc(參照, 資料) 更新指定 DocumentReference 所參照文件中的欄位。如果套用至不存在的文件,更新就會失敗。
updateDoc(參照, 欄位, 值, 更多 FieldsAndValues) 更新指定 DocumentReference 所參照文件中的欄位,如果套用至不存在的文件,更新就會失敗。如要更新巢狀欄位,可以透過提供以點分隔的欄位路徑字串或提供 FieldPath 物件。
功能(設定, ...)
memoryLocalCache(設定) 建立 MemoryLocalCache 的執行個體。執行個體可設為 FirestoreSettings.cache,讓 SDK 知道要使用哪個快取層。
memoryLruGarbageCollector(設定) 建立 MemoryLruGarbageCollector 的執行個體。您可以在設定參數中指定目標大小。一旦快取大小超過指定大小,收集器就會開始刪除文件。預設快取大小為 40 MB (40 * 1024 * 1024 個位元組)。
persistentLocalCache(設定) 建立 PersistentLocalCache 的執行個體。您可將執行個體設為 FirestoreSettings.cache,讓 SDK 知道要使用的快取層。您無法在 Node.js 環境中使用永久快取。
persistentSingleTabManager(設定) 建立 PersistentSingleTabManager 的執行個體。
function(snapshot, ...)
endAt(快照) 建立 QueryEndAtConstraint,將結果集修改至提供的文件 (包含)。結束位置與查詢的順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。
endBefore(快照) 建立 QueryEndAtConstraint,將結果集修改為在提供的文件前結束 (不含)。結束位置與查詢的順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。
startAfter(snapshot) 建立 QueryStartAtConstraint,藉此修改結果集在提供的文件後方開頭 (不含)。起始位置與查詢順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。
startAt(快照) 建立 QueryStartAtConstraint,以將結果集修改為在提供的文件 (包含) 上。起始位置與查詢順序相關。文件必須包含這項查詢的 orderBy 中提供的所有欄位。
函式(值, ...)
vector(值) 使用指定數字陣列的副本建立新的 VectorValue

類別

類別 說明
AggregateField 代表可由 Firestore 執行的匯總。
AggregateQuerySnapshot 執行匯總查詢的結果。
位元組 代表位元組陣列的不可變物件。
CollectionReference CollectionReference 物件可用於新增文件、取得文件參照及查詢文件 (使用 query())。
DocumentReference DocumentReference 是指 Firestore 資料庫中的文件位置,可用於寫入、讀取或監聽位置。參照位置中的文件不一定存在。
文件快照 DocumentSnapshot 包含從 Firestore 資料庫中文件讀取的資料。可使用 .data().get(<field>) 擷取資料,藉此取得特定欄位。如果 DocumentSnapshot 指向現有的文件,任何資料存取權都會傳回「未定義」。您可以使用 exists() 方法明確驗證文件是否存在。
FieldPath FieldPath 是指文件中的欄位。路徑可包含單一欄位名稱 (參照文件中的頂層欄位) 或欄位名稱清單 (參照文件中的巢狀欄位)。請提供欄位名稱來建立 FieldPath。如果提供多個欄位名稱,路徑會指向文件中的巢狀欄位。
欄位值 使用 set()update() 編寫文件欄位時,可以使用的 entinel 值。
Firestore Cloud Firestore 服務介面。請勿直接呼叫這個建構函式。而是使用 getFirestore()
FirestoreError Firestore 作業傳回錯誤。
地理點 代表 Firestore 中地理位置的不可變物件。位置會以經緯度組合表示。緯度值的範圍介於 [-90, 90] 之間。經度值的範圍介於 [-180, 180]。
LoadBundleTask 代表載入 Firestore 套件的工作。這項工具會提供軟體包載入的進度,以及工作完成和錯誤事件。這個 API 與 Promise<LoadBundleTaskProgress> 相容。
PersistentCacheIndexManager PersistentCacheIndexManager,用於設定本機查詢執行作業使用的永久快取索引。如要使用,請呼叫 getPersistentCacheIndexManager() 來取得執行個體。
查詢 Query 是指可以讀取或監聽的查詢。您也可以新增篩選器和排序,建立修正後的 Query 物件。
QueryCompositeFilterConstraint QueryCompositeFilterConstraint 可用於執行多個 QueryFieldFilterConstraintQueryCompositeFilterConstraint 的邏輯 OR 或 AND 來縮小 Firestore 查詢傳回的文件集。QueryCompositeFilterConstraint 是透過叫用 or()and() 建立,然後可傳遞至 query() 建立包含 QueryCompositeFilterConstraint 的新查詢執行個體。
QueryConstraint QueryConstraint 可用來縮小 Firestore 查詢傳回的文件組合範圍。QueryConstraint 的建立方式是叫用 where()orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast()limitToLast() 例項。QueryConstraint
QueryDocumentSnapshot QueryDocumentSnapshot 包含從 Firestore 資料庫中文件讀取的資料,做為查詢的一部分。文件保證存在,且您可以使用 .data().get(<field>) 擷取其資料,以取得特定欄位。QueryDocumentSnapshot 提供的 API 介面與 DocumentSnapshot 相同。由於查詢結果只包含現有文件,因此 exists 屬性將一律為 true,data() 絕不會傳回「未定義」。
QueryEndAtConstraint QueryEndAtConstraint 可用來在 Firestore 查詢傳回的結果集結尾,排除文件。QueryEndAtConstraint 的建立方式是叫用 endAt()endBefore(),然後可傳遞至 query() 建立包含此 QueryEndAtConstraint 的新查詢執行個體。
QueryFieldFilterConstraint QueryFieldFilterConstraint 可用來篩選一或多個文件欄位,縮小 Firestore 查詢傳回的文件組合範圍。系統會透過叫用 where() 建立 QueryFieldFilterConstraint,然後傳遞至 query() 以建立包含此 QueryFieldFilterConstraint 的新查詢執行個體。
QueryLimitConstraint QueryLimitConstraint 用於限制 Firestore 查詢傳回的文件數量。QueryLimitConstraint 是透過叫用 limit()limitToLast() 來建立,然後可傳遞至 query() 建立包含此 QueryLimitConstraint 的新查詢執行個體。
QueryOrderByConstraint QueryOrderByConstraint 可用來排序 Firestore 查詢傳回的文件集。QueryOrderByConstraint 是透過叫用 orderBy() 來建立,然後可傳遞至 query() 以建立包含此 QueryOrderByConstraint 的新查詢執行個體。注意:不含 orderBy 欄位的文件不會出現在查詢結果中。
查詢快照 QuerySnapshot 包含零或多個 DocumentSnapshot 物件,代表查詢結果。您可以透過 docs 屬性,將文件做為陣列存取,或使用 forEach 方法列舉。文件數量可透過 emptysize 屬性決定。
QueryStartAtConstraint QueryStartAtConstraint 可用來從 Firestore 查詢傳回的結果集開頭,排除文件。QueryStartAtConstraint 的建立方式是叫用 startAt()startAfter(),然後可傳遞至 query() 建立包含此 QueryStartAtConstraint 的新查詢執行個體。
SnapshotMetadata 快照的中繼資料,說明快照的狀態。
時間戳記 Timestamp 代表與任何時區或日曆無關的時間點,以世界標準時間 Epoch 時間的奈秒為單位表示時間,並以秒為單位。該日曆使用草皮公曆編碼,將公曆的延伸至第 1 年。這個編碼會假設所有分鐘數都為 60 秒 (也就是閏秒為「smeared」) 進行編碼。這樣解讀時就不需閏秒錶格。範圍介於 0001-01-01T00:00:00Z 至 9999-12-31T23:59:59.999999999Z。如需範例和進一步規格,請參閱時間戳記定義
交易 對交易的參照。傳遞至交易 updateFunctionTransaction 物件提供在交易環境內讀取和寫入資料的方法。請參閱 runTransaction()
VectorValue 代表 Firestore 文件中的向量類型。使用 建立執行個體。向量值
WriteBatch 寫入批次,用於以單一不可分割單元的形式執行多項寫入作業。可透過呼叫 writeBatch() 取得 WriteBatch 物件。提供將寫入作業新增至寫入批次的方法。在呼叫 WriteBatch.commit() 之前,所有寫入作業都不會修訂 (或在本機顯示)。

介面

介面 說明
AggregateSpec 指定一組匯總及其別名。
文件變更 DocumentChange 代表與查詢相符的文件變更內容。其中包含受影響的文件和發生變更類型。
文件資料 文件資料 (用於 setDoc()) 包含對應至值的欄位。
ExperimentalLongPollingOptions 使用長時間輪詢時,設定 SDK 基礎網路傳輸 (WebChannel) 的選項。注意:這個介面為「實驗版」且可能會有變動。請參閱「FirestoreSettings.experimentalAutoDetectLongPolling」、「FirestoreSettings.experimentalForceLongPolling」和「FirestoreSettings.experimentalLongPollingOptions」。
FirestoreDataConverter withConverter() 所使用的轉換器,將 AppModelType 類型的使用者物件轉換為 DbModelType 類型的 Firestore 資料。使用轉換工具,您就能在儲存及擷取 Firestore 中的物件時,指定一般類型引數。在這種情況下,是一種應用程式類別,用於將相關資訊和功能封裝在一起。舉例來說,這類類別可能具有以下屬性:複雜、巢狀資料類型的屬性、用於記憶的屬性、Firestore 不支援的類型屬性 (例如 symbolbigint),以及執行複合作業的輔助函式。這類類別不適合且/或無法儲存至 Firestore 資料庫。相反地,這類類別的執行個體必須轉換為「普通的 JavaScript 物件」(POJO) 完全具備原始屬性,有可能嵌入其他 POJO 或 POJO 陣列中。在這個情況下,這種類型稱為「DbModel」且適合保存至 Firestore 的物件為方便起見,應用程式可以透過 DocumentReferenceQuery 等 Firestore 物件實作 FirestoreDataConverter,並使用 DocumentReferenceQuery 等 Firestore 物件來註冊轉換器,以便在儲存至 Firestore 時自動將 AppModel 轉換為 DbModel,並從 Firestore 擷取時將 DbModel 轉換為 AppModel
Firestore 設定 指定 Cloud Firestore 執行個體的自訂設定。您必須先設定這些設定,才能叫用其他方法。
索引 (Beta 版) Firestore 索引的 SDK 定義。
索引設定 (Beta 版) 用於加快本機查詢執行速度的 Firestore 索引清單。如需索引定義格式的說明,請參閱 JSON 格式
IndexField (Beta 版) 索引設定中的單一欄位元素。
LoadBundleTaskProgress 代表載入套件的進度更新或最終狀態。
MemoryCacheSettings 用於設定 MemoryLocalCache 執行個體的設定物件。
MemoryEagerGarbageCollector 垃圾收集器會在文件未參與任何執行中查詢時刪除文件,且文件未附加本機異動。這項收集器會盡力確保能減少 SDK 使用的記憶體,但進行離線查詢或直接查詢快取時,可能會引發未快取文件的風險。請使用工廠函式建立這個收集器的執行個體。
MemoryLocalCache 為 SDK 提供記憶體內快取。除非另有明確設定,否則這是預設快取。如要使用,請使用 Factory 函式建立執行個體,然後將例項設為 FirestoreSettings.cache,再使用設定物件呼叫 initializeFirestore
MemoryLruGarbageCollector 垃圾收集器會從多個批次中刪除最近最少使用過的文件。這項收集器設有目標大小,且只有在快取文件超過目標大小時才會進行收集。這個功能可避免重複查詢相同查詢或文件的後端,但可能會導致記憶體用量較大。請使用工廠函式建立這個收集器的執行個體。
持續性設定 您可以傳遞至 enableIndexedDbPersistence() 來設定 Firestore 持續性。無法在 Node.js 環境中使用永久保留設定。
PersistentCacheSettings 用於設定 PersistentLocalCache 執行個體的設定物件。Node.js 環境中無法使用永久快取。
PersistentLocalCache 為 SDK 提供由 IndexedDb 支援的永久快取。如要使用,請使用 Factory 函式建立執行個體,然後使用 設定物件將執行個體設為 FirestoreSettings.cache,並呼叫 initializeFirestore
PersistentMultipleTabManager 支援多個分頁的分頁管理工具。SDK 會使用 SDK 同步處理所有分頁中完成的查詢和異動。
PersistentSingleTabManager 一個分頁管理工具,僅支援一個分頁,因此無法跨分頁執行同步處理。
PersistentSingleTabManagerSettings 輸入即可設定 PersistentSingleTabManager 例項。
SnapshotListenOptions 此選項物件可以傳遞至 onSnapshot()QuerySnapshot.docChanges(),以控制要納入結果集的變更類型。
SnapshotOptions 設定從 DocumentSnapshot 擷取資料的方式的選項 (例如對尚未設為最終值的伺服器時間戳記所需行為)。
交易選項 自訂交易行為的選項。
取消訂閱 onSnapshot() 傳回的函式,可在叫用時移除事件監聽器。

變數

變數 說明
CACHE_SIZE_UNLIMITED 用來表示應停用 LRU 垃圾收集的常數。在傳遞至 Firestore 執行個體的設定中,將這個值設為 cacheSizeBytes

型別別名

類型別名 說明
AddPrefixToKey 傳回新的地圖,其中每個鍵都加上一個點的外鍵。
AggregateFieldType Firestore 支援的所有 AggregateField 類型聯集。
AggregateSpecData 其鍵來自 AggregateSpec,其值是輸入 AggregateSpec 中相應 AggregateField 執行的匯總結果。
AggregateType 代表要執行的匯總類型。
ChildUpdateFields 計算指定類型 T1 的巢狀欄位的輔助程式。如此一來,才能分配聯集類型,例如 undefined | {...} (選用項目) 或 {a: A} | {b: B}在此使用案例中,由於 T[K] 評估為運算式,而非分散式,因此 V 會在 Record 上分配 T[K] 的聯集類型。請參閱 https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
文件變更類型 DocumentChange 的類型可「新增」、「已移除」或「已修改」。
FirestoreErrorCode Firestore 狀態碼組合。這些代碼與 gRPC 所公開的代碼相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md可能的值:- 'cancelled':作業已取消 (通常是呼叫端)。-「未知」:未知的錯誤或其他錯誤網域的錯誤。-「 invalid-argument」:用戶端指定的引數無效。請注意,這與「failed-precondition」不同。「無效引數」會指出無論系統狀態為何有問題的引數 (例如無效欄位名稱)。-「超過期限」:在作業完成前已過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,伺服器雖然成功回應,但延遲時間太久,因而超過期限。-「找不到」:找不到某些要求的文件。-「已存在」:一些我們嘗試建立的文件已經存在。-「權限遭拒」:呼叫者沒有執行指定作業的權限。-「資源用盡」:已耗盡某些資源,也許是每位使用者的配額,或是整個檔案系統空間不足。-「failed-precondition」:由於系統未處於執行作業所需的狀態,因此作業遭拒。-「已中止」:作業已取消,通常是因為交易取消等並行問題所導致。-「超出範圍」:嘗試執行的作業超出有效範圍。-「未實作」:未執行或不支援/未啟用作業。-「internal」:發生內部錯誤。意味著基礎系統預期的某些不變量已被破壞。如果看到這類錯誤,表示已經完全損壞。-「無法使用」:目前無法使用服務。這很可能是一個暫時的情況,並可透過重試輪詢來修正。-「data-loss」:無法復原的資料遺失或損毀。-「unauthenticated」:要求沒有作業的有效驗證憑證。
FirestoreLocalCache 所有支援的 SDK 快取層的聯合類型。
ListenSource 請說明查詢監聽的來源。設為 default 即可監聽快取和伺服器變更。設為 cache 即可僅監聽快取的變更。
MemoryGarbageCollector 所有支援記憶體本機快取垃圾收集器的聯合類型。
NestedUpdateFields 在每個欄位 (例如「bar」) 中,找出所有巢狀鍵 (例如 {'bar.baz': T1, 'bar.qux': T2})。將這些元素相交,以建立單一地圖,內含所有可能標示為選填的索引鍵
OrderByDirection orderBy() 子句的方向指定為「desc」或「asc」(遞減或遞增)。
PartialWithFieldValue 與 TypeScript 的 Partial<T> 類似,但允許省略巢狀欄位,並將 FieldValues 做為屬性值傳遞。
PersistentTabManager 所有可用分頁管理員的聯集。
基本 原始類型。
QueryConstraintType 說明這個 SDK 中可用的不同查詢限制。
QueryFilterConstraint QueryFilterConstraint 是代表 QueryFieldFilterConstraintQueryCompositeFilterConstraint 的輔助聯集類型。
QueryNonFilterConstraint QueryNonFilterConstraint 是代表 QueryConstraint 的輔助聯集類型,可用於縮小文件集範圍或排序,但不會明確篩選文件欄位。QueryNonFilterConstraint 的建立方式是叫用 orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast() 以建立 QueryNonFilterConstraint,然後可同時傳給包含 query() 的新查詢。QueryConstraint
設定選項 一種選項物件,用於設定 setDoc() 的行為並呼叫。藉由為 merge: true 提供 SetOptions,即可將這些呼叫設為執行精細的合併,而非覆寫整個目標文件。
工作狀態 代表軟體包載入工作的狀態。兩者皆有「錯誤」和「成功」即將停止狀態:工作會取消或完成,且回報後就不會再更新。
UnionToIntersection 假設屬性為聯集類型 U = T1 | T2 | ...,會傳回交集類型 (T1 & T2 & ...)使用分配條件類型以及從條件式類型推論。這之所以能運作,是因為在相反變化版本位置中,相同類型變數的多個候選項目會被推斷出十字路口類型。https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type
更新資料 更新資料 (適用於與 updateDoc() 搭配使用),由由對應值的欄位路徑 (例如「foo」或「foo.baz」) 組成。含有點的欄位會參照文件中的巢狀欄位。FieldValues 可以做為屬性值傳入。
WhereFilterOp where() 子句中的篩選條件是使用「&lt;」、「&lt;='」、「'==', '!='、'&gt;=', '&gt;'」、「array-contains'、'in', 'array-contains-any'」和「not-in'」等字串。
WithFieldValue 允許將 FieldValues 做為屬性值傳入,同時維持類型安全性。

function(應用程式, ...)

getFirestore(應用程式)

傳回與所提供 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。

簽名:

export declare function getFirestore(app: FirebaseApp): Firestore;

參數

參數 類型 說明
應用程式 Firebase 應用程式 傳回的 Firestore 執行個體已與 FirebaseApp 例項建立關聯。

傳回:

Firestore

提供應用程式的預設 Firestore 執行個體。

getFirestore(應用程式, 資料庫 ID)

這個 API 僅為開發人員的預先發布版,可能會根據收到的意見回饋有所變動。請勿在正式環境中使用這個 API,

傳回與所提供 FirebaseApp 相關聯的現有已命名 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。

簽名:

export declare function getFirestore(app: FirebaseApp, databaseId: string): Firestore;

參數

參數 類型 說明
應用程式 Firebase 應用程式 傳回的 Firestore 執行個體已與 FirebaseApp 例項建立關聯。
資料庫 ID 字串 資料庫名稱。

傳回:

Firestore

提供應用程式的已命名 Firestore 執行個體。

InitialFirestore(應用程式, 設定, 資料庫 ID)

使用提供的設定初始化新的 Firestore 例項。只能在其他函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()

簽名:

export declare function initializeFirestore(app: FirebaseApp, settings: FirestoreSettings, databaseId?: string): Firestore;

參數

參數 類型 說明
應用程式 Firebase 應用程式 Firestore 執行個體建立關聯的 FirebaseApp
設定 Firestore 設定 用於設定 Firestore 執行個體的設定物件。
資料庫 ID 字串 資料庫名稱。

傳回:

Firestore

剛初始化的 Firestore 執行個體。

函式(Firestore, ...)

ClearIndexedDbPersistence(Firestore)

清除永久儲存空間。這包括待處理的寫入作業和快取文件。

Firestore 執行個體未啟動 (應用程式終止或應用程式首次初始化時) 時呼叫。啟動時,必須先呼叫這個函式,然後再呼叫其他函式 (不含 initializeFirestore()getFirestore())。如果 Firestore 執行個體仍在執行,系統會拒絕承諾產品,並顯示錯誤代碼 failed-precondition

簽名:

export declare function clearIndexedDbPersistence(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore 要清除持續性的 Firestore 執行個體。

傳回:

承諾<void>

永久儲存空間遭到清除時,會解決的 Promise。否則承諾產品會遭到拒絕並顯示錯誤。

收集(Firestore, path, pathSegments)

取得參照指定絕對路徑集合的 CollectionReference 例項。

簽名:

export declare function collection(firestore: Firestore, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

參數

參數 類型 說明
firestore Firestore Firestore 執行個體的參照。
路徑 字串 以斜線分隔的路徑,指向集合。
路徑區隔 string[] 相對於第一個引數要套用的其他路徑區段。

傳回:

CollectionReference<DocumentDataDocumentData>

CollectionReference 例項。

例外狀況

如果最終路徑的線段數為偶數,且並不指向集合,

collectionGroup(firestore, collectionId)

建立並傳回新的 Query 執行個體,其中包含資料庫內含使用 collectionId 的集合或子集合中的所有文件。

簽名:

export declare function collectionGroup(firestore: Firestore, collectionId: string): Query<DocumentData, DocumentData>;

參數

參數 類型 說明
firestore Firestore Firestore 執行個體的參照。
收藏 ID 字串 識別要查詢的集合。凡是使用這個 ID 做為路徑最後一個區隔的集合或子集合,都會納入。不得包含斜線。

傳回:

查詢<DocumentDataDocumentData>

已建立Query

connectFirestoreEmulator(Firestore、主機、通訊埠、選項)

修改這個執行個體,與 Cloud Firestore 模擬器通訊。

簽名:

export declare function connectFirestoreEmulator(firestore: Firestore, host: string, port: number, options?: {
    mockUserToken?: EmulatorMockTokenOptions | string;
}): void;

參數

參數 類型 說明
firestore Firestore 要設定連線至模擬器的 Firestore 執行個體。
主機 字串 模擬器主機 (例如:localhost)。
通訊埠 數字 模擬器通訊埠 (例如:9000)。
選項 { mockUserToken?:EmulatorMockTokenOptions |字串;}

傳回:

void

stopNetwork(Firestore)

停用這個執行個體的網路用量。您可以透過 enableNetwork() 重新啟用這項功能。網路停用時,所有快照事件監聽器、getDoc()getDocs() 呼叫都會從快取傳回結果,所有寫入作業都會排入佇列,直到網路恢復運作為止。

簽名:

export declare function disableNetwork(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore

傳回:

承諾<void>

網路停用後已解決的 Promise

doc(Firestore, path, pathSegments)

取得參照指定絕對路徑文件的 DocumentReference 例項。

簽名:

export declare function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;

參數

參數 類型 說明
firestore Firestore Firestore 執行個體的參照。
路徑 字串 文件的斜線分隔路徑。
路徑區隔 string[] 將根據第一個引數套用的其他路徑區段。

傳回:

DocumentReference<DocumentDataDocumentData>

DocumentReference 例項。

例外狀況

如果最後一個路徑的路段數量奇怪,且未指向文件,

enableIndexedDbPersistence(Firestore, 持續性設定)

未來的主要版本將移除這個函式。如要開啟 IndexedDb 快取,請將 FirestoreSettings.localCache 設為 PersistentLocalCache 的執行個體。在已指定 FirestoreSettings.localCache 的情況下呼叫此函式會擲回例外狀況。

嘗試啟用永久儲存空間 (如果可以的話)。

失敗時,enableIndexedDbPersistence() 會拒絕承諾或擲回例外狀況。失敗的原因有很多,可透過錯誤中的 code 來找出。

* 失敗的先決條件:應用程式已在其他瀏覽器分頁中開啟。* 無法使用:瀏覽器與離線持續性實作功能不相容。

請注意,即使失敗後,Firestore 執行個體仍可使用,但離線保存功能將會停用。

無法在 Node.js 環境中使用持續性。

簽名:

export declare function enableIndexedDbPersistence(firestore: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;

參數

參數 類型 說明
firestore Firestore 要啟用持續性的 Firestore 執行個體。
持續性設定 持續性設定 用於設定持續性的選用設定物件。

傳回:

承諾<void>

Promise,代表成功啟用永久儲存空間。

enableMultiTabIndexedDbPersistence(Firestore)

未來的主要版本將移除這個函式。請改為將 FirestoreSettings.localCache 設為 PersistentLocalCache 的執行個體,以便開啟已建立索引的資料庫快取。在已指定 FirestoreSettings.localCache 的情況下呼叫此函式會擲回例外狀況。

嘗試啟用多分頁永久儲存空間 (如果可能)。如果所有分頁啟用這項功能,所有作業都會共用本機持續性的存取權,包括共用查詢執行,以及在所有連線執行個體間因延遲回報本機文件更新,而受到延遲負擔。

失敗時,enableMultiTabIndexedDbPersistence() 會拒絕承諾或擲回例外狀況。失敗的原因有很多,可透過錯誤中的 code 來找出。

* 失敗的先決條件:應用程式已在其他瀏覽器分頁中開啟,且未啟用多分頁功能。* 無法使用:瀏覽器與離線持續性實作功能不相容。

請注意,即使失敗後,Firestore 執行個體仍可使用,但離線保存功能將會停用。

簽名:

export declare function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore 要啟用持續性的 Firestore 執行個體。

傳回:

承諾<void>

Promise,代表成功啟用永久儲存空間。

enableNetwork(Firestore)

事先呼叫 disableNetwork() 後,讓這個 Firestore 執行個體使用網路。

簽名:

export declare function enableNetwork(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore

傳回:

承諾<void>

啟用網路後已解析的 Promise

getPersistentCacheIndexManager(Firestore)

傳回指定 Firestore 物件使用的 PersistentCache Index Manager。

PersistentCacheIndexManager 執行個體或 null (如果本機永久儲存空間未使用)。

簽名:

export declare function getPersistentCacheIndexManager(firestore: Firestore): PersistentCacheIndexManager | null;

參數

參數 類型 說明
firestore Firestore

傳回:

PersistentCacheIndexManager |空值

loadBundle(firestore, bundleData)

將 Firestore 套件載入本機快取。

簽名:

export declare function loadBundle(firestore: Firestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;

參數

參數 類型 說明
firestore Firestore 要載入套件的 Firestore 執行個體。
BundleData ReadableStream<Uint8Array>|ArrayBuffer |字串 代表要載入組合的物件。有效物件為 ArrayBufferReadableStream<Uint8Array>string

傳回:

LoadBundleTask

LoadBundleTask 物件,用來將進度更新以及完成或錯誤事件通知呼叫端。可做為 Promise<LoadBundleTaskProgress>

nameQuery(Firestore, 名稱)

從本機快取讀取以指定名稱識別的 Firestore 查詢

已命名的查詢會封裝至伺服器端的套件中 (以及產生的文件),並使用 loadBundle 載入至本機快取。進入本機快取後,請使用這個方法依名稱擷取 Query

簽名:

export declare function namedQuery(firestore: Firestore, name: string): Promise<Query | null>;

參數

參數 類型 說明
firestore Firestore 要讀取查詢的 Firestore 執行個體。
名稱 字串 查詢的名稱。

傳回:

Promise<查詢 |空值>

使用查詢或 null 解析的 Promise

onSnapshotsInSync(firestore, 觀察器)

針對同步快照事件附加事件監聽器。未同步的快照表示所有受特定變更影響的事件監聽器均已觸發,即使單一伺服器產生的變更會影響多個事件監聽器。

注意:快照同步事件僅表示事件監聽器是彼此同步的,但與這些快照是否與伺服器同步無關。在個別事件監聽器中使用 SnapshotMetadata,以判斷快照是來自快取還是伺服器。

簽名:

export declare function onSnapshotsInSync(firestore: Firestore, observer: {
    next?: (value: void) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

參數

參數 類型 說明
firestore Firestore 用於同步處理快照的 Firestore 執行個體。
觀察者 { 下一個?:(值:void) =>無效;錯誤訊息?(錯誤:FirestoreError) =>無效;完成?:() =>無效;} 包含 nexterror 回呼的單一物件。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshotsInSync(firestore, onSync)

針對同步快照事件附加事件監聽器。未同步的快照表示所有受特定變更影響的事件監聽器均已觸發,即使單一伺服器產生的變更會影響多個事件監聽器。

注意:快照同步事件僅表示事件監聽器是彼此同步的,但與這些快照是否與伺服器同步無關。在個別事件監聽器中使用 SnapshotMetadata,判斷快照是來自快取還是伺服器。

簽名:

export declare function onSnapshotsInSync(firestore: Firestore, onSync: () => void): Unsubscribe;

參數

參數 類型 說明
firestore Firestore 用於同步處理快照的 Firestore 執行個體。
OnSync () =>void 每次所有快照事件監聽器彼此同步時,要呼叫的回呼。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

runTransaction(firestore, updateFunction, options)

執行指定的 updateFunction,然後嘗試修訂交易中套用的變更。如果在交易中讀取過任何文件,Cloud Firestore 會重試 updateFunction。如果嘗試 5 次後仍無法修訂,則交易會失敗。

單一交易允許的寫入次數上限是 500。

簽名:

export declare function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;

參數

參數 類型 說明
firestore Firestore 用於執行這筆交易的 Firestore 資料庫參照。
updateFunction。 (交易:交易) =>承諾<T> 要在交易內容中執行的函式。
選項 交易選項 用於設定修訂嘗試次數上限的選項物件。

傳回:

承諾<T>

如果交易順利完成或明確取消 (updateFunction 傳回失敗的承諾),這裡會傳回 updateFunction 傳回的承諾。否則,如果交易失敗,系統就會傳回拒絕承諾,並顯示對應的失敗錯誤。

setIndexConfiguration(firestore, configuration)

這個 API 僅為開發人員的預先發布版,可能會根據收到的意見回饋有所變動。請勿在正式環境中使用這個 API,

,瞭解如何調查及移除這項存取權。

請考慮使用 enablePersistentCacheIndexAutoCreation(),讓 SDK 決定是否要為在本機執行的查詢建立快取索引,而非手動建立快取索引。

為本機查詢執行作業設定索引。系統會覆寫所有先前的索引設定。保留索引設定後,Promise 就會解析。

索引項目本身是以非同步方式建立。即使目前無法提供索引,您還是可以繼續使用需要建立索引的查詢。寫入索引項目後,查詢執行作業將自動開始使用索引。

索引僅支援 IndexedDb 持續性。如果未啟用 IndexedDb,系統會忽略所有索引設定。

簽名:

export declare function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise<void>;

參數

參數 類型 說明
firestore Firestore 要設定索引的 Firestore 執行個體。
設定 索引設定 索引定義。

傳回:

承諾<void>

在成功設定所有索引後解析的 Promise

例外狀況

如果 JSON 格式無效,就會發生 FirestoreError。

setIndexConfiguration(firestore, json)

這個 API 僅為開發人員的預先發布版,可能會根據收到的意見回饋有所變動。請勿在正式環境中使用這個 API,

,瞭解如何調查及移除這項存取權。

請考慮使用 enablePersistentCacheIndexAutoCreation(),讓 SDK 決定是否要為在本機執行的查詢建立快取索引,而非手動建立快取索引。

為本機查詢執行作業設定索引。系統會覆寫所有先前的索引設定。保留索引設定後,Promise 就會解析。

索引項目本身是以非同步方式建立。即使目前無法提供索引,您還是可以繼續使用需要建立索引的查詢。寫入索引項目後,查詢執行作業將自動開始使用索引。

索引僅支援 IndexedDb 持續性。設定索引設定前,請先叫用 enableIndexedDbPersistence()enableMultiTabIndexedDbPersistence()。如果未啟用 IndexedDb,系統會忽略所有索引設定。

此方法接受由 Firebase CLI 匯出的 JSON 格式 (firebase firestore:indexes)。如果 JSON 格式無效,這個方法會擲回錯誤。

簽名:

export declare function setIndexConfiguration(firestore: Firestore, json: string): Promise<void>;

參數

參數 類型 說明
firestore Firestore 要設定索引的 Firestore 執行個體。
json 字串 Firebase CLI 匯出的 JSON 格式。

傳回:

承諾<void>

在成功設定所有索引後解析的 Promise

例外狀況

如果 JSON 格式無效,就會發生 FirestoreError。

終止(Firestore)

終止提供的 Firestore 執行個體。

呼叫 terminate() 後,只能使用 clearIndexedDbPersistence() 函式。任何其他函式都會擲回 FirestoreError

如要在終止後重新啟動,請使用 getFirestore() 建立新的 FirebaseFirestore 執行個體。

終止不會取消任何待處理的寫入作業,系統也不會解決任何等待伺服器回應的承諾。啟用持續性後,下次啟動這個執行個體時,系統就會繼續將寫入作業傳送至伺服器。

簽名:

export declare function terminate(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore

傳回:

承諾<void>

執行個體成功終止時已解決的 Promise

waitForPendingWrites(Firestore)

等候後端確認有效使用者所有目前待處理的寫入作業。

如果沒有待處理的寫入作業,傳回的承諾會立即解析。否則,承諾會等待所有先前核發的寫入作業 (包括先前應用程式工作階段中寫入的寫入作業),但不會等待呼叫函式之後新增的寫入作業。如要等待其他寫入作業,請再次呼叫 waitForPendingWrites()

在使用者變更期間,所有尚未履行的 waitForPendingWrites() 承諾都會遭到拒絕。

簽名:

export declare function waitForPendingWrites(firestore: Firestore): Promise<void>;

參數

參數 類型 說明
firestore Firestore

傳回:

承諾<void>

在後端確認所有待處理的寫入作業時,Promise 會解析。

WriteBatch(Firestore)

建立寫入批次,用來以單一不可分割作業的形式執行多次寫入。單一 WriteBatch 允許的寫入數量上限為 500。

與交易不同的是,寫入批次會保存在離線狀態,因此如果您不需要對讀取資料的寫入作業進行條件式,建議使用此工作。

簽名:

export declare function writeBatch(firestore: Firestore): WriteBatch;

參數

參數 類型 說明
firestore Firestore

傳回:

WriteBatch

一個 WriteBatch,以不可分割的形式執行多項寫入作業。

function()

計數()

建立 AggregateField 物件,以計算查詢結果集中的文件數量。

簽名:

export declare function count(): AggregateField<number>;

傳回:

AggregateField<number>

deleteField()

傳回一個 sendinel 與 updateDoc()setDoc(){merge: true},用於標示要刪除的欄位。

簽名:

export declare function deleteField(): FieldValue;

傳回:

欄位值

文件 ID()

傳回特殊的印記 FieldPath,用來參照文件 ID。可在查詢中使用,依文件 ID 排序或篩選。

簽名:

export declare function documentId(): FieldPath;

傳回:

FieldPath

getFirestore()

傳回與預設 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。

簽名:

export declare function getFirestore(): Firestore;

傳回:

Firestore

預設應用程式的預設 Firestore 執行個體。

MemorystoreEagerGarbageCollector()

建立 MemoryEagerGarbageCollector 的執行個體。除非另有明確指定,否則這也是預設的垃圾收集器。

簽名:

export declare function memoryEagerGarbageCollector(): MemoryEagerGarbageCollector;

傳回:

MemoryEagerGarbageCollector

PersistentMultipleTabManager()

建立 PersistentMultipleTabManager 的執行個體。

簽名:

export declare function persistentMultipleTabManager(): PersistentMultipleTabManager;

傳回:

PersistentMultipleTabManager

伺服器時間戳記()

傳回與 setDoc()updateDoc() 搭配使用的 insinel,在寫入的資料中加入伺服器產生的時間戳記。

簽名:

export declare function serverTimestamp(): FieldValue;

傳回:

欄位值

function(databaseId, ...)

getFirestore(databaseId)

這個 API 僅為開發人員的預先發布版,可能會根據收到的意見回饋有所變動。請勿在正式環境中使用這個 API,

傳回與預設 FirebaseApp 相關聯的現有已命名 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。

簽名:

export declare function getFirestore(databaseId: string): Firestore;

參數

參數 類型 說明
資料庫 ID 字串 資料庫名稱。

傳回:

Firestore

預設應用程式的命名 Firestore 執行個體。

函式(元素, ...)

ArrayRemove(元素)

傳回可以與 setDoc() 搭配使用的特殊值,或指示伺服器從伺服器上現有的任何陣列值中移除指定元素。系統會從陣列中移除每個指定元素的所有例項。如果修改的欄位尚未是陣列,則會以空白陣列覆寫。

簽名:

export declare function arrayRemove(...elements: unknown[]): FieldValue;

參數

參數 類型 說明
elements 不明 [] 要從陣列中移除的元素。

傳回:

欄位值

用於 setDoc()updateDoc() 呼叫的 FieldValue 智慧型傳送器

陣列 Union(元素)

傳回可以與 setDoc()updateDoc() 搭配使用的特殊值,指示伺服器將特定元素與伺服器上現有的任何陣列值建立聯集。陣列中沒有的指定元素都會新增到結尾。如果修改的欄位尚未是陣列,則會以包含完全指定元素的陣列覆寫該欄位。

簽名:

export declare function arrayUnion(...elements: unknown[]): FieldValue;

參數

參數 類型 說明
elements 不明 [] 要聯集到陣列的元素。

傳回:

欄位值

用於對 setDoc()updateDoc() 的呼叫的 FieldValue 傳送器。

function(field, ...)

平均(欄位)

建立 AggregateField 物件,以計算查詢結果集內某範圍文件的平均值。

簽名:

export declare function average(field: string | FieldPath): AggregateField<number | null>;

參數

參數 類型 說明
欄位 字串 |FieldPath 指定結果集的平均值欄位。

傳回:

AggregateField<數字 |空值>

total(field)

建立 AggregateField 物件,以便計算查詢結果集中指定欄位內指定欄位的總和。

簽名:

export declare function sum(field: string | FieldPath): AggregateField<number>;

參數

參數 類型 說明
欄位 字串 |FieldPath 指定要用於結果集總和的欄位。

傳回:

AggregateField<number>

function(fieldPath, ...)

orderBy(fieldPath, directStr)

建立 QueryOrderByConstraint 會依據指定欄位將查詢結果排序 (選擇以遞減順序而非遞增順序)。

簽名:

export declare function orderBy(fieldPath: string | FieldPath, directionStr?: OrderByDirection): QueryOrderByConstraint;

參數

參數 類型 說明
欄位路徑 字串 |FieldPath 要做為排序依據的欄位。
方向距離 OrderByDirection 選用的排序方向 (「asc」或「desc」)。如未指定,則會以遞增方式排序。

傳回:

QueryOrderByConstraint

已建立的 QueryOrderByConstraint

where(fieldPath, opStr, value)

建立 QueryFieldFilterConstraint,要求文件必須包含指定欄位,且值應符合提供的關聯限制。

簽名:

export declare function where(fieldPath: string | FieldPath, opStr: WhereFilterOp, value: unknown): QueryFieldFilterConstraint;

參數

參數 類型 說明
欄位路徑 字串 |FieldPath 要比較的路徑
奧普斯特 WhereFilterOp 作業字串 (例如「&lt;」、「&lt;="」、「==」、「&lt;」、「&lt;=」和「!=」)。
不明 用於比較的值

傳回:

QueryFieldFilterConstraint

已建立的 QueryFieldFilterConstraint

function(fieldValues, ...)

endAt(fieldValues)

建立 QueryEndAtConstraint,根據查詢順序,將結果集修改成指定欄位的結尾。欄位值的順序必須與查詢子句的順序相符。

簽名:

export declare function endAt(...fieldValues: unknown[]): QueryEndAtConstraint;

參數

參數 類型 說明
欄位值 不明 [] 此查詢結束依據的欄位值,按照查詢的順序排列。

傳回:

QueryEndAtConstraint

要傳遞至 query()QueryEndAtConstraint

endBefore(fieldValues)

建立 QueryEndAtConstraint,根據查詢順序,將結果集修改成在提供的欄位之前的結尾。欄位值的順序必須與查詢子句的順序相符。

簽名:

export declare function endBefore(...fieldValues: unknown[]): QueryEndAtConstraint;

參數

參數 類型 說明
欄位值 不明 [] 在此查詢之前結束這項查詢的欄位值,依查詢順序排序。

傳回:

QueryEndAtConstraint

要傳遞至 query()QueryEndAtConstraint

startAfter(fieldValues)

建立 QueryStartAtConstraint,根據查詢的順序,將結果集修改成在提供的欄位之後開始。欄位值的順序必須與查詢子句的順序相符。

簽名:

export declare function startAfter(...fieldValues: unknown[]): QueryStartAtConstraint;

參數

參數 類型 說明
欄位值 不明 [] 查詢之後要啟動這項查詢的欄位值 (按照查詢順序排列)。

傳回:

QueryStartAtConstraint

要傳遞至 query()QueryStartAtConstraint

startAt(fieldValues)

建立 QueryStartAtConstraint,根據查詢順序,將結果集修改成從提供的欄位開始。欄位值的順序必須與查詢子句的順序相符。

簽名:

export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstraint;

參數

參數 類型 說明
欄位值 不明 [] 要開始這項查詢的欄位值,按照查詢的順序排列。

傳回:

QueryStartAtConstraint

要傳遞至 query()QueryStartAtConstraint

function(indexManager, ...)

deleteAllPersistentCacheIndexes(indexManager)

移除所有永久快取索引。

請注意,此函式也會刪除已淘汰的 setIndexConfiguration() 產生的索引。

簽名:

export declare function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void;

參數

參數 類型 說明
indexManager PersistentCacheIndexManager

傳回:

void

停用 PersistentCacheIndexAutoCreation(indexManager)

停止自動為本機查詢執行建立永久快取索引。透過呼叫 enablePersistentCacheIndexAutoCreation() 建立的索引仍會生效。

簽名:

export declare function disablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;

參數

參數 類型 說明
indexManager PersistentCacheIndexManager

傳回:

void

enablePersistentCacheIndexAutoCreation(indexManager)

如果 SDK 認為快取索引有助於改善效能,可讓 SDK 自動為本機查詢執行建立永久快取索引。

這項功能預設為停用。

簽名:

export declare function enablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void;

參數

參數 類型 說明
indexManager PersistentCacheIndexManager

傳回:

void

函式(左側, ...)

aggregateFieldEqual(左, 右)

比較兩個「AggregateField」例項代表相等。

簽名:

export declare function aggregateFieldEqual(left: AggregateField<unknown>, right: AggregateField<unknown>): boolean;

參數

參數 類型 說明
AggregateField<unknown> 將這個 AggregateField 與 right 進行比較。
AggregateField<unknown> 將這個 AggregateField 與 left 進行比較。

傳回:

布林值

aggregateQuerySnapshotEqual(左, )

比較兩個 AggregateQuerySnapshot 例項是否相等。

系統會將兩個 AggregateQuerySnapshot 執行個體視為「相等」是否有基本查詢相同且資料相同

簽名:

export declare function aggregateQuerySnapshotEqual<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(left: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>, right: AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>): boolean;

參數

參數 類型 說明
AggregateQuerySnapshot<AggregateSpecType、AppModelType、DBMModelType> 第一個要比較的 AggregateQuerySnapshot
AggregateQuerySnapshot<AggregateSpecType、AppModelType、DBMModelType> 第二個要比較的 AggregateQuerySnapshot

傳回:

布林值

如果物件是「等於」(如上定義),則為 true,否則為 false

queryEqual(左, 右)

如果提供的查詢指向相同的集合,並套用相同的限制,則傳回 true。

簽名:

export declare function queryEqual<AppModelType, DbModelType extends DocumentData>(left: Query<AppModelType, DbModelType>, right: Query<AppModelType, DbModelType>): boolean;

參數

參數 類型 說明
查詢<AppModelType、DundModelType> 要比較的 Query
查詢<AppModelType、DundModelType> 要比較的 Query

傳回:

布林值

如果參照指向同一個 Firestore 資料庫中相同的位置,則為 true。

refEqual(左, 右)

如果提供的參照相等,則傳回 true。

簽名:

export declare function refEqual<AppModelType, DbModelType extends DocumentData>(left: DocumentReference<AppModelType, DbModelType> | CollectionReference<AppModelType, DbModelType>, right: DocumentReference<AppModelType, DbModelType> | CollectionReference<AppModelType, DbModelType>): boolean;

參數

參數 類型 說明
DocumentReference<AppModelType、DundModelType>|CollectionReference<AppModelType、DundModelType> 用於比較的參照。
DocumentReference<AppModelType、DundModelType>|CollectionReference<AppModelType、DundModelType> 用於比較的參照。

傳回:

布林值

如果參照指向同一個 Firestore 資料庫中相同的位置,則為 true。

快照 Equal(左、右)

如果提供的快照相等,則傳回 true。

簽名:

export declare function snapshotEqual<AppModelType, DbModelType extends DocumentData>(left: DocumentSnapshot<AppModelType, DbModelType> | QuerySnapshot<AppModelType, DbModelType>, right: DocumentSnapshot<AppModelType, DbModelType> | QuerySnapshot<AppModelType, DbModelType>): boolean;

參數

參數 類型 說明
DocumentSnapshot<AppModelType、DundModelType>|查詢快照<AppModelType、DundModelType> 要比較的快照。
DocumentSnapshot<AppModelType、DundModelType>|查詢快照<AppModelType、DundModelType> 要比較的快照。

傳回:

布林值

如果快照相同,則傳回 true。

function(限制, ...)

limit(限制)

建立只會傳回第一組相符文件的 QueryLimitConstraint

簽名:

export declare function limit(limit: number): QueryLimitConstraint;

參數

參數 類型 說明
限制 數字 傳回的項目數量上限。

傳回:

QueryLimitConstraint

已建立的 QueryLimitConstraint

limitToLast(限制)

建立只傳回最後一組相符文件的 QueryLimitConstraint

您必須為 limitToLast 查詢指定至少一個 orderBy 子句,否則系統會在執行期間擲回例外狀況。

簽名:

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

參數

參數 類型 說明
限制 數字 傳回的項目數量上限。

傳回:

QueryLimitConstraint

已建立的 QueryLimitConstraint

function(logLevel, ...)

setLogLevel(logLevel)

設定 Cloud Firestore 記錄檔的詳細程度 (偵錯、錯誤或無訊息)。

簽名:

export declare function setLogLevel(logLevel: LogLevel): void;

參數

參數 類型 說明
logLevel LogLevel 您設定的活動和錯誤記錄詳細程度。這可以是下列任一值:
  • debug 適用於最詳細的記錄層級,主要用於偵錯。
  • error 即可只記錄錯誤。
  • silent to turn off logging.

傳回:

void

函式(n, ...)

遞增(n)

傳回可以與 setDoc()updateDoc() 搭配使用的特殊值,指示伺服器根據指定值增加欄位的目前值。

如果運算元或目前的欄位值使用浮點精確度,所有算術都會遵循 IEEE 754 語意。如果兩個值都是整數,位於 JavaScript 安全數字範圍 (Number.MIN_SAFE_INTEGERNumber.MAX_SAFE_INTEGER) 外的值也可能會遺失。此外,在 Firestore 後端處理之後,所有整數作業的整數作業均為 -2^63 和 2^63-1 之間的上限。

如果目前欄位值不是 number 類型,或如果該欄位不存在,轉換會將欄位設為指定值。

簽名:

export declare function increment(n: number): FieldValue;

參數

參數 類型 說明
n 數字 要遞增的值。

傳回:

欄位值

用於 setDoc()updateDoc() 呼叫的 FieldValue 智慧型傳送器

function(查詢, ...)

getAggregateFromServer(query, aggregateSpec)

以指定查詢結果集中的文件計算指定的匯總次數,而不必實際下載文件。

使用這個函式執行匯總是有效率的,因為只有最終匯總值,而非文件下載及下載如果結果集過大,無法完全下載 (數千份文件),這個函式就能執行文件匯總作業。

伺服器傳回的結果會呈現不變的特性,而不會考慮任何本機狀態。也就是說,本機快取中的文件並不會納入考量,即使是本機修改作業尚未與伺服器保持同步也一樣。系統不會使用先前下載的結果 (如有)。每次叫用此函式時,都必須經過伺服器往返。

簽名:

export declare function getAggregateFromServer<AggregateSpecType extends AggregateSpec, AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, aggregateSpec: AggregateSpecType): Promise<AggregateQuerySnapshot<AggregateSpecType, AppModelType, DbModelType>>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 系統會匯總其結果集的查詢。
匯總規格 匯總規格類型 AggregateSpec 物件,用來指定要對結果集執行的匯總作業。AggregateSpec 會指定每個匯總的別名,可用於擷取匯總結果。

傳回:

Promise<AggregateQuerySnapshot<AggregateSpecType、AppModelType、DundModelType>>

範例

const aggregateSnapshot = await getAggregateFromServer(query, {
  countOfDocs: count(),
  totalHours: sum('hours'),
  averageScore: average('score')
});

const countOfDocs: number = aggregateSnapshot.data().countOfDocs;
const totalHours: number = aggregateSnapshot.data().totalHours;
const averageScore: number | null = aggregateSnapshot.data().averageScore;

getCountFromServer(查詢)

計算指定查詢結果集中的文件數量,但實際上不會下載文件。

使用這個函式計算文件很有效,因為只有最終計數,而非文件。資料,在 Kubernetes 中如果結果集極大 (一千份文件),這個函式就能計算文件數量。

伺服器傳回的結果會呈現不變的特性,而不會考慮任何本機狀態。也就是說,本機快取中的文件並不會納入考量,即使是本機修改作業尚未與伺服器保持同步也一樣。系統不會使用先前下載的結果 (如有)。每次叫用此函式時,都必須經過伺服器往返。

簽名:

export declare function getCountFromServer<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<AggregateQuerySnapshot<{
    count: AggregateField<number>;
}, AppModelType, DbModelType>>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 計算結果集大小的查詢。

傳回:

Promise<AggregateQuerySnapshot<{ count: AggregateField<number>;}、AppModelType、DBMModelType>>

將會用計數解決的承諾;您可以從 snapshot.data().count 擷取計數,其中 snapshot 是傳回 Promise 解析的 AggregateQuerySnapshot

getDoc(查詢)

執行查詢,並以 QuerySnapshot 的形式傳回結果。

簽名:

export declare function getDocs<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType>

傳回:

Promise<QuerySnapshot<AppModelType, DBMModelType>>

將使用查詢結果解析的 Promise

getDocFromCache(查詢)

執行查詢,並從快取以 QuerySnapshot 的形式傳回結果。如果目前沒有快取與查詢相符的文件,則傳回空白的結果集。

簽名:

export declare function getDocsFromCache<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType>

傳回:

Promise<QuerySnapshot<AppModelType, DBMModelType>>

將使用查詢結果解析的 Promise

getDocFromServer(查詢)

執行查詢,並以 QuerySnapshot 形式從伺服器傳回結果。如果無法使用網路,則傳回錯誤。

簽名:

export declare function getDocsFromServer<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>): Promise<QuerySnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType>

傳回:

Promise<QuerySnapshot<AppModelType, DBMModelType>>

將使用查詢結果解析的 Promise

onSnapshot(查詢, 觀察器)

附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式,取消事件監聽器。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, observer: {
    next?: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 要監聽的查詢。
觀察者 { 下一個?:(快照:QuerySnapshot<AppModelType, DBMModelType>) =>無效;錯誤訊息?(錯誤:FirestoreError) =>無效;完成?:() =>無效;} 包含 nexterror 回呼的單一物件。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(查詢, 選項, 觀察器)

附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式,取消事件監聽器。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, options: SnapshotListenOptions, observer: {
    next?: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 要監聽的查詢。
選項 SnapshotListenOptions 控制聆聽行為的選項。
觀察者 { 下一個?:(快照:QuerySnapshot<AppModelType, DBMModelType>) =>無效;錯誤訊息?(錯誤:FirestoreError) =>無效;完成?:() =>無效;} 包含 nexterror 回呼的單一物件。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(query, onNext, onError, on 系統完成)

附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式,取消事件監聽器。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, onNext: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 要監聽的查詢。
下一本 (快照:QuerySnapshot<AppModelType, DBMModelType>) =>void 每當有新的 QuerySnapshot 可用時,要呼叫的回呼。
onError (錯誤:FirestoreError) =>void 當監聽失敗或取消時,要呼叫的回呼。這樣就不會再次進行回呼。
完成時 () =>void 可以提供,但不會呼叫,因為串流一律不會結束。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(query, options, onNext, onError, oncomplete)

附加 QuerySnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。呼叫 onSnapshot 時,您可以呼叫傳回的函式,取消事件監聽器。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 要監聽的查詢。
選項 SnapshotListenOptions 控制聆聽行為的選項。
下一本 (快照:QuerySnapshot<AppModelType, DBMModelType>) =>void 每當有新的 QuerySnapshot 可用時,要呼叫的回呼。
onError (錯誤:FirestoreError) =>void 當監聽失敗或取消時,要呼叫的回呼。這樣就不會再次進行回呼。
完成時 () =>void 可以提供,但不會呼叫,因為串流一律不會結束。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

query(query, CompositeFilter, queryConstraints)

建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。

簽名:

export declare function query<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, compositeFilter: QueryCompositeFilterConstraint, ...queryConstraints: QueryNonFilterConstraint[]): Query<AppModelType, DbModelType>;

參數

參數 類型 說明
查詢 查詢<AppModelType、DundModelType> 要做為新限制基礎的 Query 執行個體。
複合篩選器 QueryCompositeFilterConstraint 要套用的 QueryCompositeFilterConstraint。使用 and()or() 建立 QueryCompositeFilterConstraint
queryConstraints QueryNonFilterConstraint[] 要套用的其他 QueryNonFilterConstraint (例如 orderBy()limit())。

傳回:

查詢<AppModelType、DundModelType>

例外狀況

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

query(query, queryConstraints)

建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。

簽名:

export declare function query<AppModelType, DbModelType extends DocumentData>(query: Query<AppModelType, DbModelType>, ...queryConstraints: QueryConstraint[]): Query<AppModelType, DbModelType>;

參數

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

傳回:

查詢<AppModelType、DundModelType>

例外狀況

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

function(queryConstraints, ...)

and(queryConstraints)

建立結合指定篩選器限制的新 QueryCompositeFilterConstraint。如果文件符合所有指定篩選條件,系統就會加入一份文件。

簽名:

export declare function and(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;

參數

參數 類型 說明
queryConstraints QueryFilterConstraint[] 選用設定。要執行連接的 QueryFilterConstraint 清單。建立這些元素時,必須透過呼叫 where()or()and() 的呼叫建立。

傳回:

QueryCompositeFilterConstraint

新建立的 QueryCompositeFilterConstraint

or(queryConstraints)

建立新的 QueryCompositeFilterConstraint,為指定篩選器限制條件的分離。解譯篩選器會納入符合任一指定篩選條件的文件。

簽名:

export declare function or(...queryConstraints: QueryFilterConstraint[]): QueryCompositeFilterConstraint;

參數

參數 類型 說明
queryConstraints QueryFilterConstraint[] 選用設定。要執行解讀的 QueryFilterConstraint 清單。建立這些元素時,必須透過呼叫 where()or()and() 的呼叫建立。

傳回:

QueryCompositeFilterConstraint

新建立的 QueryCompositeFilterConstraint

function(參照, ...)

addDoc(參照, 資料)

使用指定資料在指定的 CollectionReference 中新增文件,自動指派文件 ID。

簽名:

export declare function addDoc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<DocumentReference<AppModelType, DbModelType>>;

參數

參數 類型 說明
參考資料 CollectionReference<AppModelType、DundModelType> 要新增這份文件的集合參照。
資料 WithFieldValue<AppModelType> 包含新文件資料的物件。

傳回:

Promise<DocumentReference<AppModelType, DBMModelType>>

將新建立的文件寫入後端後,Promise 會使用 DocumentReference 進行解析 (請注意,該文件無法在離線時解析)。

collection(reference, path, pathSegments)

取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。

簽名:

export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

參數

參數 類型 說明
參考資料 CollectionReference<AppModelType、DundModelType> 集合的參照。
路徑 字串 以斜線分隔的路徑,指向集合。
路徑區隔 string[] 相對於第一個引數要套用的其他路徑區段。

傳回:

CollectionReference<DocumentDataDocumentData>

CollectionReference 例項。

例外狀況

如果最終路徑的線段數為偶數,且並不指向集合,

collection(reference, path, pathSegments)

取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。

簽名:

export declare function collection<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): CollectionReference<DocumentData, DocumentData>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> Firestore 文件的參照。
路徑 字串 以斜線分隔的路徑,指向集合。
路徑區隔 string[] 將根據第一個引數套用的其他路徑區段。

傳回:

CollectionReference<DocumentDataDocumentData>

CollectionReference 例項。

例外狀況

如果最終路徑的線段數為偶數,且並不指向集合,

deleteDoc(參照)

刪除指定 DocumentReference 參照的文件。

簽名:

export declare function deleteDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<void>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要刪除的文件參照。

傳回:

承諾<void>

一旦文件成功從後端刪除, Promise 就已解決 (請注意,文件在離線期間無法解析)。

doc(reference, path, pathSegments)

取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。如未指定路徑,系統會為傳回的 DocumentReference 使用自動產生的專屬 ID。

簽名:

export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: CollectionReference<AppModelType, DbModelType>, path?: string, ...pathSegments: string[]): DocumentReference<AppModelType, DbModelType>;

參數

參數 類型 說明
參考資料 CollectionReference<AppModelType、DundModelType> 集合的參照。
路徑 字串 文件的斜線分隔路徑。如要使用自動產生的 ID,請省略。
路徑區隔 string[] 將根據第一個引數套用的其他路徑區段。

傳回:

DocumentReference<AppModelType、DundModelType>

DocumentReference 例項。

例外狀況

如果最後一個路徑的路段數量奇怪,且未指向文件,

doc(reference, path, pathSegments)

取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。

簽名:

export declare function doc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, path: string, ...pathSegments: string[]): DocumentReference<DocumentData, DocumentData>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> Firestore 文件的參照。
路徑 字串 文件的斜線分隔路徑。
路徑區隔 string[] 將根據第一個引數套用的其他路徑區段。

傳回:

DocumentReference<DocumentDataDocumentData>

DocumentReference 例項。

例外狀況

如果最後一個路徑的路段數量奇怪,且未指向文件,

getDoc(參照)

讀取這個DocumentReference所參照的文件。

簽名:

export declare function getDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要擷取的文件參照。

傳回:

Promise<DocumentSnapshot<AppModelType, DBMModelType>>

Promise 已透過包含目前文件內容的 DocumentSnapshot 解析。

getDocFromCache(參照)

從快取讀取這個 DocumentReference 參照的文件。如果目前未快取文件,則傳回錯誤。

簽名:

export declare function getDocFromCache<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType>

傳回:

Promise<DocumentSnapshot<AppModelType, DBMModelType>>

Promise 已透過 DocumentSnapshot 解決,其中包含目前的文件內容。

getDocFromServer(參照)

從伺服器讀取這個 DocumentReference 參照的文件。如果無法使用網路,則傳回錯誤。

簽名:

export declare function getDocFromServer<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<DocumentSnapshot<AppModelType, DbModelType>>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType>

傳回:

Promise<DocumentSnapshot<AppModelType, DBMModelType>>

Promise 已透過 DocumentSnapshot 解決,其中包含目前的文件內容。

onSnapshot(參照, 觀察器)

附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, observer: {
    next?: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要聆聽的文件參照。
觀察者 { 下一個?:(快照:DocumentSnapshot<AppModelType, DBMModelType>) =>無效;錯誤訊息?(錯誤:FirestoreError) =>無效;完成?:() =>無效;} 包含 nexterror 回呼的單一物件。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(參照、選項、觀察器)

附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, options: SnapshotListenOptions, observer: {
    next?: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void;
    error?: (error: FirestoreError) => void;
    complete?: () => void;
}): Unsubscribe;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要聆聽的文件參照。
選項 SnapshotListenOptions 控制聆聽行為的選項。
觀察者 { 下一個?:(快照:DocumentSnapshot<AppModelType, DBMModelType>) =>無效;錯誤訊息?(錯誤:FirestoreError) =>無效;完成?:() =>無效;} 包含 nexterror 回呼的單一物件。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(reference, onNext, onError, oncomplete)

附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, onNext: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要聆聽的文件參照。
下一本 (快照:DocumentSnapshot<AppModelType, DBMModelType>) =>void 每當有新的 DocumentSnapshot 可用時,要呼叫的回呼。
onError (錯誤:FirestoreError) =>void 當監聽失敗或取消時,要呼叫的回呼。這樣就不會再次進行回呼。
完成時 () =>void 可以提供,但不會呼叫,因為串流一律不會結束。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

onSnapshot(reference, options, onNext, onError, oncomplete)

附加 DocumentSnapshot 事件的事件監聽器。您可以傳遞個別的 onNextonError 回呼,也可以使用 nexterror 回呼傳遞單一觀察器物件。

注意:雖然您可以提供 onCompletion 回呼,但由於快照串流絕不會結束,因此一律不會呼叫此方法。

簽名:

export declare function onSnapshot<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, options: SnapshotListenOptions, onNext: (snapshot: DocumentSnapshot<AppModelType, DbModelType>) => void, onError?: (error: FirestoreError) => void, onCompletion?: () => void): Unsubscribe;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要聆聽的文件參照。
選項 SnapshotListenOptions 控制聆聽行為的選項。
下一本 (快照:DocumentSnapshot<AppModelType, DBMModelType>) =>void 每當有新的 DocumentSnapshot 可用時,要呼叫的回呼。
onError (錯誤:FirestoreError) =>void 當監聽失敗或取消時,要呼叫的回呼。這樣就不會再次進行回呼。
完成時 () =>void 可以提供,但不會呼叫,因為串流一律不會結束。

傳回:

取消訂閱

可呼叫取消訂閱函式來取消快照事件監聽器。

setDoc(參照, 資料)

寫入這個DocumentReference所參照的文件。如果文件不存在,系統會建立文件。

簽名:

export declare function setDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: WithFieldValue<AppModelType>): Promise<void>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要寫入的文件參照。
資料 WithFieldValue<AppModelType> 文件的欄位和值的對應。

傳回:

承諾<void>

資料成功寫入後端後,Promise 就會解析 (請注意,資料在離線時無法解析)。

setDoc(參照, 資料, 選項)

寫入指定 DocumentReference 所參照的文件。如果文件不存在,系統會建立文件。如果您提供 mergemergeFields,所提供的資料可以合併為現有文件。

簽名:

export declare function setDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: PartialWithFieldValue<AppModelType>, options: SetOptions): Promise<void>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要寫入的文件參照。
資料 PartialWithFieldValue<AppModelType> 文件的欄位和值的對應。
選項 設定選項 用來設定設定行為的物件。

傳回:

承諾<void>

資料成功寫入後端後,Promise 就已順利解決 (請注意,問題在離線期間無法解析)。

updateDoc(參照, 資料)

更新指定 DocumentReference 所參照文件中的欄位。如果套用至不存在的文件,更新就會失敗。

簽名:

export declare function updateDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, data: UpdateData<DbModelType>): Promise<void>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要更新文件的參照。
資料 UpdateData<DbModelType> 物件,內容包含要更新文件的欄位和值。欄位可以包含半形句號,以參照文件中的巢狀欄位。

傳回:

承諾<void>

資料成功寫入後端後,Promise 就會解析 (請注意,資料在離線時無法解析)。

updateDoc(reference, 欄位, 值, moreFieldsAndValues)

更新指定 DocumentReference 所參照文件中的欄位,如果套用至不存在的文件,更新作業就會失敗。

透過提供以點分隔的欄位路徑字串或 FieldPath 物件,即可更新巢狀欄位。

簽名:

export declare function updateDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): Promise<void>;

參數

參數 類型 說明
參考資料 DocumentReference<AppModelType、DundModelType> 要更新文件的參照。
欄位 字串 |FieldPath 要更新的第一個欄位。
不明 第一個值。
moreFieldsAndValues 不明 [] 其他鍵/值組合。

傳回:

承諾<void>

資料成功寫入後端後,Promise 就會解析 (請注意,資料在離線時無法解析)。

function(設定, ...)

memoryLocalCache(設定)

建立 MemoryLocalCache 的執行個體。執行個體可設為 FirestoreSettings.cache,讓 SDK 知道要使用哪個快取層。

簽名:

export declare function memoryLocalCache(settings?: MemoryCacheSettings): MemoryLocalCache;

參數

參數 類型 說明
設定 MemoryCacheSettings

傳回:

MemoryLocalCache

memoryLruGarbageCollector(設定)

建立 MemoryLruGarbageCollector 的執行個體。

可以在設定參數中指定目標大小。一旦快取大小超過指定大小,收集器就會開始刪除文件。預設快取大小為 40 MB (40 * 1024 * 1024 個位元組)。

簽名:

export declare function memoryLruGarbageCollector(settings?: {
    cacheSizeBytes?: number;
}): MemoryLruGarbageCollector;

參數

參數 類型 說明
設定 {cacheSizeBytes?: 數字;}

傳回:

MemoryLruGarbageCollector

PersistentLocalCache(設定)

建立 PersistentLocalCache 的執行個體。執行個體可設為 FirestoreSettings.cache,讓 SDK 知道要使用哪個快取層。

您無法在 Node.js 環境中使用永久快取。

簽名:

export declare function persistentLocalCache(settings?: PersistentCacheSettings): PersistentLocalCache;

參數

參數 類型 說明
設定 PersistentCacheSettings

傳回:

PersistentLocalCache

PersistentSingleTabManager(設定)

建立 PersistentSingleTabManager 的執行個體。

簽名:

export declare function persistentSingleTabManager(settings: PersistentSingleTabManagerSettings | undefined): PersistentSingleTabManager;

參數

參數 類型 說明
設定 PersistentSingleTabManagerSettings |未定義 設定已建立的分頁管理員。

傳回:

PersistentSingleTabManager

function(快照, ...)

endAt(快照)

建立 QueryEndAtConstraint,將結果集修改至提供的文件 (包含)。結束位置與查詢的順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。

簽名:

export declare function endAt<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;

參數

參數 類型 說明
快照 DocumentSnapshot<AppModelType、DundModelType> 結尾文件的快照。

傳回:

QueryEndAtConstraint

要傳遞至 query()QueryEndAtConstraint

endBefore(快照)

建立 QueryEndAtConstraint,將結果集修改為在提供的文件前結束 (不含)。結束位置與查詢的順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。

簽名:

export declare function endBefore<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryEndAtConstraint;

參數

參數 類型 說明
快照 DocumentSnapshot<AppModelType、DundModelType> 文件的結束日期。

傳回:

QueryEndAtConstraint

要傳遞至 query()QueryEndAtConstraint

startAfter(快照)

建立 QueryStartAtConstraint,藉此修改結果集在提供的文件後方開頭 (不含)。起始位置與查詢順序相關。文件必須包含查詢的 orderBy 中所提供的所有欄位。

簽名:

export declare function startAfter<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryStartAtConstraint;

參數

參數 類型 說明
快照 DocumentSnapshot<AppModelType、DundModelType> 文件的開始日期。

傳回:

QueryStartAtConstraint

要傳遞至 query()QueryStartAtConstraint

startAt(快照)

建立 QueryStartAtConstraint,以將結果集修改為在提供的文件 (包含) 上。起始位置與查詢順序相關。文件必須包含這項查詢的 orderBy 中提供的所有欄位。

簽名:

export declare function startAt<AppModelType, DbModelType extends DocumentData>(snapshot: DocumentSnapshot<AppModelType, DbModelType>): QueryStartAtConstraint;

參數

參數 類型 說明
快照 DocumentSnapshot<AppModelType、DundModelType> 文件的快照畫面。

傳回:

QueryStartAtConstraint

要傳遞至 query()QueryStartAtConstraint

函式(值, ...)

vector(值)

使用指定數字陣列的副本建立新的 VectorValue

簽名:

export declare function vector(values?: number[]): VectorValue;

參數

參數 類型 說明
數字 [] 使用這個數字陣列的副本建立 VectorValue 執行個體。

傳回:

VectorValue

使用指定數字陣列的副本建構的新 VectorValue

CACHE_SIZE_UNLIMITED

用來表示應停用 LRU 垃圾收集的常數。在傳遞至 Firestore 執行個體的設定中,將這個值設為 cacheSizeBytes

簽名:

CACHE_SIZE_UNLIMITED = -1

新增前置字串至索引鍵

傳回新的地圖,其中每個鍵都加上一個點的外鍵。

簽名:

export declare type AddPrefixToKeys<Prefix extends string, T extends Record<string, unknown>> = {
    [K in keyof T & string as `${Prefix}.${K}`]+?: string extends K ? any : T[K];
};

匯總欄位類型

Firestore 支援的所有 AggregateField 類型聯集。

簽名:

export declare type AggregateFieldType = ReturnType<typeof sum> | ReturnType<typeof average> | ReturnType<typeof count>;

匯總規格資料

這種類型的鍵來自 AggregateSpec,其值是來自輸入 AggregateSpec 的相應 AggregateField 匯總結果。

簽名:

export declare type AggregateSpecData<T extends AggregateSpec> = {
    [P in keyof T]: T[P] extends AggregateField<infer U> ? U : never;
};

匯總類型

代表要執行的匯總類型。

簽名:

export declare type AggregateType = 'count' | 'avg' | 'sum';

ChildUpdateFields (子項更新欄位)

計算指定類型 T1 的巢狀欄位的輔助程式。這樣才能分配聯集類型,例如 undefined | {...} (若為選用道具) 或 {a: A} | {b: B}

在此用途中,由於 T[K] 是以運算式形式評估而非分散式,因此 V 會在 Record 上發布 T[K] 的聯集類型。

詳情請參閱 https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types

簽名:

export declare type ChildUpdateFields<K extends string, V> = V extends Record<string, unknown> ? AddPrefixToKeys<K, UpdateData<V>> : never;

文件變更類型

DocumentChange 的類型可「新增」、「已移除」或「已修改」。

簽名:

export declare type DocumentChangeType = 'added' | 'removed' | 'modified';

FirestoreErrorCode

Firestore 狀態碼組合。這些代碼與 gRPC 所公開的程式碼相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md

可能的值:-「cancelled」:作業已取消 (通常是呼叫端)。-「未知」:未知的錯誤或其他錯誤網域的錯誤。-「 invalid-argument」:用戶端指定的引數無效。請注意,這與「failed-precondition」不同。「無效引數」會指出無論系統狀態為何有問題的引數 (例如無效欄位名稱)。-「超過期限」:在作業完成前已過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,伺服器雖然成功回應,但延遲時間太久,因而超過期限。-「找不到」:找不到某些要求的文件。-「已存在」:一些我們嘗試建立的文件已經存在。-「權限遭拒」:呼叫者沒有執行指定作業的權限。-「資源用盡」:已耗盡某些資源,也許是每位使用者的配額,或是整個檔案系統空間不足。-「failed-precondition」:由於系統未處於執行作業所需的狀態,因此作業遭拒。-「已中止」:作業已取消,通常是因為交易取消等並行問題所導致。-「超出範圍」:嘗試執行的作業超出有效範圍。-「未實作」:未執行或不支援/未啟用作業。-「internal」:發生內部錯誤。意味著基礎系統預期的某些不變量已被破壞。如果看到這類錯誤,表示已經完全損壞。-「無法使用」:目前無法使用服務。這很可能是一個暫時的情況,並可透過重試輪詢來修正。-「data-loss」:無法復原的資料遺失或損毀。-「unauthenticated」:要求沒有作業的有效驗證憑證。

簽名:

export declare type FirestoreErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';

FirestoreLocalCache

所有支援的 SDK 快取層的聯合類型。

簽名:

export declare type FirestoreLocalCache = MemoryLocalCache | PersistentLocalCache;

監聽來源

說明查詢監聽的來源。

設為 default 即可監聽快取和伺服器變更。設為 cache 即可僅監聽快取的變更。

簽名:

export declare type ListenSource = 'default' | 'cache';

MemoryGarbageCollector

所有支援記憶體本機快取垃圾收集器的聯合類型。

簽名:

export declare type MemoryGarbageCollector = MemoryEagerGarbageCollector | MemoryLruGarbageCollector;

NestedUpdateFields

在每個欄位 (例如「bar」) 中,找出所有巢狀鍵 (例如 {'bar.baz': T1, 'bar.qux': T2})。將這些元素相交,以建立單一地圖,內含所有可能標示為選填的索引鍵

簽名:

export declare type NestedUpdateFields<T extends Record<string, unknown>> = UnionToIntersection<{
    [K in keyof T & string]: ChildUpdateFields<K, T[K]>;
}[keyof T & string]>;

OrderByDirection

orderBy() 子句的方向指定為「desc」或「asc」(遞減或遞增)。

簽名:

export declare type OrderByDirection = 'desc' | 'asc';

部分包含欄位值

與 TypeScript 的 Partial<T> 類似,但允許省略巢狀欄位,並將 FieldValues 做為屬性值傳遞。

簽名:

export declare type PartialWithFieldValue<T> = Partial<T> | (T extends Primitive ? T : T extends {} ? {
    [K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
} : never);

PersistentTabManager

所有可用分頁管理員的聯集。

簽名:

export declare type PersistentTabManager = PersistentSingleTabManager | PersistentMultipleTabManager;

基本

原始類型。

簽名:

export declare type Primitive = string | number | boolean | undefined | null;

查詢限制類型

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

簽名:

export declare type QueryConstraintType = 'where' | 'orderBy' | 'limit' | 'limitToLast' | 'startAt' | 'startAfter' | 'endAt' | 'endBefore';

查詢篩選器限制

QueryFilterConstraint 是代表 QueryFieldFilterConstraintQueryCompositeFilterConstraint 的輔助聯集類型。

簽名:

export declare type QueryFilterConstraint = QueryFieldFilterConstraint | QueryCompositeFilterConstraint;

查詢非篩選器限制

QueryNonFilterConstraint 是代表 QueryConstraint 的輔助聯集類型,可用於縮小文件集範圍或排序,但不會明確篩選文件欄位。QueryNonFilterConstraint系統會透過叫用 orderBy()startAt()startAfter()endBefore()endAt()limit()limitToLast() 建立,並傳送給 limitToLast() 以建立含有新查詢的 limitToLast() 執行個體。QueryConstraint

簽名:

export declare type QueryNonFilterConstraint = QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint;

SetOptions

一種選項物件,用於設定 setDoc() 的行為並呼叫。您可以藉由為 SetOptions 提供 merge: true,將這些呼叫設為執行精細的合併,而非覆寫整個目標文件。

簽名:

export declare type SetOptions = {
    readonly merge?: boolean;
} | {
    readonly mergeFields?: Array<string | FieldPath>;
};

工作狀態

代表套件載入工作的狀態。

兩者皆「錯誤」和「成功」即將停止狀態:工作會取消或完成,且回報後就不會再更新。

簽名:

export declare type TaskState = 'Error' | 'Running' | 'Success';

聯合交集

假設使用的是聯集類型 U = T1 | T2 | ...,會傳回交集類型 (T1 & T2 & ...)

使用分配的條件類型和從條件式類型推論。這之所以能運作,是因為在相反變化版本位置中,相同類型變數的多個候選項目會被推斷出十字路口類型。https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-inference-in-conditional-types https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type

簽名:

export declare type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;

更新資料

更新資料 (適用於與 updateDoc() 搭配使用),由由對應值的欄位路徑 (例如「foo」或「foo.baz」) 組成。含有點的欄位會參照文件中的巢狀欄位。FieldValues 可以做為屬性值傳入。

簽名:

export declare type UpdateData<T> = T extends Primitive ? T : T extends {} ? {
    [K in keyof T]?: UpdateData<T[K]> | FieldValue;
} & NestedUpdateFields<T> : Partial<T>;

whereFilterOp

where() 子句中的篩選條件是使用「&lt;」、「&lt;='」、「'==', '!='、'&gt;=', '&gt;'」、「array-contains'、'in', 'array-contains-any'」和「not-in'」等字串。

簽名:

export declare type WhereFilterOp = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';

含欄位值

允許將 FieldValues 做為屬性值傳入,同時維持類型安全性。

簽名:

export declare type WithFieldValue<T> = T | (T extends Primitive ? T : T extends {} ? {
    [K in keyof T]: WithFieldValue<T[K]> | FieldValue;
} : never);