Cómo agregar una lista desplazable

1. Antes de comenzar

En este codelab, aprenderás a crear una lista desplazable en tu app con Jetpack Compose.

Trabajarás con la app de Affirmations, que muestra una lista de afirmaciones vinculadas con imágenes hermosas para aportar optimismo a tu día.

Los datos ya están allí, lo único que debes hacer es tomarlos y mostrarlos en la IU.

Requisitos previos

Conocimientos de listas de Kotlin
Experiencia en el diseño de diseños con Jetpack Compose
Experiencia en la ejecución de apps en un dispositivo o emulador

Qué aprenderás

Cómo crear una tarjeta de Material Design con Jetpack Compose
Cómo crear una lista desplazable con Jetpack Compose

Qué compilarás

Tomarás una aplicación existente y agregarás una lista desplazable a la IU.

El producto terminado se verá de la siguiente manera:

Requisitos

Una computadora con acceso a Internet, un navegador web y Android Studio
Acceso a GitHub

Descarga el código de partida

En Android Studio, abre la carpeta basic-android-kotlin-compose-training-affirmations.

Navega a la página de repositorio de GitHub del proyecto.
Verifica que el nombre de la rama coincida con el especificado en el codelab. Por ejemplo, en la siguiente captura de pantalla, el nombre de la rama es main.

En la página de GitHub de este proyecto, haz clic en el botón Code, que abre una ventana emergente.

En la ventana emergente, haz clic en el botón Download ZIP para guardar el proyecto en tu computadora. Espera a que se complete la descarga.
Ubica el archivo en tu computadora (probablemente en la carpeta Descargas).
Haz doble clic en el archivo ZIP para descomprimirlo. Se creará una carpeta nueva con los archivos del proyecto.

Abre el proyecto en Android Studio

Inicia Android Studio.
En la ventana Welcome to Android Studio, haz clic en Open.

Nota: Si Android Studio ya está abierto, selecciona la opción de menú File > Open.

En el navegador de archivos, ve hasta donde se encuentra la carpeta del proyecto descomprimida (probablemente en Descargas).
Haz doble clic en la carpeta del proyecto.
Espera a que Android Studio abra el proyecto.
Haz clic en el botón Run para compilar y ejecutar la app. Asegúrate de que funcione como se espera.

Se espera que la app muestre una pantalla en blanco cuando se compile a partir del código de rama starter.

2. Crea una clase de datos de elemento de lista

Cómo crear una clase de datos para una Affirmation

En las apps para Android, las listas se componen de elementos de lista. Para datos individuales, esto podría ser algo simple, como una cadena o un número entero. Para los elementos de lista que tienen varios datos, como una imagen y texto, necesitarás una clase que contenga todas estas propiedades. Las clases de datos son un tipo de clase que solo contiene propiedades y pueden proporcionar algunos métodos de utilidad para trabajar con esas propiedades.

Crea un paquete nuevo en com.example.affirmations.

Asígnale el nombre model. El paquete de modelos contendrá el modelo de datos que representará una clase de datos. Esa clase de datos se compone de propiedades que representan la información relevante a lo que será una "afirmación", que constará de un recurso de cadenas y un recurso de imagen. Los paquetes son directorios que contienen clases e incluso otros directorios.

Crea una clase nueva en el paquete com.example.affirmations.model.

Asígnale el nombre Affirmation a la nueva clase y conviértela en Data Class.

Cada Affirmation consiste en una imagen y una cadena. Crea dos propiedades val en la clase de datos Affirmation. Uno debe llamarse stringResourceId y el otro imageResourceId. Ambos deben ser números enteros.

Affirmation.kt

data class Affirmation(
    val stringResourceId: Int,
    val imageResourceId: Int
)

Anota la propiedad stringResourceId con la anotación @StringRes y anota el imageResourceId con la anotación @DrawableRes. stringResourceId representa un ID para el texto de afirmación almacenado en un recurso de cadenas. imageResourceId representa un ID para la imagen de afirmación almacenada en un recurso de elementos de diseño.

Affirmation.kt

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

data class Affirmation(
    @StringRes val stringResourceId: Int,
    @DrawableRes val imageResourceId: Int
)

En el paquete com.example.affirmations.data, abre el archivo Datasource.kt y quita los comentarios de las dos sentencias de importación y el contenido de la clase Datasource.

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. Cómo agregar una lista a tu app

Crea una tarjeta de elemento de lista

Esta app está diseñada para mostrar una lista de afirmaciones. El primer paso para configurar la IU para mostrar una lista es crear un elemento de lista. Cada elemento de afirmación consta de una imagen y una cadena. Los datos para cada uno de estos elementos vienen con el código de partida, y crearás el componente de IU para mostrar ese elemento.

El elemento se compone de un elemento Card componible que contiene un elemento Image componible y uno Text. En Compose, un Card es una superficie que muestra contenido y acciones en un solo contenedor. La tarjeta de Affirmation se verá de la siguiente manera en la vista previa:

La tarjeta muestra una imagen con un poco de texto debajo. Este diseño vertical se puede lograr usando un elemento componible Column en un elemento Card. Puedes probarlo tú mismo o seguir los pasos a continuación para lograrlo.

Abre el archivo MainActivity.kt.

Crea un método nuevo debajo del método AffirmationsApp(), llamado AffirmationCard(), y anótalo con la anotación @Composable.

MainActivity.kt

@Composable
fun AffirmationsApp() {
}

@Composable
fun AffirmationCard() {

}

Edita la firma del método para tomar un objeto Affirmation como parámetro. El objeto Affirmation proviene del paquete model.

MainActivity.kt

import com.example.affirmations.model.Affirmation

@Composable
fun AffirmationCard(affirmation: Affirmation) {

}

Agrega un parámetro modifier a la firma. Establece un valor predeterminado de Modifier para el parámetro.

MainActivity.kt

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

}

Dentro del método AffirmationCard, llama al elemento componible Card. Pasa el parámetro modifier.

MainActivity.kt

import androidx.compose.material3.Card

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

    }
}

Agrega un elemento Column componible dentro del elemento Card. Los elementos dentro de un elemento Column componible se organizan automáticamente en la IU. Esto te permite colocar una imagen sobre el texto asociado. Por el contrario, un elemento Row componible organiza los elementos contenidos de manera horizontal.

MainActivity.kt

import androidx.compose.foundation.layout.Column

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

        }
    }

}

Agrega un elemento Image componible dentro del cuerpo de lambda del elemento componible Column. Recuerda que un elemento Image componible siempre requiere un recurso para mostrarse y una contentDescription. El recurso debe ser un painterResource que se pase al parámetro painter. El método painterResource cargará elementos de diseño vectoriales o formatos de elementos de trama, como PNG. Además, pasa un elemento stringResource para el parámetro contentDescription.

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

Además de los parámetros painter y contentDescription, pasa una modifier y una contentScale. Una contentScale determina cómo se debe escalar y mostrar la imagen. El objeto Modifier debe tener establecido el atributo fillMaxWidth y una altura de 194.dp. El contentScale debe ser 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
            )
        }
    }
}

Dentro de la Column, crea un elemento Text componible después del elemento componible Image. Pasa un elemento stringResource de affirmation.stringResourceId al parámetro text, pasa un objeto Modifier con el atributo padding configurado en 16.dp y establece un tema de texto pasando MaterialTheme.typography.headlineSmall al parámetro 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
            )
        }
    }
}

Obtén una vista previa del elemento componible AffirmationCard

La tarjeta es el núcleo de la IU de la app de Affirmations, y te esforzaste por crearla. Para comprobar que la tarjeta se vea bien, puedes crear un elemento componible para obtener una vista previa sin tener que iniciar toda la app.

Crea un método privado llamado AffirmationCardPreview(). Anota el método con @Preview y @Composable.

MainActivity.kt

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

@Preview
@Composable
private fun AffirmationCardPreview() {

}

Dentro del método, llama al elemento componible AffirmationCard y pásale un nuevo objeto Affirmation con el recurso de cadenas R.string.affirmation1 y el recurso de elementos de diseño R.drawable.image1 que se pasó a su constructor.

MainActivity.kt

@Preview
@Composable
private fun AffirmationCardPreview() {
    AffirmationCard(Affirmation(R.string.affirmation1, R.drawable.image1))
}

Abre la pestaña Split y obtendrás una vista previa de AffirmationCard. Si es necesario, haz clic en Build & Refresh en el panel Design para mostrar la vista previa.

Cómo crear la lista

El componente del elemento de lista es el componente básico de la lista. Una vez que se crea el elemento de la lista, puedes aprovecharlo para crear el componente de la lista.

Crea una función llamada AffirmationList(), anótala con la anotación @Composable y declara un List de objetos Affirmation como parámetro en la firma del método.

MainActivity.kt

@Composable
fun AffirmationList(affirmationList: List<Affirmation>) {

}

Declara un objeto modifier como parámetro en la firma del método con un valor predeterminado de Modifier.

MainActivity.kt

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

}

En Jetpack Compose, se puede crear una lista desplazable con el elemento componible LazyColumn. La diferencia entre un elemento LazyColumn y un objeto Column es que debe usarse un objeto Column cuando tienes una pequeña cantidad de elementos para mostrar, ya que Compose los carga todos a la vez. Un Column solo puede contener una cantidad predefinida o fija de elementos componibles. Un elemento LazyColumn puede agregar contenido a pedido, lo que lo hace útil para listas largas y, en especial, cuando se desconoce la longitud de la lista. Un LazyColumn también proporciona desplazamiento de manera predeterminada, sin código adicional. Declara un elemento LazyColumn componible dentro de la función AffirmationList(). Pasa el objeto modifier como argumento a LazyColumn.

MainActivity.kt

import androidx.compose.foundation.lazy.LazyColumn

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

    }
}

En el cuerpo de lambda de LazyColumn, llama al método items() y pasa affirmationList. El método items() es la manera en la que agregas elementos a LazyColumn. Este método es algo único de ese elemento y no se suele usar para la mayoría de los elementos componibles.

MainActivity.kt

import androidx.compose.foundation.lazy.items

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

        }
    }
}

Una llamada al método items() requiere una función lambda. En esa función, especifica un parámetro de affirmation que represente un elemento de afirmación de affirmationList.

MainActivity.kt

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

        }
    }
}

Para cada afirmación de la lista, llama al elemento componible AffirmationCard(). Pásale la affirmation y un objeto Modifier con el atributo padding establecido en 8.dp.

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

Cómo mostrar la lista

En la expresión lambda, llama al elemento componible AffirmationList y pasa DataSource().loadAffirmations() al parámetro affirmationList.

MainActivity.kt

import com.example.affirmations.data.Datasource

@Composable
fun AffirmationsApp() {
    AffirmationList(
        affirmationList = Datasource().loadAffirmations(),
    )
}

Ejecuta la app de Affirmations en un dispositivo o emulador y mira el producto terminado.

4. Obtén el código de la solución

Para descargar el código del codelab terminado, puedes usar estos comandos de 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

También puedes descargar el repositorio como un archivo ZIP, descomprimirlo y abrirlo en Android Studio.

Descargar ZIP

Si deseas ver el código de la solución, puedes hacerlo en GitHub.

5. Conclusión

Ahora sabes cómo crear tarjetas, elementos de lista y listas desplazables con Jetpack Compose. Ten en cuenta que estas son solo herramientas básicas para crear una lista. Puedes darle rienda suelta a tu creatividad y personalizar los elementos de la lista como quieras.

Resumen

Usa elementos componibles Card para crear elementos de lista.
Modifica la IU contenida dentro de un elemento Card componible.
Crea una lista desplazable con el elemento LazyColumn componible.
Crea una lista con elementos de una lista personalizada.