新增可捲動的清單

1. 事前準備

在這個程式碼研究室中,您將瞭解如何使用 Jetpack Compose 在應用程式中建立可捲動的清單。

您將使用 Affirmations 應用程式,此應用程式可顯示與美麗圖片配對的肯定字詞清單,為您的一天帶來積極動力!

我們已有資料,您只需擷取相關資料並在使用者介面中顯示即可。

必要條件

  • 瞭解 Kotlin 中的清單
  • 瞭解如何使用 Jetpack Compose 建構版面配置
  • 瞭解如何使用裝置或模擬器執行應用程式

課程內容

  • 如何使用 Jetpack Compose 建立質感設計資訊卡
  • 如何使用 Jetpack Compose 建立可捲動的清單

建構項目

  • 您將使用現有的應用程式,在使用者介面中加入可捲動的清單

完成的作品看起來會像這樣:

f6f09800b74f4700.png

軟硬體需求

  • 可連接網際網路且有網頁瀏覽器的電腦、Android Studio
  • GitHub 存取權

下載範例程式碼

在 Android Studio 中開啟 basic-android-kotlin-compose-training-affirmations 資料夾。

  1. 前往為專案提供的 GitHub 存放區頁面。
  2. 驗證分支版本名稱與程式碼研究室中指定的分支版本名稱相符。例如,在下方螢幕截圖中,分支版本名稱為「main」。

1e4c0d2c081a8fd2.png

  1. 在專案的 GitHub 頁面中,按一下「Code」(程式碼) 按鈕,畫面上會出現彈出式視窗。

1debcf330fd04c7b.png

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

在 Android Studio 中開啟專案

  1. 啟動 Android Studio。
  2. 在「Welcome to Android Studio」(歡迎使用 Android Studio) 視窗中,按一下「Open」(開啟)

d8e9dbdeafe9038a.png

注意:如果已開啟 Android Studio,請依序選取「File」(檔案) >「Open」(開啟) 選單選項。

8d1fda7396afe8e5.png

  1. 在檔案瀏覽器中,前往已解壓縮的專案資料夾所在的位置 (可能位於「Downloads」(下載) 資料夾中)。
  2. 按兩下該專案資料夾。
  3. 等待 Android Studio 開啟專案。
  4. 按一下「Run」(執行) 按鈕 8de56cba7583251f.png 即可建構並執行應用程式,請確認應用程式的建構符合預期。

2. 觀看程式設計示範影片 (可略過)

如果您想觀看課程老師示範完成此程式碼研究室,請觀看以下影片。

建議您在全螢幕模式下觀看影片 (點選影片右下角的 該符號以醒目顯示的矩形方框標出 4 個角落,表示其處於全螢幕模式。 圖示),以便清楚看見 Android Studio 和程式碼。

您可以跳過這個步驟,也可以不觀看這段影片,立即開始執行程式碼研究室的操作步驟。

3. 建立清單項目資料類別

建立 Affirmation 資料類別

在 Android 應用程式中,清單是由清單項目組成。如果是單一資料,這可以是簡單的字串或整數。如果是有多個資料的清單項目 (例如圖片和文字),您就需要一個包含所有屬性的類別。資料類別是一種只包含屬性的類別類型,可以提供一些適用於這些屬性的公用程式方法。

  1. com.example.affirationss 下建立新套件。4a51cb670bbec405.png

將新的套件命名為「Model」(模型)。模型套件將包含資料類別所代表的資料模型。該資料類別將由代表「Affirmation」(自我肯定) 的資料 (由字串資源和圖片資源組成) 相關資訊的屬性組成。套件是包含類別,甚至是其他目錄的目錄。

9ea1f8880ca90ea0.png

  1. com.example.affirmations.model 套件中建立新類別。a9515a8b47715a22.png

將新類別命名為「Affirmation」(自我肯定),然後將其設為「Data Class」(資料類別)

b36be7f428fd1672.png

  1. 每個 Affirmation 都含有一張圖片和一個字串。在 Affirmation 資料類別中建立兩個 val 屬性。其中一個應該稱為 stringResourceId,而另一個則是 imageResourceId。兩個都必須是整數。

Affirmation.kt

data class Affirmation(
   val stringResourceId: Int,
   val imageResourceId: Int
)
  1. 使用 @StringRes 註解標記 stringResourceId 屬性,並使用 @DrawableRes 標記 imageResourceIdstringResourceId 代表儲存在字串資源中肯定文字的 ID。imageResourceId 代表可繪製資源中儲存的肯定圖片 ID。

Affirmation.kt

data class Affirmation(
   @StringRes val stringResourceId: Int,
   @DrawableRes val imageResourceId: Int
)
  1. 現在,開啟 com.example.affirmations.data 套件中的 Datasource.kt 檔案,然後取消註解 Datasource 類別的內容。

Datasource.kt

class Datasource() {
   fun loadAffirmations(): List<Affirmation> {
       return listOf<Affirmation>(
           Affirmation(R.string.affirmation1, R.drawable.image1),
           Affirmation(R.string.affirmation2, R.drawable.image2),
           Affirmation(R.string.affirmation3, R.drawable.image3),
           Affirmation(R.string.affirmation4, R.drawable.image4),
           Affirmation(R.string.affirmation5, R.drawable.image5),
           Affirmation(R.string.affirmation6, R.drawable.image6),
           Affirmation(R.string.affirmation7, R.drawable.image7),
           Affirmation(R.string.affirmation8, R.drawable.image8),
           Affirmation(R.string.affirmation9, R.drawable.image9),
           Affirmation(R.string.affirmation10, R.drawable.image10))
   }
}

4. 在應用程式中加入清單

建立清單項目資訊卡

此應用程式的用途是顯示肯定字詞清單。設定使用者介面以顯示清單的第一步,就是建立清單項目。每個肯定字詞項目都包含一個圖片和字串。這些項目的資料都含有範例程式碼,您將建立 UI 元件以顯示此類項目。

項目將包含一個 Card 可組合項,其中包含 ImageText 可組合項。在 Compose 中,Card 是在單一容器中顯示內容和操作的介面。Affirmation 資訊卡外觀如下:

95111184aed54fa3.png

資訊卡顯示的圖片下方有一段文字。使用 Card 可組合項中納入的 Column 可組合項,就可達成此類別版面配置。您可以自行嘗試,或是按照以下步驟進行。

  1. 開啟 MainActivity.kt 檔案。

1e348baaf91552f4.png

  1. AffirmationApp() 方法之下建立名為 AffirmationCard() 的新方法,然後使用 @Composable 註解加上註解。

MainActivity.kt

@Composable
fun AffirmationApp() {
   val context = LocalContext.current
   AffirmationsTheme {

   }
}

@Composable
fun AffirmationCard() {

}
  1. 編輯方法簽名,以使用 Affirmation 物件做為參數。Affirmation 物件來自 model 套件。

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation) {

}
  1. 在簽名中加入 modifier 參數。設定參數 Modifier 預設值。

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {

}
  1. AffirmationCard 方法內,呼叫 Card 可組合項。傳入下列參數:modifierelevation。傳遞 Modifier 物件,並針對 modifier 參數將 padding 屬性設為 8.dp。針對 elevation 傳遞 4.dp 的值。稍後我們將詳細說明 elevation 屬性。

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {Card(modifier = modifier.padding(8.dp), elevation = 4.dp) {
  }
}
  1. Card 可組合項中加入一個 Column 可組合項。Column 可組合項內的項目會在使用者介面中垂直排列。這可讓您在相關文字上方加入圖片。相反地,Row 可組合項會以水平方式排列所含項目。

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
  Card(modifier = modifier.padding(8.dp), elevation = 4.dp) {
    Column {
    }
  }
}
  1. Column 可組合項的 lambda 內文中加入 Image 可組合項。提醒您,Image 可組合項一律需要資源才能顯示,還有 contentDescription。資源應為傳遞至 painter 參數的 painterResourcepainterResource 方法會載入向量可繪項目或光柵化素材資源格式 (例如 PNG)。也會傳遞 contentDescription 參數的 stringResource

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
  Card(modifier = Modifier.padding(8.dp), elevation = 4.dp) {
    Column {
      Image(
        painter = painterResource(affirmation.imageResourceId),
        contentDescription = stringResource(affirmation.stringResourceId)
      )
    }
  }
}
  1. 除了 paintercontentDescription 參數外,還會傳遞 modifiercontentScalecontentScale 可決定圖片的縮放和顯示方式。Modifier 物件應有 fillMaxWidth 屬性組合,且高度為 194.dpcontentScale 應為 ContentScale.Crop

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
  Card(modifier = Modifier.padding(8.dp), elevation = 4.dp) {
    Column {
      Image(
        painter = painterResource(affirmation.imageResourceId),
        contentDescription = stringResource(affirmation.stringResourceId),
        modifier = Modifier
          .fillMaxWidth()
          .height(194.dp),
        contentScale = ContentScale.Crop
      )
    }
  }
}
  1. Column 內,於 Image 可組合項之後建立 Text 可組合項。將 affirmation.stringResourceIdstringResource 傳遞至 text 參數、傳遞有 padding 屬性組合的 Modifier 物件至 16.dp,並以傳遞 MaterialTheme.typography.h6style 參數設定文字主題。

MainActivity.kt

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
  Card(modifier = Modifier.padding(8.dp), elevation = 4.dp) {
    Column {
      Image(
        painter = painterResource(affirmation.imageResourceId),
        contentDescription = stringResource(affirmation.stringResourceId),
        modifier = Modifier
          .fillMaxWidth()
          .height(194.dp),
        contentScale = ContentScale.Crop
      )
      Text(
        text = stringResource(affirmation.stringResourceId),
        modifier = Modifier.padding(16.dp),
        style = MaterialTheme.typography.h6
      )
    }
  }
}

預覽 AffirmationCard 可組合項

資訊卡是 Affirations 應用程式的 UI 核心,也是您努力建立的成果!如要檢查資訊卡是否正確無誤,您可以建立可預覽的可組合項,不必啟動整個應用程式。

  1. 建立名為 AffirmationCardPreview() 的不公開方法。使用 @Preview@Composable 為方法加上註解。

MainActivity.kt

@Preview
@Composable
private fun AffirmationCardPreview() {
}
  1. 在方法內部,呼叫 AffirmationCard 可組合項,然後使用 R.string.affirmation1 字串資源及傳入建構函式的 R.drawable.image1 可繪製資源傳遞新的 Affirmation 物件。

MainActivity.kt

@Preview
@Composable
private fun AffirmationCardPreview() {
  AffirmationCard(Affirmation(R.string.affirmation1, R.drawable.image1))
}
  1. 開啟「Split」(分割) 分頁,就可查看 AffirmationCard 的預覽。如有必要,請按一下「Design」(設計) 窗格中的「Create & Refresh」(建構與重新整理) 以顯示預覽。84904da4a33413ce.png

建立清單

清單項目元件是清單的建構區塊。建立清單項目後,就可以利用清單項目製作清單元件。

  1. 建立名稱為 AffirmationList() 的方法,使用 @Composable 註解加上註解,然後在方法簽名中宣告 Affirmation 物件的 List 為參數。

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>) {
}
  1. 在方法簽名中宣告 modifier 物件為參數,預設值為 Modifier

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
}
  1. 在 Jetpack Compose 中,您可以使用 LazyColumn 可組合項建立可捲動的清單。LazyColumnColumn 的差異,在於要顯示少量項目時應使用 Column,因為 Compose 可以一次載入所有項目。Column 只能保留預先定義或固定的可組合項。LazyColumn 可以依照需求加入內容,這對於長清單而言特別實用,尤其是在清單長度不明的情況下更是如此。根據預設,LazyColumn 也會提供捲動功能,不需使用其他程式碼。在 AffirmationList() 方法內宣告 LazyColumn 可組合項。

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
  LazyColumn {
  }
}
  1. LazyColumn 的 lambda 內文中,呼叫 items() 方法並傳入 affirmationListitems() 方法可讓您在 LazyColumn 中加入項目。這種方法對於此可組合項而言比較特別,因此並不是大多數可組合項的常見做法。

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
  LazyColumn {
    items(affirmationList){
    }
  }
}
  1. 呼叫 items() 方法需要 lambda 函式。在該函式中,指定 affirmation 的參數,代表來自 affirmationList 的其中一個肯定字詞項目。

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
  LazyColumn {
    items(affirmationList){ affirmation ->
    }
  }
}
  1. 對於清單中的每個肯定字詞,呼叫 AffirmationCard() 可組合項,然後傳遞 affirmation

MainActivity.kt

@Composable
private fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
  LazyColumn {
    items(affirmationList){ affirmation ->
      AffirmationCard(affirmation)
    }
  }
}

顯示清單

  1. 在 lambda 中,呼叫 AffirmationList 可組合項,然後傳遞 DataSource().loadAffirmations()affirmationList 參數。

MainActivity.kt

@Composable
fun AffirmationApp() {
   AffirmationsTheme {
       Scaffold(
           content = {
               AffirmationList(affirmationList = Datasource().loadAffirmations())
           }
       )
   }
}

在裝置或模擬器上執行 Affirationss 應用程式,即可查看完成的作品!

f6f09800b74f4700.png

5. 取得解決方案程式碼

如要查看解決方案程式碼,請前往 GitHub 檢視。

  1. 前往為專案提供的 GitHub 存放區頁面。
  2. 驗證分支版本名稱與程式碼研究室中指定的分支版本名稱相符。例如,在下方螢幕截圖中,分支版本名稱為「main」。

1e4c0d2c081a8fd2.png

  1. 在專案的 GitHub 頁面中,按一下「Code」(程式碼) 按鈕,畫面上會出現彈出式視窗。

1debcf330fd04c7b.png

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

在 Android Studio 中開啟專案

  1. 啟動 Android Studio。
  2. 在「Welcome to Android Studio」(歡迎使用 Android Studio) 視窗中,按一下「Open」(開啟)

d8e9dbdeafe9038a.png

注意:如果已開啟 Android Studio,請依序選取「File」(檔案) >「Open」(開啟) 選單選項。

8d1fda7396afe8e5.png

  1. 在檔案瀏覽器中,前往已解壓縮的專案資料夾所在的位置 (可能位於「Downloads」(下載) 資料夾中)。
  2. 按兩下該專案資料夾。
  3. 等待 Android Studio 開啟專案。
  4. 按一下「Run」(執行) 按鈕 8de56cba7583251f.png 即可建構並執行應用程式,請確認應用程式的建構符合預期。

6. 結語

現在您已經知道如何使用 Jetpack Compose 建立資訊卡、清單項目和可捲動的清單!請注意,以上只是建立清單的基本工具,您可以盡情揮灑創意,自由自訂各種清單項目!

摘要

  • 使用 Card 可組合項建立清單項目。
  • 修改 Card 可組合項內包含的 UI。
  • 使用 LazyColumn 可組合項建立可捲動的清單。
  • 使用自訂清單項目建構清單。