Skip to content

5. Navegación

Una aplicación tiene varias pantallas. En [Android], junto con [Compose], no se abre una actividad por pantalla: una ÚNICA actividad muestra por turnos las pantallas de la aplicación, controladas por un ENRUTADOR. Esta es la biblioteca [navigation-compose] de [Jetpack], el equivalente del paquete [go_router] de [Flutter].

5.1. Ejemplo 17: el enrutador

El enrutador asocia una RUTA a cada pantalla y gestiona una PILA de pantallas: una pantalla se apila ([navigate]) y el botón Atrás del teléfono la desapila ([popBackStack]). Las rutas del ejemplo:

// =========================================================================
// ex17/Routes.kt - las RUTAS de la aplicación
// -------------------------------------------------------------------------
// Una aplicación tiene varias pantallas ("páginas"). El ENRUTADOR asocia una
// RUTA a cada pantalla. La biblioteca Jetpack Navigation (navigation-
// compose) gestiona una PILA de pantallas: se apila una pantalla (navigate), el
// botón Atrás del teléfono la desapila (popBackStack).
// Una ruta es un objeto Kotlin, @Serializable:
//   - un "object" para una pantalla sin parámetros (Home);
//   - una "data class" para una pantalla con parámetros: DoctorDetail(id = 2).
// El tipo de los parámetros se verifica en tiempo de compilación: DoctorDetail("2")
// sería rechazado. (Navigation puede guardar estos objetos en la pila, de ahí
// @Serializable.)
// Cada pantalla también puede tener una DIRECCIÓN, un "deep link"
// como app://examples/doctors/2: es lo más parecido,
// en Android, a las direcciones web (cf. Ex17Activity.kt).
// =========================================================================
package fr.stahe.examples.ex17

import kotlinx.serialization.Serializable

@Serializable
object Home

@Serializable
object DoctorList

// un parámetro de ruta
@Serializable
data class DoctorDetail(val id: Int)

// un parámetro OPCIONAL (con un valor predeterminado): ?q=... en la dirección
@Serializable
data class Search(val q: String = "")

@Serializable
object About

// una dirección antigua, que REDIRIGE a la lista de médicos
@Serializable
object Physicians

// la pantalla de las direcciones desconocidas
@Serializable
data class NotFoundPage(val address: String)

// el comienzo de todas las direcciones de este ejemplo
const val BASE = "app://examples"
  • líneas 23–30: una ruta es un objeto [Kotlin] [@Serializable]: un [object] para una pantalla sin parámetros; una [data class] para una pantalla con parámetros: [DoctorDetail(id = 2)]. El tipo de los parámetros se verifica en tiempo de compilación ([DoctorDetail("2")] sería rechazado); [@Serializable]: [Navigation] sabe cómo almacenar estos objetos en la pila y restaurarlos si la actividad se recrea;
  • línea 34: un parámetro opcional con un valor predeterminado;
  • línea 48: cada pantalla puede tener una DIRECCIÓN, un “deep link” de la forma [app://examples/doctors/2]: es lo más cercano, en [Android], a las direcciones web.

Datos “fijos en el código”, para evitar depender de un servidor:

// ex17/Data.kt - datos "codificados en duro", para no depender de un servidor en este ejemplo
package fr.stahe.examples.ex17

data class Doctor(val id: Int, val title: String, val firstName: String, val lastName: String, val specialty: String)

val doctors = listOf(
    Doctor(1, "Mme", "Marie", "PELISSIER", "general practitioner"),
    Doctor(2, "Mr", "Paul", "TATOU", "pediatrician"),
    Doctor(3, "Melle", "Sophie", "DUPONT", "general practitioner"),
)

El grafo de navegación: una entrada por ruta y la pantalla que se debe mostrar:

// =========================================================================
// ex17/Ex17Activity.kt - el NavHost: las rutas y sus pantallas
// -------------------------------------------------------------------------
//   - rememberNavController(): el controlador de navegación (la pila);
//   - NavHost(nav, startDestination = Home) { ... }: la pantalla de la
//     ruta actual. El bloque describe el GRAFO de navegación: una entrada
//     composable<Route> { ... } por ruta;
//   - entry.toRoute<DoctorDetail>(): el objeto de ruta de la pantalla, con
//     sus parámetros;
//   - deepLinks: la dirección de la pantalla. Gracias al intent filter de
//     la actividad (AndroidManifest.xml), una dirección app://examples/...
//     puede incluso abrirse desde fuera de la aplicación:
//         adb shell am start -a android.intent.action.VIEW -d "app://examples/doctors/2"
// =========================================================================
package fr.stahe.examples.ex17

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.rememberNavController
import androidx.navigation.navDeepLink
import androidx.navigation.toRoute
import fr.stahe.examples.common.ExamplesTheme
import fr.stahe.examples.ex17.pages.AboutPage
import fr.stahe.examples.ex17.pages.HomePage
import fr.stahe.examples.ex17.pages.DoctorDetailPage
import fr.stahe.examples.ex17.pages.DoctorListPage
import fr.stahe.examples.ex17.pages.SearchPage
import fr.stahe.examples.ex17.pages.NotFoundPage as NotFoundScreen

class Ex17Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { App() } }
    }
}

@Composable
fun App() {
    val nav = rememberNavController()
    Shell(nav) {
        NavHost(navController = nav, startDestination = Home) {
            composable<Home>(deepLinks = listOf(navDeepLink<Home>(basePath = "$BASE/home"))) {
                HomePage(onLink = { nav.openLink(it) }, onRedirect = { nav.navigate(Physicians) })
            }
            composable<DoctorList>(deepLinks = listOf(navDeepLink<DoctorList>(basePath = "$BASE/doctors"))) {
                // navigate: la pantalla del médico se APILA encima de la lista
                DoctorListPage(onView = { id -> nav.navigate(DoctorDetail(id)) })
            }
            // app://examples/doctors/2: el parámetro id se toma de la dirección
            composable<DoctorDetail>(deepLinks = listOf(navDeepLink<DoctorDetail>(basePath = "$BASE/doctors"))) { entry ->
                val route = entry.toRoute<DoctorDetail>()
                DoctorDetailPage(
                    id = route.id,
                    // popBackStack: desapilar la pantalla (como el botón Atrás); si
                    // no hay nada debajo (pantalla abierta por una dirección), ir a la lista
                    onBack = { if (!nav.popBackStack()) nav.navigate(DoctorList) },
                    // REEMPLAZAR la pantalla actual (sin apilar): el médico actual
                    // se desapila (inclusive) antes de apilar el siguiente
                    onNext = { next ->
                        nav.navigate(DoctorDetail(next)) { popUpTo<DoctorDetail> { inclusive = true } }
                    },
                )
            }
            // app://examples/search?q=pediatrician
            composable<Search>(deepLinks = listOf(navDeepLink<Search>(basePath = "$BASE/search"))) { entry ->
                SearchPage(q = entry.toRoute<Search>().q, onSearch = { input -> nav.navigate(Search(input)) })
            }
            composable<About> { AboutPage() }
            // una REDIRECCIÓN: la pantalla no muestra nada, reemplaza de inmediato
            // su propia ruta por otra
            composable<Physicians> {
                LaunchedEffect(Unit) {
                    nav.navigate(DoctorList) { popUpTo<Physicians> { inclusive = true } }
                }
            }
            composable<NotFoundPage> { entry ->
                NotFoundScreen(address = entry.toRoute<NotFoundPage>().address, onHome = { nav.goTo(Home) })
            }
        }
    }
}
  • línea 34: [import ... as NotFoundScreen]: un alias, porque la función de pantalla [NotFoundPage] tiene el mismo nombre que la ruta [NotFoundPage];
  • líneas 46–48: [rememberNavController()]: el controlador de navegación (la pila); [NavHost(nav, startDestination = Home)] muestra la pantalla de la ruta actual;
  • líneas 49–54: una entrada [composable<Route>] por ruta, con su dirección ([deepLinks]). Las pantallas no conocen el enrutador: reciben FUNCIONES para navegar ([onLink], [onView]...);
  • líneas 57–58: [entry.toRoute<DoctorDetail>()]: el objeto de ruta, con sus parámetros. Con [navDeepLink<DoctorDetail>(basePath = ...)], el parámetro [id] se toma de la dirección ([.../doctors/2]);
  • línea 63: [popBackStack()] desapila la pantalla, como el botón Atrás, y devuelve [false] si no hay nada debajo (pantalla abierta mediante una dirección);
  • líneas 66–67: REEMPLAZAR la pantalla actual: el médico actual ([popUpTo<DoctorDetail> [ inclusive = true ]]) se desapila antes de apilar el siguiente;
  • líneas 78–80: una REDIRECCIÓN: la pantalla no muestra nada; reemplaza de inmediato su ruta por otra. La navegación es un “efecto” ([LaunchedEffect]): nunca se navega DURANTE la visualización.

El “armazón” de la aplicación: la barra superior, la barra de pestañas inferior (típica de un dispositivo móvil) y, entre ambas, la pantalla que muestra la ruta actual:

// =========================================================================
// ex17/Shell.kt - el "shell" de la aplicación
// -------------------------------------------------------------------------
// La barra superior, la barra de navegación inferior y, entre las dos,
// la pantalla de la ruta actual (content: el NavHost, cf. Ex17Activity.kt).
//   - nav.currentBackStackEntryAsState(): la pantalla en la CIMA de la pila,
//     un estado observado (el shell se recompone en cada navegación);
//   - destination.hasRoute<DoctorList>(): ¿es la pantalla la de
//     esta ruta?; entry.toRoute<DoctorDetail>(): el objeto de ruta y
//     sus parámetros;
//   - navigate(route) { ... }: ir a una ruta; las opciones del bloque
//     indican qué hacer con la pila (cf. goTo).
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class)

package fr.stahe.examples.ex17

import android.net.Uri
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Info
import androidx.compose.material.icons.filled.Person
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.compose.ui.text.font.FontFamily
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.navigation.NavBackStackEntry
import androidx.navigation.NavDestination
import androidx.navigation.NavDestination.Companion.hasRoute
import androidx.navigation.NavGraph.Companion.findStartDestination
import androidx.navigation.NavHostController
import androidx.navigation.compose.currentBackStackEntryAsState
import androidx.navigation.toRoute

// una pestaña: la ruta a la que lleva, su etiqueta, su ícono y la prueba que
// indica si está activa para una pantalla dada
class Tab(val route: Any, val label: String, val icon: ImageVector, val active: (NavDestination) -> Boolean)

val tabs = listOf(
    Tab(Home, "Home", Icons.Default.Home) { it.hasRoute<Home>() },
    // la pestaña Doctors sigue activa en la pantalla de un médico
    Tab(DoctorList, "Doctors", Icons.Default.Person) { it.hasRoute<DoctorList>() || it.hasRoute<DoctorDetail>() },
    Tab(Search("general practitioner"), "Search", Icons.Default.Search) { it.hasRoute<Search>() },
    Tab(About, "About", Icons.Default.Info) { it.hasRoute<About>() },
)

// la dirección de la pantalla actual, para mostrarla
fun addressOf(entry: NavBackStackEntry?): String {
    val d = entry?.destination ?: return ""
    return when {
        d.hasRoute<Home>() -> "/"
        d.hasRoute<DoctorList>() -> "/doctors"
        d.hasRoute<DoctorDetail>() -> "/doctors/${entry.toRoute<DoctorDetail>().id}"
        d.hasRoute<Search>() -> "/search?q=${entry.toRoute<Search>().q}"
        d.hasRoute<About>() -> "/about"
        d.hasRoute<NotFoundPage>() -> entry.toRoute<NotFoundPage>().address
        else -> "?"
    }
}

// ir a una pestaña: la pila se REEMPLAZA por la de esta pestaña
fun NavHostController.goTo(route: Any) {
    navigate(route) {
        // se desapila todo, hasta la primera pantalla (excluida)...
        popUpTo(graph.findStartDestination().id)
        // ... y la misma pantalla no se apila dos veces
        launchSingleTop = true
    }
}

// seguir un ENLACE (una dirección); una dirección desconocida lleva a NotFoundPage
fun NavHostController.openLink(address: String) {
    try {
        navigate(Uri.parse("$BASE$address"))
    } catch (e: IllegalArgumentException) {
        navigate(NotFoundPage(address))
    }
}

@Composable
fun Shell(nav: NavHostController, content: @Composable () -> Unit) {
    val entry by nav.currentBackStackEntryAsState()
    val destination = entry?.destination
    Scaffold(
        topBar = { TopAppBar(title = { Text("Example 17 - the router") }) },
        // NavigationBar: la barra de pestañas inferior, típica de un móvil
        bottomBar = {
            NavigationBar {
                for (t in tabs) {
                    NavigationBarItem(
                        selected = destination != null && t.active(destination),
                        onClick = { nav.goTo(t.route) },
                        icon = { Icon(t.icon, contentDescription = null) },
                        label = { Text(t.label) },
                    )
                }
            }
        },
    ) { insets ->
        Column(Modifier.padding(insets).fillMaxSize()) {
            Text(
                "current address: ${addressOf(entry)}",
                fontFamily = FontFamily.Monospace,
                fontSize = 12.sp,
                modifier = Modifier.fillMaxWidth().background(Color(0xFFF5F5F5)).padding(8.dp),
            )
            Box(Modifier.padding(16.dp).weight(1f)) { content() }
        }
    }
}
  • líneas 55–62: las pestañas. [hasRoute<DoctorList>()]: ¿es esta la pantalla de esta ruta? La pestaña “Doctors” permanece activa en la pantalla de un médico;
  • líneas 66–75: la dirección de la pantalla actual, para mostrarla;
  • líneas 80–85: ir a una pestaña: la pila se REEMPLAZA ([popUpTo] es la primera pantalla) y la misma pantalla ([launchSingleTop]) no se apila dos veces;
  • líneas 90–94: seguir una dirección: [navigate(Uri)]; una dirección desconocida lanza una excepción: entonces se muestra la pantalla “Page not found”;
  • líneas 100–101: [currentBackStackEntryAsState()]: la pantalla en la CIMA de la pila, un estado observado: el armazón se reconstruye con cada navegación;
  • líneas 106–112: la barra de pestañas ([NavigationBar]).

Las pantallas:

// =========================================================================
// ex17/pages/Pages.kt - las pantallas del ejemplo 17
// -------------------------------------------------------------------------
// Las pantallas no conocen el enrutador: reciben sus parámetros
// (id, q...) y FUNCIONES para navegar (onView, onBack...). Es el
// NavHost (Ex17Activity.kt) quien enlaza estas funciones con las rutas. Una pantalla
// sigue siendo así un componente ordinario, fácil de mostrar por sí solo (en una
// vista previa de Android Studio, en una prueba).
// =========================================================================
@file:OptIn(ExperimentalLayoutApi::class)

package fr.stahe.examples.ex17.pages

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.KeyboardArrowRight
import androidx.compose.material.icons.filled.Search
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.ListItem
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.OutlinedButton
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.runtime.setValue
import androidx.compose.foundation.clickable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.unit.dp
import fr.stahe.examples.common.TaskTitle
import fr.stahe.examples.ex17.doctors

@Composable
fun HomePage(onLink: (String) -> Unit, onRedirect: () -> Unit) {
    TaskTitle("Home")
    Column {
        Text(
            "Welcome. Touch the tabs: the screen changes, and so does its address. The phone's Back " +
                "button pops the pushed screens. An address can also be opened from " +
                "outside the application (cf. the course).",
        )
        Spacer(Modifier.height(16.dp))
        // enlaces a direcciones particulares
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            OutlinedButton(onClick = onRedirect) { Text("/physicians (redirection)") }
            OutlinedButton(onClick = { onLink("/unknown-page") }) { Text("Broken link") }
        }
    }
}

@Composable
fun DoctorListPage(onView: (Int) -> Unit) {
    TaskTitle("Doctors")
    Column {
        for (d in doctors) {
            ListItem(
                headlineContent = { Text("${d.title} ${d.firstName} ${d.lastName}") },
                trailingContent = { Icon(Icons.AutoMirrored.Filled.KeyboardArrowRight, contentDescription = null) },
                // el médico se APILA; el botón Atrás vuelve aquí
                modifier = Modifier.clickable { onView(d.id) },
            )
        }
    }
}

// una página con un parámetro: el enrutador le pasa id, un Int
@Composable
fun DoctorDetailPage(id: Int, onBack: () -> Unit, onNext: (Int) -> Unit) {
    // find: el primer médico que coincide, o null
    val doctor = doctors.find { it.id == id }
    if (doctor == null) {
        Text("Doctor no. $id does not exist.", color = Color.Red)
        return
    }
    val next = doctor.id % doctors.size + 1
    TaskTitle("${doctor.firstName} ${doctor.lastName}")
    Column {
        Text("${doctor.title} ${doctor.firstName} ${doctor.lastName}", style = MaterialTheme.typography.titleLarge)
        Text("Specialty: ${doctor.specialty}")
        Spacer(Modifier.height(16.dp))
        FlowRow(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
            OutlinedButton(onClick = onBack) { Text("Back") }
            Button(onClick = { onNext(next) }) { Text("Next doctor") }
        }
    }
}

// =========================================================================
// una página dirigida por su ruta: Search(q = "pediatrician"). Buscar
// significa IR a la ruta Search(q = <input>): la página muestra lo que
// dice la ruta, y nada más (el botón Atrás vuelve a la búsqueda
// anterior).
// =========================================================================
@Composable
fun SearchPage(q: String, onSearch: (String) -> Unit) {
    TaskTitle("Search")
    val results = doctors.filter { "${it.firstName} ${it.lastName} ${it.specialty}".lowercase().contains(q.lowercase()) }
    // el campo de entrada empieza con el valor de la ruta; rememberSaveable(q):
    // si la ruta cambia (botón Atrás), el campo vuelve a empezar desde el nuevo valor
    var input by rememberSaveable(q) { mutableStateOf(q) }
    Column {
        OutlinedTextField(
            value = input,
            onValueChange = { input = it },
            placeholder = { Text("name or specialty") },
            trailingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
            singleLine = true,
            // la tecla "search" del teclado
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
            keyboardActions = KeyboardActions(onSearch = { onSearch(input.trim()) }),
            modifier = Modifier.fillMaxWidth(),
        )
        Spacer(Modifier.height(8.dp))
        for (d in results) {
            ListItem(headlineContent = { Text("${d.firstName} ${d.lastName} (${d.specialty})") })
        }
        if (results.isEmpty()) {
            ListItem(headlineContent = { Text("No result.", color = Color.Gray) })
        }
    }
}

@Composable
fun AboutPage() {
    TaskTitle("About")
    Text(
        "On a phone, all the code of the application is in its .apk file: there is nothing " +
            "to download on the first visit of a screen (for a very big application, Google " +
            "Play can deliver some modules on demand: Play Feature Delivery).",
    )
}

@Composable
fun NotFoundPage(address: String, onHome: () -> Unit) {
    TaskTitle("Page not found")
    Column {
        Text("No page at the address $address.", color = Color.Red)
        Spacer(Modifier.height(16.dp))
        Button(onClick = onHome) { Text("Back to home") }
    }
}
  • línea 73: [Modifier.clickable]: toda la línea es un enlace;
  • líneas 108–113: una página controlada por su ruta: “Search” VA a la ruta [Search(q = input)]; la página muestra la información de la ruta. [rememberSaveable(q)]: si la ruta cambia (botón Atrás), la entrada se restablece al nuevo valor.

Image

Image

Image

Image

Para que una dirección pueda abrirse desde el EXTERIOR de la aplicación (un enlace en un correo electrónico, otra aplicación), la actividad declara un filtro de intents en el manifiesto:

1
2
3
4
5
6
7
        <activity android:name=".ex17.Ex17Activity" android:exported="true" android:windowSoftInputMode="adjustResize">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:scheme="app" android:host="examples" />
            </intent-filter>
        </activity>

Luego puede probarlo desde una ventana de comandos en la PC, con la herramienta [adb] del SDK de [Android] (emulador iniciado):

adb shell am start -a android.intent.action.VIEW -d "app://examples/doctors/2"

El Ejemplo 17 se abre directamente en la pantalla del médico n.º 2; “Atrás” lleva entonces a la lista ([popBackStack()] devolvió [false]).

5.2. Ejemplo 18: guardias de navegación

Algunas pantallas solo son accesibles para un usuario que haya iniciado sesión o para roles específicos. El usuario que inició sesión, simulado aquí sin servidor, se almacena en un único objeto:

// =========================================================================
// ex18/Session.kt - una sesión SIMULADA (sin servidor)
// -------------------------------------------------------------------------
// El usuario conectado debe ser conocido por las PANTALLAS (la barra superior,
// la agenda) y por los GUARDIAS del enrutador. Se guarda en un objeto
// ÚNICO (object: una clase que tiene una sola instancia, creada en el primer uso):
//   - una propiedad de estado, observada por Compose (mutableStateOf): cualquier
//     componente que la lea se recompone cuando cambia;
//   - funciones para modificarla.
// (El ejemplo 23 hará lo mismo con un servidor real.)
// =========================================================================
package fr.stahe.examples.ex18

import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue

enum class Role { ADMIN, DOCTOR, USER }

data class User(val login: String, val role: Role)

// tres cuentas "codificadas en duro" (contraseña = login)
private val accounts = mapOf("admin" to Role.ADMIN, "pelissier" to Role.DOCTOR, "martin" to Role.USER)

object Session {
    // el estado: null, nadie ha iniciado sesión. private set: modificable solo aquí
    var user by mutableStateOf<User?>(null)
        private set

    fun logIn(login: String, password: String): Boolean {
        val role = accounts[login]
        if (role == null || password != login) {
            return false
        }
        user = User(login, role)
        return true
    }

    fun logOut() {
        user = null
    }
}
  • Líneas 25–26: [object]: una clase con una sola instancia, creada en el primer uso; su propiedad [user] es un estado observado: cualquier componente que la lea se recompone cuando cambia.

Rutas y guardias:

// =========================================================================
// ex18/Routes.kt - rutas PROTEGIDAS por guardias
// -------------------------------------------------------------------------
// Un GUARDIA es una función que recibe al usuario conectado (o null) y
// devuelve:
//   - null: la pantalla se puede mostrar;
//   - una ruta: la pantalla se REEMPLAZA por esta ruta (una redirección).
// El componente Protected(...) aplica los guardias de una pantalla. Como LEE
// al usuario de la sesión (un estado observado), se reevalúa en cada
// inicio o cierre de sesión: se abandona una pantalla que ya no está permitida.
//
// Es el equivalente del lado del cliente de los guardias de NestJS (JwtAuthGuard,
// RolesGuard) - con una diferencia FUNDAMENTAL: un guardia del cliente es
// solo una comodidad. La aplicación está en manos del usuario, que
// puede modificarla a voluntad. La verdadera protección de los datos sigue siendo
// la del SERVIDOR (cf. capítulo sobre la caja negra).
// =========================================================================
package fr.stahe.examples.ex18

import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.navigation.NavHostController
import kotlinx.serialization.Serializable

// denied: lo deja el guardia requireRole cuando el rol no corresponde
@Serializable
data class Home(val denied: String? = null)

// redirect: la dirección de la pantalla que el usuario quería abrir
@Serializable
data class Login(val redirect: String? = null)

@Serializable
object Schedule

@Serializable
object Administration

const val BASE = "app://examples18"

typealias Guard = (User?) -> Any?

// el guardia de "inicio de sesión requerido": sin sesión -> a la página de login,
// recordando la dirección de la pantalla solicitada
fun requireLogin(address: String): Guard = { u -> if (u == null) Login(redirect = address) else null }

// el guardia de "rol requerido": con sesión, pero sin el rol adecuado -> de vuelta a
// la página de inicio, con un motivo
fun requireRole(address: String, vararg roles: Role): Guard = { u ->
    if (u == null || u.role !in roles) Home(denied = address) else null
}

// los guardias, en orden: gana el primero que devuelve una ruta
@Composable
fun Protected(nav: NavHostController, vararg guards: Guard, content: @Composable () -> Unit) {
    val redirection = guards.firstNotNullOfOrNull { guard -> guard(Session.user) }
    if (redirection == null) {
        content()
    } else {
        // navegar es un "efecto": no navegamos DURANTE la visualización
        LaunchedEffect(redirection) {
            val here = nav.currentBackStackEntry?.destination?.id ?: return@LaunchedEffect
            // la pantalla denegada se reemplaza (inclusive) por la redirección
            nav.navigate(redirection) { popUpTo(here) { inclusive = true } }
        }
    }
}
  • línea 41: un GUARDIA es una función que toma al usuario (o [null]) como argumento y devuelve [null] (se puede mostrar la pantalla) o una RUTA (la pantalla se reemplaza por esta ruta);
  • líneas 45–50: dos funciones guardia: “se requiere inicio de sesión” redirige a la pantalla de inicio de sesión conservando la dirección solicitada; “se requiere rol” redirige a la pantalla de bienvenida con un motivo;
  • líneas 55–64: [Protected] aplica los guardias a una pantalla: [firstNotNullOfOrNull], el primer resultado que no es [null]. Como LEE la sesión, se reevalúa con cada inicio o cierre de sesión: se sale de una pantalla que deja de estar permitida.

Este es el equivalente en el cliente de las comprobaciones de [NestJS] ([JwtAuthGuard], [RolesGuard]), con una diferencia: una comprobación en el cliente es solo una comodidad. La aplicación está en manos del usuario; la verdadera protección de los datos sigue siendo la que ofrece el SERVIDOR.

// =========================================================================
// ex18/Ex18Activity.kt - el grafo de navegación, con sus guardias
// -------------------------------------------------------------------------
// Las pantallas protegidas están envueltas por Protected(nav, guards...): sus
// guardias se evalúan cuando se abre la pantalla... y de nuevo en cada
// cambio de la sesión.
// Después de iniciar sesión, se envía al usuario de vuelta a la pantalla que quería
// abrir (su dirección, guardada por el guardia en Login.redirect), o a
// la página de inicio.
// =========================================================================
package fr.stahe.examples.ex18

import android.net.Uri
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.runtime.Composable
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.rememberNavController
import androidx.navigation.navDeepLink
import androidx.navigation.navOptions
import androidx.navigation.toRoute
import fr.stahe.examples.common.ExamplesTheme

class Ex18Activity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent { ExamplesTheme { App() } }
    }
}

@Composable
fun App() {
    val nav = rememberNavController()
    Shell(nav) {
        NavHost(navController = nav, startDestination = Home()) {
            composable<Home> { entry -> HomePage(denied = entry.toRoute<Home>().denied) }
            composable<Login> { entry ->
                LoginPage(
                    redirection = entry.toRoute<Login>().redirect,
                    onLoggedIn = { r ->
                        // solo se acepta una dirección de ESTA aplicación
                        // la pila se vacía (popUpTo todo el grafo): la página de login
                        // no se queda en ella, Atrás no la reabrirá
                        val clearStack = navOptions { popUpTo(nav.graph.id) { inclusive = true } }
                        if (r != null && r.startsWith("$BASE/")) {
                            nav.navigate(Uri.parse(r), clearStack)
                        } else {
                            nav.navigate(Home(), clearStack)
                        }
                    },
                )
            }
            composable<Schedule>(deepLinks = listOf(navDeepLink<Schedule>(basePath = "$BASE/schedule"))) {
                Protected(nav, requireLogin("$BASE/schedule")) { SchedulePage() }
            }
            composable<Administration>(deepLinks = listOf(navDeepLink<Administration>(basePath = "$BASE/administration"))) {
                Protected(nav, requireLogin("$BASE/administration"), requireRole("/administration", Role.ADMIN)) {
                    AdministrationPage()
                }
            }
        }
    }
}
  • líneas 44–52: después de iniciar sesión, el programa va a la dirección almacenada por el guardia (solo si es una dirección de ESTA aplicación); en caso contrario, a la página de inicio; [navOptions { popUpTo(nav.graph.id) [ inclusive = true ] }] vacía la pila: el botón Atrás no reabrirá la pantalla de inicio de sesión;
  • líneas 58–62: las pantallas protegidas, envueltas por [Protected].

El armazón y las pantallas:

// =========================================================================
// ex18/Shell.kt - los enlaces y el usuario conectado
// -------------------------------------------------------------------------
// La barra superior lee Session.user: se recompone en cada
// inicio y cierre de sesión.
// =========================================================================
@file:OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)

package fr.stahe.examples.ex18

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.ExperimentalLayoutApi
import androidx.compose.foundation.layout.FlowRow
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.Scaffold
import androidx.compose.material3.SuggestionChip
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.material3.TopAppBar
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.unit.dp
import androidx.navigation.NavDestination.Companion.hasRoute
import androidx.navigation.NavHostController
import androidx.navigation.compose.currentBackStackEntryAsState

@Composable
fun Shell(nav: NavHostController, content: @Composable () -> Unit) {
    val destination = nav.currentBackStackEntryAsState().value?.destination
    val u = Session.user

    // un enlace: en negrita si designa la pantalla mostrada
    @Composable
    fun Link(route: Any, active: Boolean, label: String) {
        TextButton(onClick = { nav.navigate(route) { launchSingleTop = true } }) {
            Text(label, fontWeight = if (active) FontWeight.Bold else FontWeight.Normal)
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Example 18 - guards") },
                actions = {
                    if (u == null) {
                        TextButton(onClick = { nav.navigate(Login()) }) { Text("login") }
                    } else {
                        SuggestionChip(onClick = {}, label = { Text("${u.login} ${u.role}") })
                        IconButton(onClick = {
                            Session.logOut()
                            nav.navigate(Home()) { popUpTo(nav.graph.id) { inclusive = true } }
                        }) {
                            Icon(Icons.AutoMirrored.Filled.ExitToApp, contentDescription = "logout")
                        }
                    }
                },
            )
        },
    ) { insets ->
        Column(Modifier.padding(insets).fillMaxSize()) {
            FlowRow {
                Link(Home(), destination?.hasRoute<Home>() == true, "Home")
                Link(Schedule, destination?.hasRoute<Schedule>() == true, "Schedule (logged in)")
                Link(Administration, destination?.hasRoute<Administration>() == true, "Administration (ADMIN)")
            }
            HorizontalDivider()
            Box(Modifier.padding(16.dp).weight(1f)) { content() }
        }
    }
}
// =========================================================================
// ex18/Pages.kt - las pantallas del ejemplo 18
// =========================================================================
package fr.stahe.examples.ex18

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.text.KeyboardActions
import androidx.compose.foundation.text.KeyboardOptions
import androidx.compose.material3.Button
import androidx.compose.material3.Card
import androidx.compose.material3.CardDefaults
import androidx.compose.material3.OutlinedTextField
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.text.SpanStyle
import androidx.compose.ui.text.buildAnnotatedString
import androidx.compose.ui.text.font.FontWeight
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.input.PasswordVisualTransformation
import androidx.compose.ui.text.withStyle
import androidx.compose.ui.unit.dp

@Composable
fun HomePage(denied: String?) {
    Column {
        if (denied != null) {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFEBEE))) {
                Text("Your role does not allow opening $denied.", Modifier.padding(12.dp))
            }
            Spacer(Modifier.height(8.dp))
        }
        Text("Public page. Try the other two links, logged in or not (admin, pelissier, martin - password = login).")
    }
}

@Composable
fun SchedulePage() {
    Text(
        buildAnnotatedString {
            append("The schedule of ")
            withStyle(SpanStyle(fontWeight = FontWeight.Bold)) { append(Session.user?.login ?: "") }
            append(": this page requires being logged in.")
        },
    )
}

@Composable
fun AdministrationPage() {
    Text("Administration: page reserved for the ADMIN role.")
}

// =========================================================================
// el login. Tras un inicio de sesión exitoso, onLoggedIn recibe la dirección de
// la pantalla que el usuario quería abrir (parámetro redirect dejado por el guardia),
// o null
// =========================================================================
@Composable
fun LoginPage(redirection: String?, onLoggedIn: (String?) -> Unit) {
    var login by remember { mutableStateOf("") }
    var password by remember { mutableStateOf("") }
    var error by remember { mutableStateOf(false) }

    fun validate() {
        if (!Session.logIn(login.trim(), password)) {
            error = true
            return
        }
        onLoggedIn(redirection)
    }

    Column {
        if (redirection != null) {
            Card(colors = CardDefaults.cardColors(containerColor = Color(0xFFFFF8E1))) {
                Text("Log in to open ${redirection.removePrefix(BASE)}.", Modifier.padding(12.dp))
            }
        }
        OutlinedTextField(value = login, onValueChange = { login = it }, label = { Text("login") }, singleLine = true, modifier = Modifier.fillMaxWidth())
        OutlinedTextField(
            value = password,
            onValueChange = { password = it },
            label = { Text("password") },
            singleLine = true,
            visualTransformation = PasswordVisualTransformation(),
            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Go),
            keyboardActions = KeyboardActions(onGo = { validate() }),
            modifier = Modifier.fillMaxWidth(),
        )
        Spacer(Modifier.height(16.dp))
        Button(onClick = { validate() }) { Text("Log in") }
        if (error) {
            Text("Incorrect login or password.", color = Color.Red, modifier = Modifier.padding(top = 8.dp))
        }
    }
}

Image

Image

Image

A la izquierda, “Administration” sin haber iniciado sesión: el guardia condujo a la pantalla de inicio de sesión; en el centro, con sesión iniciada como [martin] (rol USER): regreso a la página de inicio, con el motivo; a la derecha, con sesión iniciada como [admin].