@firebase/firestore/lite

函式

函式 說明
功能(應用程式, ...)
getFirestore(應用程式) 傳回與所提供 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
getFirestore(應用程式, 資料庫 ID) (Beta 版) 傳回與所提供 FirebaseApp 相關聯的現有 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
InitialFirestore(應用程式, 設定) 根據提供的設定來初始化新的 Cloud Firestore 執行個體。只能在其他任何函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()
InitialFirestore(應用程式, 設定, 資料庫 ID) (Beta 版) 使用提供的設定來初始化 Cloud Firestore 的新執行個體。只能在其他任何函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()
功能(Firestore, ...)
collection(Firestore, path, pathSegments) 取得參照指定絕對路徑集合的 CollectionReference 例項。
collectionGroup(firestore, collectionId) 建立並傳回新的 Query 執行個體,其中包含資料庫中含有指定 collectionId 的集合或子集合中的所有文件。
connectFirestoreEmulator(Firestore、主機、通訊埠、選項) 請修改這個執行個體,以便與 Cloud Firestore 模擬器通訊。注意:在使用這個執行個體執行任何作業前,必須先呼叫這個執行個體。
doc(Firestore, path, pathSegments) 取得參照指定絕對路徑文件的 DocumentReference 例項。
runTransaction(firestore, updateFunction, options) 執行指定的 updateFunction,然後嘗試修訂交易中套用的變更。如果在交易中讀取過任何文件,Cloud Firestore 會重試 updateFunction。如果嘗試 5 次後仍無法修訂,交易就會失敗。單一交易中允許的寫入數量上限為 500。
終止(火災) 終止提供的 Firestore 執行個體。呼叫 terminate() 後,只能使用 clearIndexedDbPersistence() 函式。任何其他函式都會擲回 FirestoreError。終止不會取消任何待處理的寫入作業,等待伺服器回應的任何承諾也不會解決。如要在終止後重新啟動,請使用 getFirestore() 建立新的 Firestore 執行個體。注意:在正常情況下,不需要呼叫 terminate()。只有當您想強制這個執行個體釋出其所有資源,或與 clearIndexedDbPersistence() 併用時,才適合使用這個函式,以確保所有本機狀態在測試執行之間會全部刪除。
writeBatch(Firestore) 建立寫入批次,用來以單一不可分割作業的形式執行多次寫入。單一 WriteBatch 允許的寫入數量上限為 500。只有在傳回承諾後發生的文件讀取作業中,這些寫入結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
function()
count() 建立 AggregateField 物件,以計算查詢結果集中的文件數量。
deleteField() 傳回一個 sendinel 與 updateDoc()setDoc(){merge: true},用於標示要刪除的欄位。
documentId() 傳回特殊的印記 FieldPath,用來參照文件 ID。可在查詢中使用,依文件 ID 排序或篩選。
getFirestore() 傳回與預設 FirebaseApp 相關聯的現有預設 Firestore 執行個體。如果沒有執行個體,則使用預設設定初始化新的執行個體。
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,根據查詢順序,將結果集修改成從提供的欄位開始。欄位值的順序必須與查詢子句的順序相符。
功能(左側, ...)
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(查詢, ...)
getAggregate(query, aggregateSpec) 這個外掛程式能針對指定查詢結果集中的文件計算指定的匯總次數,且不會實際下載文件。由於只有最終匯總值,而非文件,因此使用此函式執行匯總作業非常有效率。下載及下載如果結果集過大,無法完全下載 (數千份文件),這個函式就能執行文件匯總作業。
getCount(查詢) 這個外掛程式能計算指定查詢結果集中的文件數量,但不需實際下載文件。由於只有最終計數,而非文件,因此使用這個函式計算文件非常有效率。資料,在 Kubernetes 中如果結果集極大 (一千份文件),這個函式就能計算文件數量。
getDoc(查詢) 執行查詢並以 QuerySnapshot 傳回結果。所有查詢均由伺服器直接執行,即使查詢先前已執行也一樣。最近修改過的修改只有在後端已套用的情況下,才會反映在擷取的結果中。如果用戶端處於離線狀態,作業就會失敗。如要查看之前快取的結果和本機修改內容,請使用完整 Firestore SDK。
query(query, CompositeFilter, queryConstraints) 建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。
query(query, queryConstraints) 建立不可變的新 Query 執行個體,擴充為包含其他查詢限制。
function(queryConstraints, ...)
and(queryConstraints) 建立結合指定篩選器限制的新 QueryCompositeFilterConstraint。如果文件符合所有指定篩選條件,系統就會加入一份文件。
or(queryConstraints) 建立新的 QueryCompositeFilterConstraint,為指定篩選器限制條件的分離。解譯篩選器會納入符合任一指定篩選條件的文件。
function(參考資料, ...)
addDoc(參考資料, 資料) 使用指定資料在指定的 CollectionReference 中新增文件,並自動指派文件 ID。只有在傳回承諾後發生的文件讀取作業中,這項寫入的結果才會反映。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
collection(reference, path, pathSegments) 取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。
collection(reference, path, pathSegments) 取得參照指定相對路徑中 reference 子集合的 CollectionReference 例項。
deleteDoc(參考資料) 刪除指定的 DocumentReference 參照的文件。只有在傳回的承諾產品解決後,系統才會在文件朗讀中反映刪除作業。如果用戶端處於離線狀態,刪除作業就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
doc(reference, path, pathSegments) 取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。如未指定路徑,傳回的 DocumentReference 將使用系統自動產生的專屬 ID。
doc(reference, path, pathSegments) 取得參照指定相對路徑 reference 中文件的 DocumentReference 例項。
getDoc(參考資料) 這個外掛程式能讀取指定文件參照參照的文件。所有文件都會直接從伺服器擷取,即使先前已讀取或修改文件也一樣。最近修改過的修改只有在後端已套用的情況下,才會反映在擷取的 DocumentSnapshot 中。如果用戶端處於離線狀態,讀取作業就會失敗。如要使用快取或查看本機修改內容,請使用完整 Firestore SDK。
setDoc(參照, 資料) 寫入指定 DocumentReference 參照的文件。如果文件尚未存在,系統就會建立文件。只有在傳回的承諾產品解決後,系統才會在文件讀取作業中顯示此寫入結果。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
setDoc(參照、資料、選項) 寫入指定 DocumentReference 參照的文件。如果文件不存在,系統會建立文件。如果您提供 mergemergeFields,所提供的資料可以合併至現有文件。只有在傳回承諾後發生的文件讀取作業中,這項寫入的結果才會反映。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
updateDoc(參照, 資料) 更新指定 DocumentReference 所參照文件中的欄位。如果套用至不存在的文件,更新就會失敗。只有在傳回的承諾產品解決後,更新作業的結果才會反映在文件中。如果用戶端處於離線狀態,更新就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
updateDoc(參照, 欄位, 值, 更多 FieldsAndValues) 指定 DocumentReference 所參照的文件中的欄位更新,如果套用於不存在的文件,更新將會失敗。您可以透過提供以點分隔的欄位路徑字串或提供 FieldPath 物件來更新巢狀欄位。只有傳回承諾後發生的文件讀取作業,才會反映這項更新的結果。如果用戶端處於離線狀態,更新就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。
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]。
查詢 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 的新查詢執行個體。
時間戳記 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 指定一組匯總及其別名。
文件資料 文件資料 (用於 setDoc()) 包含對應至值的欄位。
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
設定 指定 Cloud Firestore 執行個體的自訂設定。您必須先設定這些設定,才能叫用其他方法。
交易選項 自訂交易行為的選項。

型別別名

類型別名 說明
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
FirestoreErrorCode Firestore 狀態碼組合。這些代碼與 gRPC 所公開的代碼相同:https://github.com/grpc/grpc/blob/master/doc/statuscodes.md可能的值:- 'cancelled':作業已取消 (通常是呼叫端)。-「未知」:未知的錯誤或其他錯誤網域的錯誤。-「 invalid-argument」:用戶端指定的引數無效。請注意,這與「failed-precondition」不同。「無效引數」會指出無論系統狀態為何有問題的引數 (例如無效欄位名稱)。-「超過期限」:在作業完成前已過期。針對變更系統狀態的作業,即使作業已成功完成,也可能傳回此錯誤。例如,伺服器雖然成功回應,但延遲時間太久,因而超過期限。-「找不到」:找不到某些要求的文件。-「已存在」:一些我們嘗試建立的文件已經存在。-「權限遭拒」:呼叫者沒有執行指定作業的權限。-「資源用盡」:已耗盡某些資源,也許是每位使用者的配額,或是整個檔案系統空間不足。-「failed-precondition」:由於系統未處於執行作業所需的狀態,因此作業遭拒。-「已中止」:作業已取消,通常是因為交易取消等並行問題所導致。-「超出範圍」:嘗試執行的作業超出有效範圍。-「未實作」:未執行或不支援/未啟用作業。-「internal」:發生內部錯誤。意味著基礎系統預期的某些不變量已被破壞。如果看到這類錯誤,表示已經完全損壞。-「無法使用」:目前無法使用服務。這很可能是一個暫時的情況,並可透過重試輪詢來修正。-「data-loss」:無法復原的資料遺失或損毀。-「unauthenticated」:要求沒有作業的有效驗證憑證。
NestedUpdateFields 在每個欄位 (例如「bar」) 中,找出所有巢狀鍵 (例如 {'bar.baz': T1, 'bar.qux': T2})。將這些元素相交,以建立單一地圖,內含所有可能標示為選填的索引鍵
OrderByDirection orderBy() 子句的方向指定為「desc」或「asc」(遞減或遞增)。
PartialWithFieldValue 與 TypeScript 的 Partial<T> 類似,但允許省略巢狀欄位,並將 FieldValues 做為屬性值傳遞。
基本 原始類型。
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(應用程式, 設定)

根據提供的設定來初始化新的 Cloud Firestore 執行個體。只能在其他任何函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()

簽名:

export declare function initializeFirestore(app: FirebaseApp, settings: Settings): Firestore;

參數

參數 類型 說明
應用程式 Firebase 應用程式 Firestore 執行個體建立關聯的 FirebaseApp
設定 設定 用於設定 Firestore 執行個體的設定物件。

傳回:

Firestore

剛初始化的 Firestore 例項。

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

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

根據提供的設定來初始化新的 Cloud Firestore 執行個體。只能在其他任何函式之前呼叫,包括 getFirestore()。如果自訂設定空白,此函式就等同於呼叫 getFirestore()

簽名:

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

參數

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

傳回:

Firestore

剛初始化的 Firestore 例項。

函式(Firestore, ...)

收集(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

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 例項。

例外狀況

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

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 傳回的承諾。否則,如果交易失敗,系統就會傳回拒絕承諾,並顯示對應的失敗錯誤。

終止(Firestore)

終止提供的 Firestore 執行個體。

呼叫 terminate() 後,只能使用 clearIndexedDbPersistence() 函式。任何其他函式都會擲回 FirestoreError。終止不會取消任何待處理的寫入作業,系統也不會解決任何等待伺服器回應的承諾。

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

簽名:

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

參數

參數 類型 說明
firestore Firestore 要終止的 Firestore 執行個體。

傳回:

承諾<void>

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

WriteBatch(Firestore)

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

只有在傳回的承諾產品解析後,這些寫入結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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 執行個體。

伺服器時間戳記()

傳回與 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

函式(左側, ...)

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(查詢, ...)

getAggregate(query, aggregateSpec)

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

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

簽名:

export declare function getAggregate<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 getAggregate(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;

getCount(查詢)

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

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

簽名:

export declare function getCount<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 形式傳回結果。

所有查詢都是由伺服器直接執行,即使查詢先前已執行也一樣。最近修改過的修改只有在後端已套用的情況下,才會反映在擷取的結果中。如果用戶端處於離線狀態,作業就會失敗。如要查看之前快取的結果和本機修改內容,請使用完整 Firestore SDK。

簽名:

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

參數

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

傳回:

Promise<QuerySnapshot<AppModelType, DBMModelType>>

將與查詢結果解析的 Promise。

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。

只有在傳回的承諾產品解決後,寫入作業的結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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 解析,在文件寫入後端後指向新建立的文件。

例外狀況

錯誤 - 如果提供的輸入內容不是有效的 Firestore 文件,

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 參照的文件。

只有在傳回的承諾產品解決後,系統才會在文件讀取作業中反映刪除作業。如果用戶端處於離線狀態,刪除作業就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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(參照)

這個外掛程式能讀取指定文件參照所參照的文件。

所有文件都會直接從伺服器擷取,即使文件先前已讀取或修改過也一樣。最近修改過的修改只有在後端已套用的情況下,才會反映在擷取的 DocumentSnapshot 中。如果用戶端處於離線狀態,讀取作業就會失敗。如要使用快取或查看本機修改內容,請使用完整 Firestore SDK。

簽名:

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 解析。

setDoc(參照, 資料)

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

只有在傳回的承諾產品解決後,寫入作業的結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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

參數

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

傳回:

承諾<void>

一旦資料成功寫入後端,Promise 就會解析。

例外狀況

錯誤 - 如果提供的輸入內容不是有效的 Firestore 文件,

setDoc(參照, 資料, 選項)

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

只有在傳回的承諾產品解決後,寫入作業的結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,寫入就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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 就會解析。

例外狀況

錯誤 - 如果提供的輸入內容不是有效的 Firestore 文件,

updateDoc(參照, 資料)

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

只有在傳回的承諾產品解決後,這項更新的結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,更新就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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

參數

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

傳回:

承諾<void>

一旦資料成功寫入後端,Promise 就會解析。

例外狀況

錯誤 - 如果提供的輸入內容不是有效的 Firestore 資料,

updateDoc(reference, 欄位, 值, moreFieldsAndValues)

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

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

只有在傳回的承諾產品解決後,這項更新的結果才會反映在文件讀取作業中。如果用戶端處於離線狀態,更新就會失敗。如想在用戶端上線前查看本機修改或緩衝區寫入作業,請使用完整 Firestore SDK。

簽名:

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 就會解析。

例外狀況

錯誤 - 如果提供的輸入內容不是有效的 Firestore 資料,

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

新增前置字串至索引鍵

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

簽名:

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;

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';

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);

基本

原始類型。

簽名:

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>;
};

聯合交集

假設使用的是聯集類型 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);