專案：Amphibians 應用程式

1. 事前準備

本程式碼研究室將說明如何自行建構一款名為「Amphibians」的新應用程式。我們會引導您逐步完成 Amphibians 應用程式專案，包括在 Android Studio 中設定和測試專案。

必要條件

  • 此專案適用於已完成 Kotlin 課程中 Android 基本概念單元 4 的使用者。

建構項目

  • 使用 Retrofit 和 Moshi 以及適當的錯誤處理方式，在應用程式中實作網路。

軟硬體需求

  • 已安裝 Android Studio 的電腦。

2. 應用程式成品簡介

歡迎參與專案：Amphibians！

到目前為止，您建構的所有應用程式都依賴儲存在本機的資料。這次，您會採用顯示不同兩棲動物物種資訊的應用程式，並運用您對網路、JSON 剖析及檢視模型的知識，讓該應用程式能夠使用來自網路的資料。應用程式會從這個專案的自訂 API 中取得資料，然後顯示於清單檢視的畫面中。

在最後一個應用程式中，使用者看到的第一個畫面，會顯示回收器檢視畫面中各個物種的名稱。

7697a4e0c9bb5a76.png

輕觸清單項目即可前往詳細資料畫面，當中也會顯示物種名稱和詳細說明。

9797605a20dc68d1.png

雖然已為您建立這個應用程式的 UI 部分，但執行範例專案並不會顯示任何資料。您必須實作應用程式的網路部分，版面配置中才會顯示已下載的資料。

3. 開始操作

下載專案程式碼

請注意，資料夾名稱是 android-basics-kotlin-amphibians-app。在 Android Studio 中開啟專案時，請選取這個資料夾。

如要取得這個程式碼研究室的程式碼，並在 Android Studio 中開啟，請按照下列步驟操作：

取得程式碼

  1. 按一下上面顯示的網址。系統會在瀏覽器中開啟專案的 GitHub 頁面。
  2. 在專案的 GitHub 頁面中，按一下「Code」按鈕開啟對話方塊。

5b0a76c50478a73f.png

  1. 在對話方塊中，按一下「Download ZIP」按鈕，將專案儲存到電腦。等待下載作業完成。
  2. 在電腦中找到該檔案 (可能位於「下載」資料夾中)。
  3. 按兩下解壓縮 ZIP 檔案。這項操作會建立含有專案檔案的新資料夾。

在 Android Studio 中開啟專案

  1. 啟動 Android Studio。
  2. 在「Welcome to Android Studio」視窗中，按一下「Open an existing Android Studio project」。

36cc44fcf0f89a1d.png

注意：如果 Android Studio 已開啟，請依序選取「File」>「New」>「Import Project」選單選項。

21f3eec988dcfbe9.png

  1. 在「Import Project」對話方塊中，前往解壓縮專案資料夾所在的位置 (可能位於「下載」資料夾中)。
  2. 按兩下該專案資料夾。
  3. 等待 Android Studio 開啟專案。
  4. 按一下「Run」按鈕 11c34fc5e516fb1c.png 即可建構並執行應用程式。請確認應用程式的建構符合預期。
  5. 在「Project」工具視窗中瀏覽專案檔案，查看應用程式的設定方式。

實作 API 服務

與先前的專案一樣，我們已為您實作大部分的應用程式。您只需要運用在單元 4 中學到的知識，實作網路部分即可。您可以熟悉一下範例程式碼。您應該在單元 1 到單元 3 的課程中熟悉了大部分的概念。下列步驟會根據完成各步驟的需要而列舉程式碼的特定部分。

應用程式會列出網路中的兩棲動物資料，這些兩棲動物資料來自 API 傳回的 JSON 物件。請看看 network 套件中的 Amphibian.kt 檔案。這個類別會建立單一兩棲動物物件的模型，並會由 API 傳回該物件的清單。每種兩棲動物都有三個屬性：名稱、類型和說明。

data class Amphibian(
    val name: String,
    val type: String,
    val description: String
)

此 API 的後端相當簡單。您需要取得兩項重要資訊，才能存取兩棲動物資料，一個是基準網址，另一個則是用於取得兩棲動物清單的端點。

  1. 基準網址：https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
  2. 取得兩棲動物清單：android-basics-kotlin-unit-4-pathway-2-project-api.json

專案已有 Retrofit 和 Moshi 依附元件。您可在 network 套件中找到 AmphibianApiService.kt 檔案。檔案含有幾則 TODO 留言。請執行以下五項工作，以實作兩棲動物應用程式：

  1. 建立變數來儲存 API 的基準網址。
  2. 使用 Kotlin Adapter Factory 建構 Moshi 物件，此模式會利用 Retrofit 來剖析 JSON。
  3. 使用 Moshi 轉換工具建構 aRetrofit 執行個體。
  4. 使用 suspend 函式為每個 API 方法實作 AmphibianApiService 介面 (這個應用程式只有一個方法，即用於取得兩棲動物清單)。
  5. 建立 AmphibianApi 物件以顯示採用 AmphibianApiService 介面的延遲初始化 Retrofit 服務。

實作 ViewModel

實作 API 後，您要向 ampimbians API 發出要求，然後儲存所有需要顯示的值。您需要在 ui 套件中的 AmphibianViewModel.kt 類別中執行這項操作。

您會發現，類別宣告上方是名為 AmphibianApiStatus 的列舉。

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

三個可能的值為 LOADING、ERROR 和 DONE，用來向使用者顯示要求的狀態。

在 AmphibianViewModel.kt 類別中，您必須實作部分 LiveData 變數、與 API 互動的函式，以及用於處理詳細資料頁面上設定兩棲動物的函式。

  1. 新增一個 _status 私人 MutableLiveData 變數，可用於保留 AmphibianApiStatus 列舉和相關狀態的幕後屬性 status。
  2. 對類型 List<Amphibian> 的兩棲動物清單新增 amphibians 變數和私人幕後屬性 _amphibians。
  3. 為所選的類型 LiveData<Amphibian> 兩棲動物物件新增類型 MutableLiveData<Amphibian> 的 _amphibian 變數和幕後屬性 amphibian。此變數會用於儲存詳細資料畫面上已選定的兩棲動物。
  4. 定義名為 getAmphibianList() 的函式。使用 ViewModelScope 啟動協同程式，在協同程式中，透過呼叫 Retrofit 服務的 getAmphibians() 方法來執行 GET 要求以下載兩棲動物的資料。您需要使用 try 和 catch 來妥善處理錯誤。在提出要求之前，請將 _status 的值設為 AmphibianApiStatus.LOADING。如果要求成功，_amphibians 應設為來自伺服器的兩棲動物清單，而 _status 應設為 AmphibianApiStatus.DONE。如果發生錯誤，_amphibians 應設為空白清單，而 _status 應設為 AmphibianApiStatus.ERROR。
  5. 實作 onAmphibianClicked() 方法，將您定義的 _amphibian 屬性設為傳遞到函式的引數。在選取兩棲動物時已呼叫此方法，因此兩棲動物的資訊便會顯示在詳細資料畫面上。

從 ViewModel 更新使用者介面

實作 ViewModel 後，您只需要編輯片段類別和版面配置檔案，即可使用資料繫結。

  1. AmphibianListFragment 中已參照 ViewModel。在 onCreateView() 方法中，加載版面配置後，只需從 ViewModel 呼叫 getAmphibianList() 方法即可。
  2. 在 fragment_amphibian_list.xml 中，資料繫結變數的 <data> 標記已新增到版面配置檔案。只需實作 TODO，使用者介面就會根據檢視模型更新。為 listData 和 apiStatus 設定適當的繫結。
  3. 在 fragment_amphibian_detail.xml 中實作 TODO，以為兩棲動物的名稱和說明設定適當的文字屬性。

4. 測試操作說明

執行測試

如要執行測試，請執行下列其中一項操作：

若是單一測試案例，請開啟測試案例類別，然後按一下類別宣告左側的綠色箭頭。接著從選單中選取「Run」選項。這麼做將會執行測試案例中的所有測試。

a32317d35c77142b.png

您通常只需要執行一項測試，例如只有一個測試失敗，另一個則通過測試。執行單一測試的做法，與執行整個測試案例一樣。使用綠色箭頭並選取「Run」選項。

ac6244434cfafb60.png

如果您有多個測試案例，也可以執行整個測試套件。就像執行應用程式一樣，您可以在「Run」選單中找到這個選項。

7a925c5e196725bb.png

請注意，Android Studio 預設會執行您執行的最後一個目標 (應用程式、測試目標等)，因此如果選單仍顯示「Run」>「Run ‘app'」，您可以依序選取「Run」>「Run」以執行測試目標。

ee1e227446c536fe.png

然後從彈出式選單中選擇測試目標。

d570c947769db65c.png

測試執行結果會顯示在「Run」分頁中。左側窗格中會顯示失敗測試清單 (如果有的話)。如果測試失敗，函式名稱旁邊會標上紅色驚嘆號；如果測試通過，則會標上綠色勾號。

6d68f2bf589501ae.png

如果測試失敗，文字輸出會提供相關資訊，協助您修正導致測試失敗的問題。

92f3c8219c03651d.png

例如，在上述錯誤訊息中，測試會檢查 TextView 是否使用了特定字串資源。然而，測試失敗了。「Expected」和「Got」之後的文字不相符，代表測試預期的值與執行中應用程式的值不相符。在這個例子中，TextView 中使用的字串並非是預期的實際 squeeze_count。