Saltar a contenido

Tema 3.1 - Navegación: grafo, argumentos y enlaces profundos

La navegación básica (NavHost, navigate(), popBackStack()) se vio en Desarrollo de Interfaces (DI-U2.1 §6). Aquí la pantalla de destino necesita saber qué ficha mostrar (un argumento), la app tiene que sobrevivir a un argumento que no existe, y un enlace externo (ismaelagenda://ficha/3) tiene que abrir la app directamente en esa ficha.

🟢 Leyenda de repaso obligatorio: los textos con este fondo verde son imprescindibles: hay que repasarlos cada semana, porque entrarán en todas las evaluaciones del módulo.
Código Descripción
RA 2 Desarrolla aplicaciones para dispositivos móviles analizando y empleando las tecnologías y librerías específicas.
CE a) Se ha generado la estructura de clases necesaria para la aplicación.
CE b) Se han analizado y utilizado las clases que modelan ventanas, menús, alertas y controles para el desarrollo de aplicaciones gráficas sencillas.
CE g) Se han realizado pruebas de interacción usuario-aplicación para optimizar las aplicaciones desarrolladas a partir de emuladores.

La app de referencia es IsmaelAgenda, una agenda que se llena de datos en memoria, luego en Room y por último contra un servidor. Las capturas son de este código en el emulador.

1. La ruta como contrato

Un argumento de ruta es la única forma limpia de decirle a una pantalla QUÉ datos mostrar: la ruta es el contrato, no una variable global.

2. El grafo: rutas con argumento

El NavHost es el mapa de la app. La ruta con {id} declara un hueco que se rellena al navegar, y navArgument fija su tipo (IntType):

val nav = rememberNavController()                       // mando de navegación que sobrevive a recomposiciones
Scaffold(                                              // andamio Material: barra + contenido
    topBar = { TopAppBar(title = { Text("IsmaelAgenda · navegación") }) }
) { relleno ->                                        // relleno = hueco que ocupa la barra
    NavHost(                                           // aquí se declaran todas las pantallas
        navController = nav,                           // el mando
        startDestination = "inicio",                    // primera pantalla al abrir
        modifier = Modifier.padding(relleno)            // respeta la barra superior
    ) {
        composable("inicio") {                          // pantalla de la lista
            PantallaInicio(nav)                         // recibe el mando para poder navegar
        }
        composable(                                     // pantalla de detalle con argumento
            route = "detalle/{id}",                     // {id} es el hueco del argumento
            arguments = listOf(navArgument("id") { type = NavType.IntType }), // se exige entero
            deepLinks = listOf(navDeepLink { uriPattern = "ismaelagenda://ficha/{id}" }) // enlace externo
        ) { entrada ->                                  // entrada = back stack entry de esta pantalla
            val id = entrada.arguments?.getInt("id") ?: 0 // argumento leído con valor por defecto
            PantallaDetalle(nav, id)                    // pinta la ficha pedida
        }
        composable("acerca") {                          // pantalla estática sin argumentos
            PantallaAcerca(nav)                         // demuestra que también se navega a lo simple
        }
    }
}

navArgument("id") { type = NavType.IntType } obliga a que el argumento sea un entero: si llega otra cosa, la navegación falla en vez de reventar dentro de la pantalla.

Al pulsar una ficha navegamos metiendo el id dentro de la ruta:

.clickable { nav.navigate("detalle/${ficha.id}") }

Pantalla de inicio de IsmaelAgenda con la lista de fichas y el botón Acerca de IsmaelAgenda

Figura 1. Cada tarjeta navega a detalle/{id} con el id de su ficha.

Pantalla de detalle con el texto Argumento recibido: id = 1 y la ficha de Alé Soto

Figura 2. El detalle recibe id = 1 y pinta la ficha de Alé Soto: la ruta lleva el dato.

3. La pila: empujar y desapilar

Cada navigate() empuja una entrada en la pila (back stack) y popBackStack() desapila la de arriba. El botón Atrás del sistema hace lo mismo.

fun EscenaPila() {                                         // 3.1b: la pila de navegación
    val nav = rememberNavController()                       // mando de navegación
    val pila by nav.currentBackStack.collectAsState()      // lista viva de entradas de la pila
    Scaffold(topBar = { TopAppBar(title = { Text("Pila de navegación") }) }) { relleno ->
        Column(
            Modifier.fillMaxSize().padding(relleno).padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(12.dp)
        ) {
            Text("Pantallas en la pila: ${pila.size}", style = MaterialTheme.typography.headlineSmall)
            Text(
                pila.joinToString(" > ") { it.destination.route ?: "?" }, // ruta de cada entrada
                style = MaterialTheme.typography.bodyMedium
            )
            Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
                Button(onClick = { nav.navigate("detalle/3") }) { Text("Empujar detalle/3") }
                Button(onClick = { nav.popBackStack() }) { Text("Desapilar") }
            }
            NavHost(                                        // el grafo real: sin él, navegar revienta
                navController = nav,
                startDestination = "inicio",
                modifier = Modifier.weight(1f)              // ocupa el resto de la pantalla
            ) {
                composable("inicio") {                      // pantalla inicial del grafo
                    Text("Estás en inicio. Pulsa Empujar detalle/3.")
                }
                composable(
                    route = "detalle/{id}",
                    arguments = listOf(navArgument("id") { type = NavType.IntType })
                ) { entrada ->
                    val id = entrada.arguments?.getInt("id") ?: 0
                    Text("Detalle $id dentro del grafo", style = MaterialTheme.typography.titleMedium)
                }
            }
        }
    }
}

nav.currentBackStack es un Flow: con collectAsState() la pantalla se redibuja sola cada vez que la pila cambia. Es la forma de depurar navegación sin adivinar.

Pantalla de pila de navegación mostrando Pantallas en la pila: 2 y las rutas separadas por mayor que

Figura 3. La pila en vivo: al empujar detalle/3 sube a 3 entradas; al desapilar, baja.

4. Argumentos que no existen: nulabilidad

Un deep link o un test pueden navegar a detalle/99; si el código hace AGENDA[99], la app revienta. Como en el Tema 2, toda extra y todo argumento se leen con valor por defecto.

fun PantallaDetalle(nav: NavController, id: Int) {          // detalle: recibe el id de la ruta
    val ficha = AGENDA.firstOrNull { it.id == id }          // busca la ficha o null si el id no existe
    Column(Modifier.fillMaxSize().padding(16.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
        Text(                                              // el argumento, tal cual llegó
            "Argumento recibido: id = $id",
            style = MaterialTheme.typography.labelLarge
        )
        Text(
            ficha?.nombre ?: "No existe ninguna ficha con id $id", // valor por defecto si no hay ficha
            style = MaterialTheme.typography.headlineSmall
        )
        ficha?.let { Text(it.telefono, style = MaterialTheme.typography.bodyLarge) }
        Button(onClick = { nav.popBackStack() }) { Text("Volver (popBackStack)") } // desapila
    }
}

entrada.arguments?.getInt("id") ?: 0 y firstOrNull { it.id == id } son las dos barreras: si el id no existe, la pantalla informa en vez de cerrarse.

Pantalla de detalle con id 99 y el mensaje No existe ninguna ficha con id 99

Figura 4. detalle/99: la ficha no existe y la app lo dice en pantalla, sin cerrarse.

Un deep link es una URL que abre la app en una pantalla concreta. Se declara en el AndroidManifest.xml (Android sabe que la app responde a ese esquema) y en el grafo con navDeepLink (Navigation sabe a qué pantalla ir).

    <activity
        android:name=".MainActivity"
        android:exported="true"
        android:label="@string/app_name"
        android:theme="@style/Theme.MyApplication"
        android:windowSoftInputMode="adjustResize">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="ismaelagenda" android:host="ficha" />
        </intent-filter>
    </activity>

El esquema ismaelagenda y el host ficha son un contrato público: cualquier app, QR o correo puede abrir ismaelagenda://ficha/3 y aterrizar en tu pantalla de detalle.

Pantalla de detalle abierta por deep link con id 3 y la ficha de Manolo Alcántara

Figura 5. Prueba con adb shell am start -a android.intent.action.VIEW -d ismaelagenda://ficha/3: la app se abre en la ficha 3.

6. Rutas type-safe

Desde Navigation 2.8 las rutas pueden ser clases serializables (@Serializable object Inicio y composable<Inicio> { }): el compilador comprueba los argumentos. Aquí se usan rutas de texto porque funcionan en cualquier versión.

7. Errores típicos (y cómo se ven)

Error Qué pasa Solución
Navegar sin NavHost montado IllegalStateException: no hay grafo el NavHost debe envolver a la pantalla que navega
Ruta mal escrita (detalle/abc) la navegación no encuentra destino tipo del argumento + ruta exacta
Leer el argumento sin ? NullPointerException al abrir por deep link ?: valorPorDefecto
popBackStack() en la raíz no hace nada (no hay a dónde volver) comprobar previousBackStackEntry
Deep link sin navDeepLink Android abre la app pero se queda en inicio declararlo en el grafo, no solo en el Manifest

8. Resumen

  • La ruta es el contrato: detalle/{id} dice qué necesita la pantalla; navArgument fija el tipo.
  • La pila se puede leer (currentBackStack) y manipular (popBackStack).

En la práctica se construye el grafo de una agenda con argumento tipado, control de la pila y un deep link propio, y las capturas de la entrega deben demostrar los cinco comportamientos de las figuras 1 a 5 (CE g).

Lo que tienes que llevarte de este apartado

  • Toda ruta con argumento se declara con plantilla (detalle/{id}) y se navega con la ruta resuelta (detalle/3): si navegas a la plantilla literal, el argumento no llega.
  • Los argumentos viajan en un Bundle, así que solo caben tipos simples (Int, Long, String, Boolean). Un objeto completo se pasa por su id y se vuelve a leer.
  • Un deep link no funciona solo: necesita su intent-filter en el AndroidManifest.xml. Sin esa declaración, el enlace abre el navegador, no tu app.
  • El botón atrás del sistema ya hace popBackStack(): no lo interceptes ni lo reimplementes, o el usuario pierde la navegación esperada.

Presentación