Jetpack Compose Cheatsheet

@Composable y setContent

Una función marcada con @Composable pinta interfaz. Su nombre empieza por mayúscula (como una clase) y no devuelve nada. La Activity carga la primera pantalla con setContent.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            MiAppTheme {
                Saludo(nombre = "Eva")
            }
        }
    }
}

@Composable
fun Saludo(nombre: String, modifier: Modifier = Modifier) {
    Text(text = "Hola, $nombre", modifier = modifier)
}

Buena práctica: que cada composable reciba un modifier: Modifier = Modifier como primer parámetro opcional y lo aplique a su elemento raíz. Así quien lo usa puede darle tamaño, márgenes o posición.

@Preview

Muestra el composable en el panel de diseño de Android Studio sin ejecutar la app.

@Preview(showBackground = true, name = "Claro")
@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES, name = "Oscuro")
@Composable
fun SaludoPreview() {
    MiAppTheme {
        Saludo(nombre = "Android")
    }
}

Recomposición

Cuando cambia un dato que la interfaz está leyendo (un estado), Compose vuelve a ejecutar solo los composables afectados. A esto se le llama recomposición.

Tamaño y espacio

Aspecto

Interacción y scroll

Ojo: para listas largas no uses verticalScroll, usa LazyColumn: solo crea los elementos que se ven en pantalla.

El orden importa

Cada modificador se aplica sobre el resultado del anterior. Cambiar el orden cambia el resultado:

// El fondo cubre también el padding: caja azul grande con el texto dentro
Modifier.background(Color.Blue).padding(16.dp)

// El padding va primero: queda un margen transparente alrededor del fondo
Modifier.padding(16.dp).background(Color.Blue)

// clip antes de clickable: la onda del clic respeta las esquinas redondeadas
Modifier.clip(RoundedCornerShape(12.dp)).clickable { }

horizontalArrangement Row

Cómo se reparten los elementos a lo largo de la fila.

verticalArrangement Column

Cómo se reparten los elementos a lo largo de la columna.

Box() y contentAlignment

Los hijos se apilan; el último queda encima. Para colocarlos se usa contentAlignment en el Box o Modifier.align() en cada hijo:

Box(modifier = Modifier.size(120.dp)) {
    Image(painterResource(R.drawable.foto), contentDescription = null, modifier = Modifier.matchParentSize())
    Text("Oferta", modifier = Modifier.align(Alignment.TopEnd).padding(8.dp))
}

LazyColumn / LazyRow Nuevo

LazyColumn(
    modifier = Modifier.fillMaxSize(),
    contentPadding = PaddingValues(16.dp),
    verticalArrangement = Arrangement.spacedBy(8.dp)
) {
    item {
        Text("Cabecera", style = MaterialTheme.typography.titleLarge)
    }
    items(productos, key = { it.id }) { producto ->
        ProductoCard(producto)
    }
}

Import: items(lista) necesita import androidx.compose.foundation.lazy.items. Si Android Studio marca error con una lista, suele ser esto.

LazyVerticalGrid()

LazyVerticalGrid(
    columns = GridCells.Adaptive(minSize = 128.dp),
    contentPadding = PaddingValues(8.dp),
    horizontalArrangement = Arrangement.spacedBy(8.dp),
    verticalArrangement = Arrangement.spacedBy(8.dp)
) {
    items(fotos) { foto -> FotoItem(foto) }
}

Text()

Textos en recursos: Text(stringResource(R.string.titulo)) lee de strings.xml y permite traducir la app.

TextField / OutlinedTextField

TextField tiene fondo relleno y OutlinedTextField solo borde. Los dos se usan igual y necesitan un estado donde guardar lo escrito.

Buscador Ejemplo

@Composable
fun SearchField(label: String, modifier: Modifier = Modifier) {
    var search by remember { mutableStateOf("") }

    TextField(
        value = search,
        onValueChange = { search = it },
        label = { Text(text = label) },
        leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
        singleLine = true,
        modifier = modifier
    )
}

Para filtrar una lista con lo que se escribe, el texto tiene que estar en el padre: mira la elevación de estado y el ejemplo completo.

Button()

Propiedades comunes

Button(onClick = { guardar() }) {
    Icon(Icons.Default.Check, contentDescription = null)
    Spacer(Modifier.width(8.dp))
    Text("Guardar")
}

Checkbox, Switch y RadioButton Nuevo

Funcionan igual que un campo de texto: un estado con el valor y una lambda que lo cambia.

var aceptado by remember { mutableStateOf(false) }
var notificaciones by remember { mutableStateOf(true) }

Row(verticalAlignment = Alignment.CenterVertically) {
    Checkbox(checked = aceptado, onCheckedChange = { aceptado = it })
    Text("Acepto las condiciones")
}

Switch(checked = notificaciones, onCheckedChange = { notificaciones = it })

val opciones = listOf("Pequeño", "Mediano", "Grande")
var elegida by remember { mutableStateOf(opciones[0]) }
opciones.forEach { opcion ->
    Row(
        Modifier.fillMaxWidth().selectable(selected = opcion == elegida, onClick = { elegida = opcion }),
        verticalAlignment = Alignment.CenterVertically
    ) {
        RadioButton(selected = opcion == elegida, onClick = null)
        Text(opcion)
    }
}

Fila entera pulsable: con Modifier.selectable en la fila y onClick = null en el RadioButton, el usuario puede tocar también el texto.

Slider Nuevo

var volumen by remember { mutableFloatStateOf(5f) }

Slider(
    value = volumen,
    onValueChange = { volumen = it },
    valueRange = 0f..10f,
    steps = 9   // 9 paradas intermedias: valores enteros del 0 al 10
)
Text("Volumen: ${volumen.toInt()}")

Card()

También existen ElevatedCard (con sombra) y OutlinedCard (con borde). Surface es la versión más básica: un fondo con color, forma y sombra.

Scaffold con barra superior y botón flotante Nuevo

Es el esqueleto de una pantalla: coloca la barra superior, la inferior, el botón flotante y los avisos, y te pasa el espacio que queda libre.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun PantallaLista() {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Mis tareas") },
                actions = {
                    IconButton(onClick = { /* ajustes */ }) {
                        Icon(Icons.Default.Settings, contentDescription = "Ajustes")
                    }
                }
            )
        },
        floatingActionButton = {
            FloatingActionButton(onClick = { /* nueva tarea */ }) {
                Icon(Icons.Default.Add, contentDescription = "Añadir")
            }
        }
    ) { innerPadding ->
        LazyColumn(contentPadding = innerPadding) {
            // ...
        }
    }
}

No ignores innerPadding: si no lo aplicas, el contenido queda tapado por las barras.

AlertDialog Nuevo

El diálogo se muestra mientras una condición sea verdadera.

var mostrarDialogo by remember { mutableStateOf(false) }

if (mostrarDialogo) {
    AlertDialog(
        onDismissRequest = { mostrarDialogo = false },
        title = { Text("¿Borrar tarea?") },
        text = { Text("Esta acción no se puede deshacer.") },
        confirmButton = {
            TextButton(onClick = { borrar(); mostrarDialogo = false }) { Text("Borrar") }
        },
        dismissButton = {
            TextButton(onClick = { mostrarDialogo = false }) { Text("Cancelar") }
        }
    )
}

Snackbar Nuevo

Aviso breve en la parte inferior. Se muestra desde una corrutina, porque espera a que desaparezca.

val snackbarHostState = remember { SnackbarHostState() }
val scope = rememberCoroutineScope()

Scaffold(snackbarHost = { SnackbarHost(snackbarHostState) }) { innerPadding ->
    Button(
        onClick = { scope.launch { snackbarHostState.showSnackbar("Guardado") } },
        modifier = Modifier.padding(innerPadding)
    ) { Text("Guardar") }
}

Icon()

¿Faltan iconos? El paquete básico trae pocos. Para tener todos, añade la dependencia androidx.compose.material:material-icons-extended, o importa iconos sueltos desde Android Studio (New → Vector Asset).

Image()

Imágenes de internet con Coil Nuevo

Compose no descarga imágenes por sí solo. La librería más usada es Coil: añade io.coil-kt.coil3:coil-compose y io.coil-kt.coil3:coil-network-okhttp, y el permiso de internet en el AndroidManifest.xml.

AsyncImage(
    model = producto.urlFoto,
    contentDescription = producto.nombre,
    contentScale = ContentScale.Crop,
    placeholder = painterResource(R.drawable.cargando),
    error = painterResource(R.drawable.sin_foto),
    modifier = Modifier.size(80.dp).clip(RoundedCornerShape(8.dp))
)

<uses-permission android:name="android.permission.INTERNET" />

remember + mutableStateOf

@Composable
fun Contador() {
    var contador by remember { mutableStateOf(0) }

    Button(onClick = { contador++ }) {
        Text("Pulsado $contador veces")
    }
}

Si by da error, faltan estos imports: import androidx.compose.runtime.getValue y import androidx.compose.runtime.setValue.

Tipos de estado

Error típico: mutableStateOf(mutableListOf()) y luego lista.add(x) no repinta, porque la lista es la misma. Usa mutableStateListOf() o crea una lista nueva: lista = lista + x.

Elevación de estado (state hoisting)

Si dos composables necesitan el mismo dato, el estado se sube al padre común. El hijo recibe el valor y un evento para cambiarlo, así no guarda nada y es fácil de reutilizar y probar.

// Hijo sin estado: solo muestra y avisa
@Composable
fun Buscador(texto: String, onTextoChange: (String) -> Unit) {
    OutlinedTextField(value = texto, onValueChange = onTextoChange, label = { Text("Buscar") })
}

// Padre con el estado: lo comparte con el buscador y con la lista
@Composable
fun PantallaProductos(productos: List<Producto>) {
    var texto by rememberSaveable { mutableStateOf("") }
    val filtrados = productos.filter { it.nombre.contains(texto, ignoreCase = true) }

    Column {
        Buscador(texto = texto, onTextoChange = { texto = it })
        ListaProductos(filtrados)
    }
}

ViewModel + StateFlow

data class TareasUiState(
    val tareas: List<Tarea> = emptyList(),
    val cargando: Boolean = false
)

class TareasViewModel : ViewModel() {
    private val _uiState = MutableStateFlow(TareasUiState())
    val uiState: StateFlow<TareasUiState> = _uiState.asStateFlow()

    fun anadir(titulo: String) {
        _uiState.update { estado ->
            estado.copy(tareas = estado.tareas + Tarea(titulo))
        }
    }
}

La pantalla obtiene el ViewModel y lee su estado:

@Composable
fun PantallaTareas(viewModel: TareasViewModel = viewModel()) {
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    LazyColumn {
        items(uiState.tareas) { tarea -> Text(tarea.titulo) }
    }
}

Dependencias: androidx.lifecycle:lifecycle-viewmodel-compose (para viewModel()) y androidx.lifecycle:lifecycle-runtime-compose (para collectAsStateWithLifecycle()).

Operaciones lentas: viewModelScope

Las llamadas a red o a base de datos se lanzan en una corrutina del ViewModel, que se cancela sola si se cierra la pantalla.

fun cargar() {
    viewModelScope.launch {
        _uiState.update { it.copy(cargando = true) }
        val tareas = repositorio.obtenerTareas()   // función suspend
        _uiState.update { it.copy(tareas = tareas, cargando = false) }
    }
}

NavHost con rutas de texto

@Composable
fun AppNavigation() {
    val navController = rememberNavController()

    NavHost(navController = navController, startDestination = "inicio") {
        composable("inicio") {
            PantallaInicio(onVerDetalle = { id -> navController.navigate("detalle/$id") })
        }
        composable("detalle/{id}") { backStackEntry ->
            val id = backStackEntry.arguments?.getString("id")
            PantallaDetalle(id = id, onVolver = { navController.popBackStack() })
        }
    }
}

Buena práctica: no pases el navController a cada pantalla; pásales lambdas como onVerDetalle. Así las pantallas no dependen de la navegación y se pueden previsualizar.

Rutas con tipos (type-safe)

Desde Navigation 2.8 las rutas pueden ser objetos de Kotlin en lugar de textos, y el compilador comprueba los argumentos. Necesita el plugin de kotlinx.serialization.

@Serializable object Inicio
@Serializable data class Detalle(val id: Int)

NavHost(navController, startDestination = Inicio) {
    composable<Inicio> {
        PantallaInicio(onVerDetalle = { id -> navController.navigate(Detalle(id)) })
    }
    composable<Detalle> { backStackEntry ->
        val detalle: Detalle = backStackEntry.toRoute()
        PantallaDetalle(id = detalle.id)
    }
}

LaunchedEffect

Lanza una corrutina al aparecer el composable y la repite solo si cambia la clave.

@Composable
fun PantallaDetalle(id: Int, viewModel: DetalleViewModel = viewModel()) {
    LaunchedEffect(id) {
        viewModel.cargar(id)   // se ejecuta al entrar y cada vez que cambie id
    }
    // ...
}

MaterialTheme

Text(
    text = "Título",
    style = MaterialTheme.typography.headlineSmall,
    color = MaterialTheme.colorScheme.primary
)

Surface(
    color = MaterialTheme.colorScheme.surfaceVariant,
    shape = MaterialTheme.shapes.medium
) { /* ... */ }

Tipografía del tema

colorResource o tema: colorResource(R.color.X) lee de colors.xml y está bien para un color concreto, pero no cambia con el modo oscuro. Para la app entera, define los colores en Theme.kt.

Lista de tareas

data class Tarea(val id: Int, val titulo: String, val hecha: Boolean = false)

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun PantallaTareas() {
    val tareas = remember { mutableStateListOf<Tarea>() }
    var texto by rememberSaveable { mutableStateOf("") }
    var aBorrar by remember { mutableStateOf<Tarea?>(null) }

    Scaffold(topBar = { TopAppBar(title = { Text("Tareas (${tareas.count { !it.hecha }})") }) }) { innerPadding ->
        Column(Modifier.padding(innerPadding).padding(16.dp)) {
            Row(verticalAlignment = Alignment.CenterVertically) {
                OutlinedTextField(
                    value = texto,
                    onValueChange = { texto = it },
                    label = { Text("Nueva tarea") },
                    singleLine = true,
                    modifier = Modifier.weight(1f)
                )
                Spacer(Modifier.width(8.dp))
                Button(
                    onClick = {
                        tareas.add(Tarea(id = (tareas.maxOfOrNull { it.id } ?: 0) + 1, titulo = texto.trim()))
                        texto = ""
                    },
                    enabled = texto.isNotBlank()
                ) { Text("Añadir") }
            }

            Spacer(Modifier.height(16.dp))

            LazyColumn(verticalArrangement = Arrangement.spacedBy(8.dp)) {
                items(tareas, key = { it.id }) { tarea ->
                    Card {
                        Row(Modifier.fillMaxWidth().padding(8.dp), verticalAlignment = Alignment.CenterVertically) {
                            Checkbox(
                                checked = tarea.hecha,
                                onCheckedChange = { marcada ->
                                    val i = tareas.indexOf(tarea)
                                    tareas[i] = tarea.copy(hecha = marcada)
                                }
                            )
                            Text(
                                text = tarea.titulo,
                                textDecoration = if (tarea.hecha) TextDecoration.LineThrough else null
                            )
                            Spacer(Modifier.weight(1f))   // empuja la papelera a la derecha
                            IconButton(onClick = { aBorrar = tarea }) {
                                Icon(Icons.Default.Delete, contentDescription = "Borrar")
                            }
                        }
                    }
                }
            }
        }
    }

    aBorrar?.let { tarea ->
        AlertDialog(
            onDismissRequest = { aBorrar = null },
            title = { Text("¿Borrar «${tarea.titulo}»?") },
            confirmButton = { TextButton(onClick = { tareas.remove(tarea); aBorrar = null }) { Text("Borrar") } },
            dismissButton = { TextButton(onClick = { aBorrar = null }) { Text("Cancelar") } }
        )
    }
}

Siguiente paso: mover tareas a un ViewModel para que no se pierdan al girar la pantalla, y guardarlas con Room o DataStore para que sobrevivan al cerrar la app.