添加一个可滚动的列表

1. 准备工作

在此 Codelab 中，您将学习如何使用 Jetpack Compose 在应用中创建可滚动的列表。

您将使用 Affirmations 应用，该应用显示肯定句列表以及精美图片，为您的日常注入积极能量！

数据已经存在，您只需获取这些数据并在界面中显示即可。

前提条件

  • 熟悉 Kotlin 中的列表
  • 有使用 Jetpack Compose 构建布局的经验
  • 有在设备或模拟器上运行应用的经验

学习内容

  • 如何使用 Jetpack Compose 创建 Material Design 卡片
  • 如何使用 Jetpack Compose 创建可滚动的列表

构建内容

  • 您将使用现有应用并在界面中添加可滚动的列表

完成后的产品将如下所示

286f5132aa155fa6.png

所需物品

  • 一台联网的计算机、一个网页浏览器和 Android Studio
  • 访问 GitHub 的权限

下载入门代码

在 Android Studio 中，打开 basic-android-kotlin-compose-training-affirmations 文件夹。

当使用 starter 分支的代码构建时，应用应显示空白屏幕。

3beea0789e2eeaba.png

2. 创建列表项数据类

为 Affirmation 创建数据类

在 Android 应用中，列表由列表项组成。对于单个数据片段，这可以是一个简单的字符串或整数。对于包含多个数据片段（例如图片和文本）的列表项，您需要一个包含所有这些属性的类。数据类是一种只包含属性的类，它们可以提供一些实用方法来处理这些属性。

  1. 在 com.example.affirmations 下创建一个新包。

89c8d8485c685fac.png

将新包命名为 model. model 包将包含由数据类表示的数据模型。该数据类将由表示与“Affirmation”相关的信息的属性组成，其中包括字符串资源和图片资源。包是包含类甚至其他目录的目录。

b54fb6bf57de44c8.png

  1. 在 com.example.affirmations.model 包中创建一个新类。

58510a651bd49100.png

将新类命名为 Affirmation 并使其成为 Data class。

7f94b65ee3d8407f.png

  1. 每个 Affirmation 都包含一张图片和一个字符串。在 Affirmation 数据类中创建两个 val 属性。一个应命名为 stringResourceId，另一个命名为 imageResourceId。它们都应该是整数。

Affirmation.kt

data class Affirmation(
    val stringResourceId: Int,
    val imageResourceId: Int
)
  1. 使用 @StringRes 注解标注 stringResourceId 属性，并使用 @DrawableRes 注解标注 imageResourceId。 stringResourceId 表示存储在字符串资源中的肯定句文本的 ID。imageResourceId 表示存储在 drawable 资源中的肯定句图片的 ID。

Affirmation.kt

import androidx.annotation.DrawableRes
import androidx.annotation.StringRes

data class Affirmation(
    @StringRes val stringResourceId: Int,
    @DrawableRes val imageResourceId: Int
)
  1. 在 com.example.affirmations.data 包中，打开 Datasource.kt 文件并取消注释两个 import 语句和 Datasource 类的 contents。

Datasource.kt

import com.example.affirmations.R
import com.example.affirmations.model.Affirmation

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

3. 向应用添加列表

创建列表项卡片

此应用旨在显示肯定句列表。配置界面以显示列表的第一步是创建列表项。每个肯定句项都包含一张图片和一个字符串。每个项的数据都随入门代码提供，您将创建用于显示此类项的界面组件。

该项将由一个 Card 可组合项组成，其中包含一个 Image 和一个 Text 可组合项。在 Compose 中，Card 是一种在单个容器中显示内容和操作的界面。Affirmation 卡片在预览中的样子如下

4f657540712a069f.png

卡片下方显示一张图片和一些文本。可以使用包裹在 Card 可组合项中的 Column 可组合项实现此垂直布局。您可以自己尝试，或按照以下步骤实现。

  1. 打开 MainActivity.kt 文件。
  2. 在 AffirmationsApp() 方法下方创建一个新方法，命名为 AffirmationCard()，并使用 @Composable 注解标注它。

MainActivity.kt

@Composable
fun AffirmationsApp() {
}

@Composable
fun AffirmationCard() {

}
  1. 编辑方法签名以将 Affirmation 对象作为参数。 Affirmation 对象来自 model 包。

MainActivity.kt

import com.example.affirmations.model.Affirmation

@Composable
fun AffirmationCard(affirmation: Affirmation) {

}
  1. 在签名中添加一个 modifier 参数。为该参数设置默认值 Modifier。

MainActivity.kt

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

}
  1. 在 AffirmationCard 方法内部，调用 Card 可组合项。传入 modifier 参数。

MainActivity.kt

import androidx.compose.material3.Card

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

    }
}
  1. 在 Card 可组合项内部添加一个 Column 可组合项。 Column 可组合项中的项在界面中垂直排列。这允许您将图片放在相关文本的上方。相反，Row 可组合项将其包含的项水平排列。

MainActivity.kt

import androidx.compose.foundation.layout.Column

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

        }
    }

}
  1. 在 Column 可组合项的 lambda 体内部添加一个 Image 可组合项。请记住，Image 可组合项始终需要一个要显示的资源和一个 contentDescription。资源应该是传递给 painter 参数的 painterResource。painterResource 方法将加载矢量 drawable 或 PNG 等光栅化资产格式。此外，为 contentDescription 参数传递一个 stringResource。

MainActivity.kt

import androidx.compose.foundation.Image
import androidx.compose.ui.res.painterResource
import androidx.compose.ui.res.stringResource

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
    Card(modifier = modifier) {
        Column {
            Image(
                painter = painterResource(affirmation.imageResourceId),
                contentDescription = stringResource(affirmation.stringResourceId),
            )
        }
    }
}
  1. 除了 painter 和 contentDescription 参数外，还要传递一个 modifier 和一个 contentScale。contentScale 决定了图片应该如何缩放和显示。Modifier 对象应设置 fillMaxWidth 属性，高度为 194.dp。contentScale 应为 ContentScale.Crop。

MainActivity.kt

import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.ui.unit.dp
import androidx.compose.ui.layout.ContentScale

@Composable
fun AffirmationCard(affirmation: Affirmation, modifier: Modifier = Modifier) {
    Card(modifier = modifier) {
        Column {
            Image(
                painter = painterResource(affirmation.imageResourceId),
                contentDescription = stringResource(affirmation.stringResourceId),
                modifier = Modifier
                    .fillMaxWidth()
                    .height(194.dp),
                contentScale = ContentScale.Crop
            )
        }
    }
}
  1. 在 Column 内部，在 Image 可组合项之后创建一个 Text 可组合项。将 affirmation.stringResourceId 的 stringResource 传递给 text 参数，传递一个设置了 padding 属性为 16.dp 的 Modifier 对象，并通过将 MaterialTheme.typography.headlineSmall 传递给 style 参数来设置文本主题。

MainActivity.kt

import androidx.compose.material3.Text
import androidx.compose.foundation.layout.padding
import androidx.compose.ui.platform.LocalContext

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

预览 AffirmationCard 可组合项

卡片是 Affirmations 应用界面的核心，您付出了很多努力来创建它！要检查卡片是否正确显示，您可以创建一个无需启动整个应用即可预览的可组合项。

  1. 创建一个名为 AffirmationCardPreview() 的私有方法。使用 @Preview 和 @Composable 注解标注该方法。

MainActivity.kt

import androidx.compose.ui.tooling.preview.Preview

@Preview
@Composable
private fun AffirmationCardPreview() {

}
  1. 在方法内部，调用 AffirmationCard 可组合项，并向其传递一个新的 Affirmation 对象，该对象的构造函数中传入了 R.string.affirmation1 字符串资源和 R.drawable.image1 drawable 资源。

MainActivity.kt

@Preview
@Composable
private fun AffirmationCardPreview() {
    AffirmationCard(Affirmation(R.string.affirmation1, R.drawable.image1))
}
  1. 打开 Split 选项卡，您将看到 AffirmationCard 的预览。如有必要，在 Design 窗格中点击 Build & Refresh 以显示预览。

924a4df2c1db236c.png

创建列表

列表项组件是列表的构建块。创建列表项后，您可以利用它来创建列表组件本身。

  1. 创建一个名为 AffirmationList() 的函数，使用 @Composable 注解标注它，并在方法签名中声明一个 Affirmation 对象 List 作为参数。

MainActivity.kt

@Composable
fun AffirmationList(affirmationList: List<Affirmation>) {
    
}
  1. 在方法签名中声明一个 modifier 对象作为参数，其默认值为 Modifier。

MainActivity.kt

@Composable
fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {

}
  1. 在 Jetpack Compose 中，可以使用 LazyColumn 可组合项创建可滚动的列表。LazyColumn 和 Column 的区别在于，当您要显示的项数量较少时应使用 Column，因为 Compose 会一次性加载所有项。Column 只能容纳预定义或固定数量的可组合项。LazyColumn 可以按需添加内容，这使其适用于长列表，尤其是在列表长度未知时。LazyColumn 还默认提供滚动功能，无需额外代码。在 AffirmationList() 函数内部声明一个 LazyColumn 可组合项。将 modifier 对象作为参数传递给 LazyColumn。

MainActivity.kt

import androidx.compose.foundation.lazy.LazyColumn

@Composable
fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
    LazyColumn(modifier = modifier) {

    }
}
  1. 在 LazyColumn 的 lambda 体中，调用 items() 方法，并传入 affirmationList。items() 方法是向 LazyColumn 添加项的方式。此方法对此可组合项来说有点独特，对于大多数可组合项而言并非通用做法。

MainActivity.kt

import androidx.compose.foundation.lazy.items

@Composable
fun AffirmationList(affirmationList: List<Affirmation>, modifier: Modifier = Modifier) {
    LazyColumn(modifier = modifier) {
        items(affirmationList) {

        }
    }
}
  1. 调用 items() 方法需要一个 lambda 函数。在该函数中，指定一个参数 affirmation，它代表 affirmationList 中的一个肯定句项。

MainActivity.kt

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

        }
    }
}
  1. 对于列表中的每个肯定句，调用 AffirmationCard() 可组合项。向其传递 affirmation 和一个设置了 padding 属性为 8.dp 的 Modifier 对象。

MainActivity.kt

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

显示列表

  1. 在 AffirmationsApp 可组合项中，检索当前的布局方向并将其保存在一个变量中。稍后将使用它们配置内边距。

MainActivity.kt

import com.example.affirmations.data.Datasource

@Composable
fun AffirmationsApp() {
    val layoutDirection = LocalLayoutDirection.current
}
  1. 现在创建一个 Surface 可组合项。此可组合项将为 AffirmationsList 可组合项设置内边距。

MainActivity.kt

import com.example.affirmations.data.Datasource

@Composable
fun AffirmationsApp() {
    val layoutDirection = LocalLayoutDirection.current
    Surface() {
    }
}
  1. 将一个 Modifier 传递给 Surface 可组合项，使其填充其父项的最大宽度和高度，设置状态栏内边距，并将开始和结束内边距设置为 layoutDirection。以下是将 LayoutDirection 对象转换为内边距的示例：WindowInsets.safeDrawing.asPaddingValues().calculateStartPadding(layoutDirection)。

MainActivity.kt

import com.example.affirmations.data.Datasource

@Composable
fun AffirmationsApp() {
    val layoutDirection = LocalLayoutDirection.current
    Surface(
        Modifier = Modifier
        .fillMaxSize()
        .statusBarsPadding()
        .padding(
            start = WindowInsets.safeDrawing.asPaddingValues()
                    .calculateStartPadding(layoutDirection),
            end = WindowInsets.safeDrawing.asPaddingValues()
                    .calculateEndPadding(layoutDirection),
        ),
    ) {
    }
}
  1. 在 Surface 可组合项的 lambda 中，调用 AffirmationList 可组合项，并将 DataSource().loadAffirmations() 传递给 affirmationList 参数。

MainActivity.kt

import com.example.affirmations.data.Datasource

@Composable
fun AffirmationsApp() {
    val layoutDirection = LocalLayoutDirection.current
    Surface(
        Modifier = Modifier
        .fillMaxSize()
        .statusBarsPadding()
        .padding(
            start = WindowInsets.safeDrawing.asPaddingValues()
                    .calculateStartPadding(layoutDirection),
            end = WindowInsets.safeDrawing.asPaddingValues()
                    .calculateEndPadding(layoutDirection),
        ),
    ) {
        AffirmationsList(
            affirmationList = Datasource().loadAffirmations(),
        )
    }
}

在设备或模拟器上运行 Affirmations 应用，查看成品！

286f5132aa155fa6.png

4. 获取解决方案代码

要下载完成的 Codelab 代码，可以使用以下 git 命令

$ git clone https://github.com/google-developer-training/basic-android-kotlin-compose-training-affirmations.git
$ cd basic-android-kotlin-compose-training-affirmations
$ git checkout intermediate

或者，您可以将仓库下载为 ZIP 文件，解压后在 Android Studio 中打开。

如果您想查看解决方案代码，请在 GitHub 上查看。

5. 总结

现在您已了解如何使用 Jetpack Compose 创建卡片、列表项和可滚动列表！请记住，这些只是创建列表的基本工具。您可以发挥创意，随意自定义列表项！

总结

  • 使用 Card 可组合项创建列表项。
  • 修改 Card 可组合项中包含的界面。
  • 使用 LazyColumn 可组合项创建可滚动的列表。
  • 使用自定义列表项构建列表。