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.
| 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:

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

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.

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.

Figura 4. detalle/99: la ficha no existe y la app lo dice en pantalla, sin cerrarse.
5. Deep links: que la app se abra desde fuera¶
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.

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;navArgumentfija 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 suidy se vuelve a leer. - Un deep link no funciona solo: necesita su
intent-filteren elAndroidManifest.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.