建立互動式的 Dice Roller 應用程式

1. 事前準備

在本程式碼研究室中，您將建立一個 Dice Roller Android 應用程式，讓使用者能在應用程式中點選 Button 來擲骰子。擲骰子結果會顯示在螢幕上的 TextView 中。

您將使用 Android Studio 的「Layout Editor」(版面配置編輯器) 建立應用程式版面配置，然後編寫 Kotlin 程式碼，新增使用者按一下 Button 時觸發的動作。

必要條件

如何在 Android Studio 中建立及執行「Hello, World!」應用程式
熟悉在應用程式中使用 TextViews。
如何在「Layout Editor」(版面配置編輯器) 中修改 TextView 的屬性。
如何將文字擷取為字串資源，讓您更容易翻譯應用程式並重複使用字串。
Kotlin 程式設計基本概念

課程內容

如何將 Button 新增至 Android 應用程式。
如何新增輕觸應用程式 Button 時的行為。
如何開啟及修改應用程式的 Activity 程式碼。
如何顯示 Toast 訊息。
如何在應用程式執行期間更新 TextView 的內容。

建構項目

Dice Roller Android 應用程式和擲骰子的 Button，畫面上的文字會依據擲出結果更新。

軟硬體需求

已安裝 Android Studio 的電腦。

完成本程式碼研究室後，應用程式的外觀可能如下。

2. 設定應用程式

建立空白活動專案

如果已在 Android Studio 中開啟現有專案，請依序點選「File」(檔案) >「New」(新增) >「New Project…」(新專案...)，然後開啟「Create New Project」(建立新專案) 畫面。
在「Create New Project」(建立新專案) 中，使用「Empty Activity」(空白活動) 範本建立新的 Kotlin 專案。
將應用程式命名為「Dice Roller」，指定最低 API 級別 19 (KitKat)。

執行新的應用程式，看起來應該會像這樣。

3. 建立應用程式的版面配置

開啟 Layout Editor (版面配置編輯器)

在「Project」視窗中，按兩下開啟 activity_main.xml (或依序點選「app」>「res」>「layout」>「activity_main.xml」)。您應該會看到「Layout Editor」(版面配置編輯器)，且應用程式的中央只有「Hello World」TextView。

接下來，請將 Button 新增到應用程式。Button 是 Android 中的使用者介面 (UI) 元素，讓使用者輕觸即可執行動作。

在這項工作中，您將在「Hello World」TextView 下方新增 Button。TextView 和 Button 位於 ViewGroup 類型的 ConstraintLayout 中。

如果 ViewGroup 中有 Views，Views 會視為父項 ViewGroup 的子項。就您的應用程式而言，TextView 和 Button 視同父項 ConstraintLayout 的子項。

將 Button 新增為應用程式中現有 ConstraintLayout 的子項。

在版面配置中新增按鈕

將 Button 從「Palette」(區塊面板) 拖曳至「Design」(設計) 檢視畫面，並放在「Hello World」TextView 下方。

在「Component Tree」的「Palette」下方，確認 Button 和 TextView 列於 ConstraintLayout 下方 (做為 ConstraintLayout 的子項)。
請注意，Button 未受限。由於 Button 位於 ConstraintLayout 內，因此您必須設定垂直和水平限制條件進行定位。

安排按鈕的位置

在這個步驟中，您將新增從 Button 頂端到 TextView 底部的垂直限制條件。這會將 Button 放在 TextView 的下方。

在「Design」檢視畫面中，按住 Button 上方邊緣有藍色邊框的白色圓圈。拖曳指標，並箭頭會遵循指標。當您移動到「Hello World」TextView底部邊緣時放開。這項操作會建立版面配置限制條件，且 Button 往上滑至 TextView 正下方。

查看「Layout Editor」右側的「Attributes」。
請留意「Constraint Widget」中，新版面配置的限制條件設定為 TextView 的底部，例如 Top → BottomOf textView (0dp)。(0dp) 表示邊界為 0。已發生缺少水平限制條件的錯誤。

新增從 Button 的左側至父項 ConstraintLayout 的左側的水平限制條件。
於右側重複操作，將 Button 的右邊緣連接到 ConstraintLayout 的右邊緣。結果看起來會像這樣：

在仍然選取 Button 的情況下，「Constraint Widget」應如下所示。您會看到新增了兩個額外的限制條件：Start → StartOf parent (0dp) 和 End → EndOf parent (0dp)。這表示 Button 是水平置中於其父項 ConstraintLayout 中。

執行應用程式。應如以下螢幕截圖所示。您可以點選 Button，但目前還沒有任何動作。接著執行下一項工作吧！

變更按鈕文字

您將會在「Layout Editor」中進行幾項使用者介面變更。

比起將 Button 標籤改成顯示「Button」，請將標籤變更為說明按鈕將「擲骰子」。

在版面配置編輯器中，如果已選取 Button，請前往「Attributes」，將「text」變更為「Roll」，然後按下 Enter 鍵 (Mac 則是按下 Return 鍵)。

在「Component Tree」中，Button 旁邊會顯示橘色的警示三角形。只要游標懸停在三角形上，就會顯示訊息。Android Studio 在您的應用程式的程式碼中偵測到硬式編碼字串 (「Roll」)，因此建議您改用字串資源。

使用硬式編碼字串，應用程式會難以翻譯成其他語言，您也可能很難在應用程式的不同部分重複使用字串。幸好 Android Studio 已自動修正。

在「Component Tree」中點選橘色三角形。

系統隨即會顯示完整警示訊息。

在訊息底部的「Suggested Fix」下方，按一下「Fix」按鈕。(您可能需要向下捲動頁面。)
系統隨即會開啟「Extract Resource」對話方塊。擷取字串代表擷取「Roll」文字，並在 strings.xml 中建立一個名為 roll 的字串資源 (app > res > values > strings.xml)。由於預設值正確無誤，因此請按一下「OK」。

請注意，在「Attributes」中，Button 的 text 屬性現在會指向 @string/roll，也就是您剛剛建立的資源。

在「Design」(設計) 檢視畫面中，Button 應仍顯示出 Roll。

設定 TextView 的樣式

「Hello World!」文字非常小，且訊息與您的應用程式無關。在這個步驟中，您必須將小型「Hello, World!」訊息取代為數字以顯示搖骰子值，並放大字型，讓使用者一目瞭然。

在「Design Editor」中選取 TextView，以便在「Attributes」視窗中顯示其屬性。
將 TextView 的 textSize 變更為 36sp，以便放大且易讀。您可能需要捲動畫面，才能找到 textSize。

清除 TextView 的 text 屬性。您不用在 TextView 中顯示任何資訊，直到使用者擲骰子為止。

不過，當您編輯應用程式的版面配置和程式碼時，在 TextView 中查看部分文字會很有幫助。為此，您可以在 TextView 新增文字，這些文字只會顯示在版面配置預覽中，但不會在應用程式執行時顯示。

在「Component Tree」中選取 TextView。
在「Common Attributes」下方找到「text」屬性，該屬性下方會顯示含有工具圖示的另一個「text」屬性。text 屬性是在應用程式執行時顯示給使用者。含有工具圖示的「text」屬性是專為您 (開發人員) 設計的「tools text」屬性。
在 TextView 中將工具文字設定為「1」(假設您有一個顯示「1」的骰子)。「1」只會出現在 Android Studio 的「Design Editor」中，但當您在實際裝置或模擬器上執行應用程式時，畫面上不會顯示「1」。

請注意，由於只有應用程式開發人員看得到此文字，因此您不需要為其提供字串資源。

在預覽畫面中查看應用程式。目前顯示「1」。

執行您的應用程式。這是在模擬器上執行應用程式後的外觀。未顯示「1」。這是正確的做法。

太好了，這樣版面配置已完成變更！

您的應用程式中有按鈕，但即使您輕觸按鈕，系統也不會執行任何動作。如要變更這項設定，您必須編寫一些擲骰子的 Kotlin 程式碼，並在使用者輕觸按鈕時更新畫面。

如要進行這項變更，您需要進一步瞭解 Android 應用程式的結構。

4. 活動簡介

Activity 會提供應用程式繪製使用者介面的視窗。一般而言，Activity 會占滿執行中應用程式的整個畫面。每個應用程式都有一或多個活動。頂層或第一個活動通常稱為 MainActivity，由專案範本提供。舉例來說，當使用者捲動裝置上的應用程式清單，然後輕觸「Dice Roller」應用程式圖示時，Android 系統將啟動應用程式的 MainActivity。

您必須在 MainActivity 程式碼中提供 Activity 版面配置的詳細資料，以及使用者與其互動的方式。

Birthday Card 應用程式有一個 Activity 會顯示生日訊息和圖片的。
在 Dice Roller 應用程式中，有一個 Activity 會顯示您剛建立的 TextView 和 Button 版面配置。

如果是較複雜的應用程式，可能有多個畫面以及多個 Activity。每個 Activity 都有特定用途。

例如，在相片庫應用程式中，您可以使用 Activity 以格狀檢視模式顯示相片，而第二個 Activity 用於檢視個別相片，第三個 Activity 則用於編輯個別相片。

開啟 MainActivity.kt 檔案

您需要新增程式碼來回應 MainActivity 中的按鈕輕觸動作。為了正確執行這項作業，您必須進一步瞭解應用程式中現有的 MainActivity 程式碼。

找到並開啟 MainActivity.kt 檔案 (app > java > com.example.diceroller > MainActivity.kt)。以下是您應該會看到的內容。如果看到 import...，請按一下 ... 來展開匯入作業。

package com.example.diceroller

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
   }
}

您不需要瞭解上述程式碼中的每個字詞，但必須大致瞭解這些程式碼有何作用。越常使用 Android 程式碼，就越容易學會使用，也越容易瞭解。

查看 MainActivity 類別的 Kotlin 程式碼，並以關鍵字 class 和名稱來識別。

class MainActivity : AppCompatActivity() {
    ...
}

請注意，MainActivity 中沒有 main() 函式。

您之前已瞭解每個 Kotlin 程式都必須有 main() 函式。Android 應用程式的運作方式有所不同。在首次開啟應用程式時，Android 系統會呼叫 MainActivity 的 onCreate() 方法，而不會呼叫 main() 函式。

找出 onCreate() 方法，程式碼看起來如下所示。

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
   }

您稍後會在程式碼研究室中學習 override，因此暫時不必費心。除了使用匯入作業中的程式碼，onCreate() 方法的其餘部分還會利用 setContentView() 設定起始版面配置，進而設定 MainActivity。

請注意開頭為 import 的行。

Android 提供許多類別的「架構」，可讓您更輕鬆地撰寫 Android 應用程式，但必須確切瞭解您的類別。您可以使用 import 陳述式，指定您程式碼要使用架構中的哪個類別。舉例來說，android.widget.Button 中定義了 Button 類別。

啟用自動匯入作業

如果您同時使用更多類別，新增 import 陳述式會變得困難。幸好，使用他人提供的類別時，Android Studio 可協助您選擇正確的匯入作業。在這個步驟中，您會將 Android Studio 設為在可能的情況下自動匯入作業，並在程式碼中自動移除未使用的匯入作業。

在 macOS 中依序前往「File」(檔案) >「New Project Settings」(新專案設定) >「Preferences for New Project…」(新專案的偏好設定…) 開啟設定。依序展開「Other Settings」(其他設定) >「Auto Import」(自動匯入)。在「Java」和「Kotlin」區段中，確定已勾選「Add unambiguous imports on the fly」(快速新增不明確的匯入) 和「Optimize imports on the fly (for current project)」(快速最佳化匯入 (適用於目前的專案))。請注意，每個部分各有一個核取方塊。按下「OK」儲存變更，然後關閉設定。

在 Windows 中前往「File」(檔案) >「Settings」(設定) >「Editor」(編輯器) >「General」(一般) >「Auto Import」(自動匯入)，開啟設定。在「Java」和「Kotlin」區段中，確定已勾選「Add unambiguous imports on the fly」(快速新增不明確的匯入) 和「Optimize imports on the fly (for current project)」(快速最佳化匯入 (適用於目前的專案))。請注意，每個部分各有一個核取方塊。按下「OK」儲存變更，然後關閉設定。

「unambiguous imports」設定會指示 Android Studio 自動新增匯入陳述式，前提是必須可決定要使用哪個陳述式。「optimize imports」設定則會指示 Android Studio 移除程式碼未使用的所有匯入作業。

5. 製作互動式按鈕

現在您對於 MainActivity 瞭若指掌，您將修改應用程式後，使得按一下 Button 即可在螢幕上進行其他動作。

在點選按鈕時顯示訊息

在這個步驟中，您需要指定在按下按鈕時，畫面底部顯示簡短訊息。

setContentView() 呼叫後，將下列程式碼新增至 onCreate() 方法。findViewById() 方法會在版面配置中找到 Button。R.id.button 是 Button 的資源 ID，這是其專屬識別碼。

val rollButton: Button = findViewById(R.id.button)

程式碼會將對 Button 物件的參照儲存至名為 rollButton 的變數中，而非 Button 物件本身。

onCreate() 方法現在應會如下所示：

override fun onCreate(savedInstanceState: Bundle?) {
   super.onCreate(savedInstanceState)
   setContentView(R.layout.activity_main)

   val rollButton: Button = findViewById(R.id.button)
}

確認 Android Studio 已自動新增 Button 的 import 陳述式。請注意，目前有 3 個匯入陳述式。

import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity

接下來，您需要建立程式碼與 Button 的關聯，以便在輕觸 Button 時執行程式碼。「點擊事件監聽器」是在使用者輕觸或點選時採取動作的特定程式碼。在此情況中，您不妨把程式碼想成是僅僅坐著「監聽」使用者是否點選 Button。

使用 rollButton 物件並呼叫 setOnClickListener() 方法，在物件上設定點擊事件監聽器。在方法名稱後面使用大括號，而不要使用括號。這是一個宣告 Lambda 的特殊語法，詳情請見未來程式碼研究室的內容。

您現在需要知道的是，放入大括號中的指令會指示輕觸按鈕時應執行的操作。下一個步驟中，應用程式會顯示浮動式訊息，這是簡短訊息。

rollButton.setOnClickListener {
}

當您輸入文字時，Android Studio 可能會顯示多個建議。在這種情況下，請選擇「setOnClickListener {...}」選項。

您可在大括號中放入指令，指示在輕觸按鈕時應該執行的操作。目前您的應用程式會顯示 Toast，這是會顯示的簡短訊息給使用者。

呼叫 Toast.makeText() 即可建立內含文字 "Dice Rolled!" 的 Toast。

val toast = Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT)

然後呼叫 show() 方法，讓 Toast 自行顯示。

toast.show()

更新後的 MainActivity 類別如下所示；package 和 import 陳述式仍位於檔案頂端：

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)

       val rollButton: Button = findViewById(R.id.button)
       rollButton.setOnClickListener {
           val toast = Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT)
           toast.show()
       }
   }
}

您可以將點擊事件監聽器中的兩行合併成沒有變數的一行。這是其他程式碼中常見的模式。

Toast.makeText(this, "Dice Rolled!", Toast.LENGTH_SHORT).show()

執行應用程式，然後按一下「Roll」按鈕。浮動式訊息應會以彈出式視窗顯示在螢幕底部，而且不久後就會消失。

太棒了！點選按鈕後，畫面上會以彈出式視窗顯示訊息！這是您第一次編寫 Android 適用的 Kotlin 程式碼！

在點選按鈕時更新 TextView

如果不想顯示臨時 Toast 訊息，您必須撰寫程式碼，並在點選「Roll」按鈕時更新畫面上的 TextView。

返回 activity_main.xml (app > res > layout >activity_main.xml)
按一下 TextView。
請注意，id 為 textView。

開啟 MainActivity.kt (app > java > com.example.diceroller > MainActivity.kt)
刪除建立並顯示 Toast 的程式碼行。

rollButton.setOnClickListener {

}

在該位置建立一個名稱為 resultTextView 的新變數，以便儲存 TextView。
使用 findViewById() 在版面配置中使用 textView 找出這個 ID 並儲存其參照。

val resultTextView: TextView = findViewById(R.id.textView)

將 resultTextView 上的文字設定為在雙引號內的　6。

resultTextView.text = "6"

操作方式與您在「Attributes」中設定「text」屬性的方式相同，但現在您已納入程式碼，因此文字必須置於雙引號中。如果明確設定，TextView 目前會顯示 6。您需要加入程式碼來擲骰子，並在下一個工作中顯示不同的值。

MainActivity 類別應如下所示：

class MainActivity : AppCompatActivity() {

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)

       val rollButton: Button = findViewById(R.id.button)
       rollButton.setOnClickListener {
           val resultTextView: TextView = findViewById(R.id.textView)
           resultTextView.text = "6"
       }
   }
}

執行應用程式。按一下按鈕。應將 TextView 更新為 "6"。

6. 新增擲骰子邏輯

唯一遺漏的就是實際上擲骰子。您可以重複使用先前程式碼研究室的 Dice 類別，該類別會處理擲骰子的邏輯。

新增 Dice (骰子) 類別

在 MainActivity 類別中加上最後一個大括號後，透過 roll() 方法建立 Dice 類別。

class Dice(val numSides: Int) {

   fun roll(): Int {
       return (1..numSides).random()
   }
}

請注意，Android Studio 可能會用灰色波浪號加底線於 numSides。(可能需要一些時間才會顯示。)
將游標懸停在 numSides 上，畫面上就會顯示「Property ‘numSides' could be private」彈出式視窗。

將 numSides 標示為 private 後，您只能在 Dice 類別中存取。由於只有使用 numSides 的程式碼才會位於 Dice 類別內，因此可為 Dice 類別指定這個引數 private。下一單元中您將瞭解 private 和 public 變數。

按一下「Make ‘numSides' ‘private'」，繼續透過 Android Studio 實作建議的修正項目。

建立 rollDice() 方法

現在您已經新增 Dice 類別至應用程式，必須更新 MainActivity 才能使用該類別。如要妥善整理程式碼，請將所有擲骰子邏輯放入一個函式中。

將點擊事件監聽器中將文字設定為 "6" 的程式碼替換為呼叫 rollDice()。

rollButton.setOnClickListener {
   rollDice()
}

因為尚未定義 rollDice()，Android Studio 會標記誤並以紅色顯示 rollDice()。
滑鼠游標懸停在 rollDice() 上時，Android Studio 會顯示問題和可能的解決方法。

按一下「More actions…」開啟選單。Android Studio 提供更完善的使用體驗！

選取「Create function ‘rollDice'」。Android Studio 會為 MainActivity 中的函式建立空白定義。

private fun rollDice() {
    TODO("Not yet implemented")
}

建立新的 Dice 物件例項

在這個步驟中，您必須建立 rollDice() 方法並擲骰子，然後在 TextView 中顯示結果。

在 rollDice() 中刪除 TODO() 呼叫。
加入程式碼即可建立具有 6 個面的骰子。

val dice = Dice(6)

呼叫 roll() 方法即可擲骰子，並將結果儲存在名為 diceRoll 的變數中。

val diceRoll = dice.roll()

呼叫 findViewById() 即可找到 TextView。

val resultTextView: TextView = findViewById(R.id.textView)

變數 diceRoll 是數字，但 TextView 使用文字。您可以在 diceRoll 上使用 toString() 方法，將數字轉換為字串。

將 diceRoll 轉換成字串，並使用該字串更新 resultTextView 的文字。

resultTextView.text = diceRoll.toString()

rollDice() 方法的樣式看起來像：

private fun rollDice() {
    val dice = Dice(6)
    val diceRoll = dice.roll()
    val resultTextView: TextView = findViewById(R.id.textView)
    resultTextView.text = diceRoll.toString()
}

執行您的應用程式。擲骰子結果應變更為 6 以外的其他值！由於這是 1 到 6 之間的隨機數字，因可能偶爾也會顯示此值 6。

太棒了！

7. 採用完善的程式設計做法

您在這裡微調部分程式碼並讓應用程式正常運作後，程式碼通常看起來會有些微雜亂。但是在退出程式碼前，請先完成一些簡單的清除工作。應用程式會保持在良好狀態，日後也更容易維護。

這些習慣是專業 Android 開發人員編寫程式碼時的實務做法。

Android 樣式指南

團隊合作時，理想的做法是以類似的方式撰寫程式碼，讓程式碼之間保持一致。因此，Android 提供樣式指南來說明如何編寫 Android 程式碼，包括命名慣例、格式和其他遵循的建議做法。撰寫 Android 程式碼時遵循這些指南：Android 開發人員適用的 Kotlin 樣式指南。

您可以透過下列幾種方式遵守樣式指南。

清理您的程式碼

縮減程式碼

您可以將程式碼縮減成較短行的程式碼，讓程式碼更精簡。以下範例是設定 Button 點擊事件監聽器的程式碼。

rollButton.setOnClickListener {
    rollDice()
}

由於點擊事件監聽器的操作說明只有 1 行，因此您可以縮減 rollDice() 方法呼叫，將此呼叫和大括號全部置於一行。看起來會像下面這樣，請注意是單行而非三行！

rollButton.setOnClickListener { rollDice() }

重新設定程式碼格式

現在，您必須重新設定程式碼格式，確保程式碼符合 Android 建議的程式碼格式規範。

在 MainActivity.kt 類別中，用 Windows 的鍵盤快速鍵 Control+A (Mac 則是 Command+A) 就可選取檔案中的所有文字。或者您可以在 Android Studio 的選單中依序點選「Edit」>「Select All」。
選取檔案中的所有文字後，在 Android Studio 的選單中依序點選「Code」>「Reformat Code」，或使用鍵盤快速鍵 Ctrl+Alt+L (Mac 則是 Command+Option+L)。

這會更新程式碼的格式，包括空白字元、縮排等等。您可能還看不到任何變化，這很好。您的程式碼已正確格式化！

為程式碼加上註解

在您的程式碼中新增一些註解，說明您編寫的程式碼的作用。隨著程式碼變得越來越複雜，您也必須註明「為何」要編寫程式碼來按照特定方式運作。如果之後返回變更程式碼，程式碼的「功用」或許還是清楚明瞭，但您可能不記得當初為何如此編寫程式碼。

通常，為每個類別 (MainActivity 和 Dice 是您的應用程式中僅有的類別) 和您撰寫的每個方法新增註解。請在註解的開頭和結尾使用 /** 和 */ 符號，告訴系統這不是程式碼。系統在執行程式碼時會忽略這些行。

類別註解範例：

/**
* This activity allows the user to roll a dice and view the result
* on the screen.
*/
class MainActivity : AppCompatActivity() {

方法的註解範例：

/**
* Roll the dice and update the screen with the result.
*/
private fun rollDice() {

您可以在方法中隨意新增註解，協助讀者瞭解程式碼。提醒您，您可以在註解開頭加上 // 符號。行中 // 符號後面的所有內容都會視為註解。

方法中有 2 個註解範例：

private fun rollDice() {
   // Create new Dice object with 6 sides and roll it
   val dice = Dice(6)
   val diceRoll = dice.roll()

   // Update the screen with the dice roll
   val resultTextView: TextView = findViewById(R.id.textView)
   resultTextView.text = diceRoll.toString()
}