iT邦幫忙

2019 iT 邦幫忙鐵人賽

DAY 21
0
Modern Web

我或許沒那麼懂 Web系列 第 21

Cloud Firestore β (13): API 研究

前天在編寫範例程式碼時,對於物件類別有點疑惑,所以今天就來花點時間研究 Reference 吧。

這邊以研究 JS 為主,JS 的 SDK 又有分為用於 Web 環境的 JavaScript ,以及用於 Server 環境(待查證)的 Node.js 兩種,但在單就 firebase.firestore 下的 API 目前看起來是沒有差異的。

依照類別與介面來分

以下是 firebase.firestore 下的類別與介面:

類別

  • CollectionReference
  • FieldPath
  • GeoPoint
  • QueryDocumentSnapshot
  • Timestamp

介面

  • Interfaces
  • Blob
  • DocumentChange
  • DocumentReference
  • DocumentSnapshot
  • FieldValue
  • Firestore
  • FirestoreError
  • GetOptions
  • Query
  • QuerySnapshot
  • SetOptions
  • Settings
  • SnapshotListenOptions
  • SnapshotMetadata
  • SnapshotOptions
  • Transaction
  • WriteBatch

目前用過的

最一開始我們會透過 firebase.initializeApp() 去設定 Firebase 的連線資料,該方法的簽署式為:

firebase.initializeApp(options, name) returns firebase.app.App

不過目前我們只會用來設定,不會去管它的回傳值。在設定後,我們會透過 firebase.firestore() 取得 firebase.firestore.Firestore 的實例。而實例我們目前只用到也最常用到的方法如下:

- `collection(collectionPath) returns firebase.firestore.CollectionReference`
- `doc(documentPath) returns firebase.firestore.DocumentReference`

可以看到這兩個方法分別會得到集合參照(CollectionReference)和文件參照(DocumentReference)。其中集合參照又擴充自 firebase.firestore.Query,所以我們就先來看看 Query 提供的方法吧!

首先是用來查詢用的相關方法,這些方法都回傳 Query,所以我們可以用方法鏈的方式將所有查詢資訊串起來。至於這些方法還沒提到的部分,就等之後再另外開一篇吧。

  • where(fieldPath, opStr, value) returns firebase.firestore.Query
  • orderBy(fieldPath, directionStr) returns firebase.firestore.Query
  • limit(limit) returns firebase.firestore.Query
  • startAt(snapshotOrVarArgs) returns firebase.firestore.Query
  • endAt(snapshotOrVarArgs) returns firebase.firestore.Query
  • startAfter(snapshotOrVarArgs) returns firebase.firestore.Query
  • endBefore(snapshotOrVarArgs) returns firebase.firestore.Query

而呼叫以上方法時,還不會馬上對 Cloud Firestore 提出 request,而是等到使用 get() 方法時才會去抓取資料。

  • get(options) returns firebase.firestore.QuerySnapshot

get() 方法,就會回傳原型為 firebase.firestore.QuerySnapshot 的物件。這個原型提供幾個:

  • docs: 回傳不為 null 的 Array,且裡面都是以 firebase.firestore.QueryDocumentSnapshot 為原型且不為 null 的物件。
  • empty: 布林值。
  • query: 回傳讓我們得到這個 QuerySnapshotQuery
  • size: 回傳數字。

方法中我們目前有用到的就是:

  • forEach(callback, thisArg)

forEach 中的 callback 的簽署式則是:

  • function(non-null firebase.firestore.QueryDocumentSnapshot)

也就是會迭代回傳以 QueryDocumentSnapshot 為原型的物件,讓我們透過其方法去取得我們要的資料,方法如下:

  • data(options) returns (firebase.firestore.Firestore~DocumentData or undefined)
  • get(fieldPath, options) returns (any type or undefined)

前者是拿取該文件的所有資料,後者則是拿取該文件指定欄位的資料。到這邊就算是把集合到資料的流程順過一次了。然後我們再度回到透過 firebase.firestore.Firestore.doc() 取得的 DocumentReference 吧!

先從我們前面提到過的獲取、新增、更新、刪除,也就是 CRUD 的四個方法吧!

  • get(options) returns Promise containing non-null firebase.firestore.DocumentSnapshot
  • set(data, options) returns Promise containing void
  • update(...var_args) returns Promise containing void
  • delete() returns Promise containing void

可以看到四個方法都會返回 Promise 物件,我們才因此得以使用 then()catch() 去處理成功和失敗的狀況,其中 get() 方法的 Promise 會包含 DocumentSnapshot,而前面提到的 QueryDocumentSnapshot 正是擴充自 DocumentSnapshot,所以兩者擁有相同的方法介面,所以方法這邊就不重複提了。

回到 DocumentReferencecollection() 方法,該方法會讓我們拿到 CollectionReference

  • collection(collectionPath) returns firebase.firestore.CollectionReference

CollectionReference 又提供 doc() 方法讓我們拿到 CollectionReference

  • doc(documentPath) returns firebase.firestore.DocumentReference

所以我們就可以透過這種方式從集合中拿到某文件,再從文件拿到他下面的某個集合,依此類推。而 CollectionReference 除了比 Query 多出了 doc() 方法外,還有我們之前用來新增資料的 `add() 方法:

  • add(data) returns Promise containing non-null firebase.firestore.DocumentReference

到了這邊,前面提過的方法和得到的物件原型/類別都大概提過了,感覺在認知是有比較有系統了呢。那我們明天再繼續研究下去吧!


上一篇
Cloud Firestore β (12): 初始化
下一篇
Cloud Firestore β (14): 進階查詢 - 1
系列文
我或許沒那麼懂 Web31

尚未有邦友留言

立即登入留言