Skip to content

5. Navegação

Um aplicativo tem várias telas. No [Android], com o [Compose], não se abre uma activity por tela: uma ÚNICA activity exibe as telas do aplicativo uma após a outra, controlada por um ROTEADOR. Essa é a biblioteca [navigation-compose] do [Jetpack], o equivalente do pacote [go_router] do [Flutter].

5.1. Exemplo 17: o roteador

O roteador associa uma ROTA a cada tela e gerencia uma PILHA de telas: uma tela é empilhada ([navigate]) e o botão Voltar do celular a desempilha ([popBackStack]). As rotas do exemplo:

// =========================================================================
// ex17/Routes.kt - as ROTAS do aplicativo
// -------------------------------------------------------------------------
// Um aplicativo tem várias telas ("páginas"). O ROTEADOR associa uma
// ROTA a cada tela. A biblioteca Jetpack Navigation (navigation-
// compose) gerencia uma PILHA de telas: uma tela é empilhada (navigate), o
// botão Voltar do celular a desempilha (popBackStack).
// Uma rota é um objeto Kotlin, @Serializable:
//   - um "object" para uma tela sem parâmetros (Home);
//   - uma "data class" para uma tela com parâmetros: DoctorDetail(id = 2).
// O tipo dos parâmetros é verificado em tempo de compilação: DoctorDetail("2")
// seria rejeitado. (O Navigation pode armazenar esses objetos na pilha, daí
// @Serializable.)
// Cada tela também pode ter um ENDEREÇO, um "deep link"
// como app://examples/doctors/2: é o que há de mais próximo,
// no Android, dos endereços web (cf. Ex17Activity.kt).
// =========================================================================
package fr.stahe.examples.ex17

import kotlinx.serialization.Serializable

@Serializable
object Home

@Serializable
object DoctorList

// um parâmetro de rota
@Serializable
data class DoctorDetail(val id: Int)

// um parâmetro OPCIONAL (com valor padrão): ?q=... no endereço
@Serializable
data class Search(val q: String = "")

@Serializable
object About

// um endereço antigo, que REDIRECIONA para a lista de médicos
@Serializable
object Physicians

// a tela dos endereços desconhecidos
@Serializable
data class NotFoundPage(val address: String)

// o início de todos os endereços deste exemplo
const val BASE = "app://examples"
  • linhas 23–30: uma rota é um objeto [Kotlin] [@Serializable]: um [object] para uma tela sem parâmetros; uma [data class] para uma tela com parâmetros: [DoctorDetail(id = 2)]. O tipo dos parâmetros é verificado em tempo de compilação ([DoctorDetail("2")] seria rejeitado); [@Serializable]: o [Navigation] sabe armazenar esses objetos na pilha e restaurá-los se a activity for recriada;
  • linha 34: um parâmetro opcional com valor padrão;
  • linha 48: cada tela pode ter um ENDEREÇO, um “deep link” da forma [app://examples/doctors/2]: é o que há de mais próximo, no [Android], dos endereços web.

Dados “fixos no código”, para evitar a dependência de um servidor:

// ex17/Data.kt - dados "fixos no código", para não depender de um servidor neste exemplo
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"),
)

O grafo de navegação: uma entrada por rota e a tela a exibir:

// =========================================================================
// ex17/Ex17Activity.kt - o NavHost: as rotas e suas telas
// -------------------------------------------------------------------------
//   - rememberNavController(): o controlador de navegação (a pilha);
//   - NavHost(nav, startDestination = Home) { ... }: a tela da
//     rota atual. O bloco descreve o GRAFO de navegação: uma entrada
//     composable<Route> { ... } por rota;
//   - entry.toRoute<DoctorDetail>(): o objeto de rota da tela, com
//     seus parâmetros;
//   - deepLinks: o endereço da tela. Graças ao intent filter da
//     activity (AndroidManifest.xml), um endereço app://examples/...
//     pode até ser aberto de fora do aplicativo:
//         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: a tela do médico é EMPILHADA sobre a lista
                DoctorListPage(onView = { id -> nav.navigate(DoctorDetail(id)) })
            }
            // app://examples/doctors/2: o parâmetro id é extraído do endereço
            composable<DoctorDetail>(deepLinks = listOf(navDeepLink<DoctorDetail>(basePath = "$BASE/doctors"))) { entry ->
                val route = entry.toRoute<DoctorDetail>()
                DoctorDetailPage(
                    id = route.id,
                    // popBackStack: desempilhando a tela (como o botão Voltar); se
                    // não houver nada abaixo (tela aberta por um endereço), vai para a lista
                    onBack = { if (!nav.popBackStack()) nav.navigate(DoctorList) },
                    // SUBSTITUINDO a tela atual (sem empilhar): o médico atual
                    // é desempilhado (inclusive) antes de empilhar o próximo
                    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() }
            // um REDIRECIONAMENTO: a tela não exibe nada, ela substitui imediatamente
            // sua própria rota por outra
            composable<Physicians> {
                LaunchedEffect(Unit) {
                    nav.navigate(DoctorList) { popUpTo<Physicians> { inclusive = true } }
                }
            }
            composable<NotFoundPage> { entry ->
                NotFoundScreen(address = entry.toRoute<NotFoundPage>().address, onHome = { nav.goTo(Home) })
            }
        }
    }
}
  • linha 34: [import ... as NotFoundScreen]: um alias, porque a função de tela [NotFoundPage] tem o mesmo nome que a rota [NotFoundPage];
  • linhas 46–48: [rememberNavController()]: o controlador de navegação (a pilha); [NavHost(nav, startDestination = Home)] exibe a tela da rota atual;
  • linhas 49–54: uma entrada [composable<Route>] por rota, com seu endereço ([deepLinks]). As telas não conhecem o roteador: elas recebem FUNÇÕES para navegar ([onLink], [onView]...);
  • linhas 57–58: [entry.toRoute<DoctorDetail>()]: o objeto da rota, com seus parâmetros. Com [navDeepLink<DoctorDetail>(basePath = ...)], o parâmetro [id] é obtido do endereço ([.../doctors/2]);
  • linha 63: [popBackStack()] desempilha a tela, como o botão Voltar, e retorna [false] se não houver nada abaixo dela (tela aberta por um endereço);
  • linhas 66–67: SUBSTITUIR a tela atual: o médico atual ([popUpTo<DoctorDetail> [ inclusive = true ]]) é desempilhado antes que o próximo seja empilhado;
  • linhas 78–80: um REDIRECIONAMENTO: a tela não exibe nada; ela substitui imediatamente sua rota por outra. A navegação é um “efeito” ([LaunchedEffect]): nunca se navega DURANTE a exibição.

O “shell” do aplicativo: a barra superior, a barra de abas inferior, típica de um dispositivo móvel, e, entre as duas, a tela que mostra a rota atual:

// =========================================================================
// ex17/Shell.kt - o "shell" do aplicativo
// -------------------------------------------------------------------------
// A barra superior, a barra de navegação inferior e, entre as duas,
// a tela da rota atual (content: o NavHost, cf. Ex17Activity.kt).
//   - nav.currentBackStackEntryAsState(): a tela no TOPO da pilha,
//     um estado observado (o shell é recomposto a cada navegação);
//   - destination.hasRoute<DoctorList>(): a tela é a desta
//     rota?; entry.toRoute<DoctorDetail>(): o objeto de rota e
//     seus parâmetros;
//   - navigate(route) { ... }: ir para uma rota; as opções do bloco
//     dizem o que fazer com a pilha (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

// uma aba: a rota para a qual ela leva, seu rótulo, seu ícone e o teste que
// diz se ela está ativa para uma dada tela
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>() },
    // a aba Doctors continua ativa na tela de um 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>() },
)

// o endereço da tela atual, para exibi-lo
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 -> "?"
    }
}

// indo para uma aba: a pilha é SUBSTITUÍDA pela dessa aba
fun NavHostController.goTo(route: Any) {
    navigate(route) {
        // tudo é desempilhado, até a primeira tela (excluída)...
        popUpTo(graph.findStartDestination().id)
        // ... e a mesma tela não é empilhada duas vezes
        launchSingleTop = true
    }
}

// seguindo um LINK (um endereço); um endereço desconhecido leva 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: a barra de abas inferior, típica de um celular
        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() }
        }
    }
}
  • linhas 55–62: as abas. [hasRoute<DoctorList>()]: esta é a tela dessa rota? A aba “Doctors” permanece ativa na tela de um médico;
  • linhas 66–75: o endereço da tela atual, para exibi-lo;
  • linhas 80–85: ir para uma aba: a pilha é SUBSTITUÍDA ([popUpTo] é a primeira tela), e a mesma tela ([launchSingleTop]) não é empilhada duas vezes;
  • linhas 90–94: seguir um endereço: [navigate(Uri)]; um endereço desconhecido lança uma exceção: a tela “Page not found” é então exibida;
  • linhas 100–101: [currentBackStackEntryAsState()]: a tela NO TOPO da pilha, um estado observado: o shell é reconstruído a cada navegação;
  • linhas 106–112: a barra de abas ([NavigationBar]).

As telas:

// =========================================================================
// ex17/pages/Pages.kt - as telas do exemplo 17
// -------------------------------------------------------------------------
// As telas não conhecem o roteador: elas recebem seus parâmetros
// (id, q...) e FUNÇÕES para navegar (onView, onBack...). É o
// NavHost (Ex17Activity.kt) que liga essas funções às rotas. Uma tela
// continua sendo, assim, um componente comum, fácil de exibir isoladamente (em uma
// preview do Android Studio, em um teste).
// =========================================================================
@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))
        // links para endereços específicos
        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) },
                // o médico é EMPILHADO; o botão Voltar retorna para cá
                modifier = Modifier.clickable { onView(d.id) },
            )
        }
    }
}

// uma página com parâmetro: o roteador passa a ela id, um Int
@Composable
fun DoctorDetailPage(id: Int, onBack: () -> Unit, onNext: (Int) -> Unit) {
    // find: o primeiro médico correspondente, ou 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") }
        }
    }
}

// =========================================================================
// uma página conduzida por sua rota: Search(q = "pediatrician"). Pesquisar
// significa IR para a rota Search(q = <input>): a página exibe o que
// a rota diz, e nada mais (o botão Voltar retorna à pesquisa
// 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()) }
    // o campo começa com o valor da rota; rememberSaveable(q):
    // se a rota mudar (botão Voltar), o campo recomeça a partir do novo 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,
            // a tecla "search" do 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") }
    }
}
  • linha 73: [Modifier.clickable]: a linha inteira é um link;
  • linhas 108–113: uma página dirigida por sua rota: “Search” VAI para a rota [Search(q = input)]; a página exibe as informações da rota. [rememberSaveable(q)]: se a rota mudar (botão Voltar), o campo de entrada é redefinido para o novo valor.

Image

Image

Image

Image

Para que um endereço possa ser aberto de FORA do aplicativo (um link em um e-mail, outro aplicativo), a activity declara um intent filter no manifesto:

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>

Em seguida, é possível testá-lo em uma janela de comando do PC, com a ferramenta [adb] do SDK do [Android] (emulador iniciado):

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

O Exemplo 17 abre diretamente na tela do médico nº 2; “Back” leva então à lista ([popBackStack()] retornou [false]).

5.2. Exemplo 18: guards de navegação

Algumas telas são acessíveis apenas a um usuário autenticado ou a papéis específicos. O usuário autenticado, simulado aqui sem servidor, é armazenado em um único objeto:

// =========================================================================
// ex18/Session.kt - uma sessão SIMULADA (sem servidor)
// -------------------------------------------------------------------------
// O usuário logado precisa ser conhecido pelas TELAS (a barra superior,
// a agenda) e pelos GUARDS do roteador. Ele é armazenado em um objeto
// ÚNICO (object: uma classe que tem apenas uma instância, criada no primeiro uso):
//   - uma propriedade de estado, observada pelo Compose (mutableStateOf): qualquer
//     componente que a leia é recomposto quando ela muda;
//   - funções para modificá-la.
// (O exemplo 23 fará a mesma coisa com um 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)

// três contas "fixas no código" (senha = login)
private val accounts = mapOf("admin" to Role.ADMIN, "pelissier" to Role.DOCTOR, "martin" to Role.USER)

object Session {
    // o estado: null, ninguém está logado. private set: modificável apenas aqui
    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
    }
}
  • Linhas 25–26: [object]: uma classe com uma única instância, criada no primeiro uso; sua propriedade [user] é um estado observado: qualquer componente que a leia é recomposto quando ela muda.

Rotas e guards:

// =========================================================================
// ex18/Routes.kt - rotas PROTEGIDAS por guards
// -------------------------------------------------------------------------
// Um GUARD é uma função que recebe o usuário logado (ou null) e
// retorna:
//   - null: a tela pode ser exibida;
//   - uma rota: a tela é SUBSTITUÍDA por essa rota (um redirecionamento).
// O componente Protected(...) aplica os guards de uma tela. Como ele LÊ
// o usuário da sessão (um estado observado), é reavaliado a cada
// login ou logout: uma tela que deixou de ser permitida é abandonada.
//
// É o equivalente, no lado do cliente, dos guards do NestJS (JwtAuthGuard,
// RolesGuard) - com uma diferença FUNDAMENTAL: um guard de cliente é
// apenas uma comodidade. O aplicativo está nas mãos do usuário, que
// pode modificá-lo à vontade. A proteção real dos dados continua sendo
// a do SERVIDOR (cf. capítulo sobre a caixa-preta).
// =========================================================================
package fr.stahe.examples.ex18

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

// denied: deixado pelo guard requireRole quando o papel não é adequado
@Serializable
data class Home(val denied: String? = null)

// redirect: o endereço da tela que o usuário queria abrir
@Serializable
data class Login(val redirect: String? = null)

@Serializable
object Schedule

@Serializable
object Administration

const val BASE = "app://examples18"

typealias Guard = (User?) -> Any?

// o guard "login obrigatório": não logado -> para a página de login,
// lembrando o endereço da tela solicitada
fun requireLogin(address: String): Guard = { u -> if (u == null) Login(redirect = address) else null }

// o guard "papel obrigatório": logado, mas sem o papel certo -> de volta à
// página inicial, com um motivo
fun requireRole(address: String, vararg roles: Role): Guard = { u ->
    if (u == null || u.role !in roles) Home(denied = address) else null
}

// os guards, em ordem: vale o primeiro que retorna uma rota
@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 é um "efeito": não navegamos DURANTE a exibição
        LaunchedEffect(redirection) {
            val here = nav.currentBackStackEntry?.destination?.id ?: return@LaunchedEffect
            // a tela negada é substituída (inclusive) pelo redirecionamento
            nav.navigate(redirection) { popUpTo(here) { inclusive = true } }
        }
    }
}
  • linha 41: um GUARD é uma função que recebe o usuário (ou [null]) como argumento e retorna [null] (a tela pode ser exibida) ou uma ROTA (a tela é substituída por essa rota);
  • linhas 45–50: duas funções de guard: “login obrigatório” redireciona para a tela de login mantendo o endereço solicitado; “papel obrigatório” redireciona para a tela de boas-vindas com um motivo;
  • linhas 55–64: [Protected] aplica os guards a uma tela: [firstNotNullOfOrNull], o primeiro resultado que não é [null]. Como ele LÊ a sessão, é reavaliado a cada login ou logout: uma tela que deixa de ser permitida é abandonada.

Este é o equivalente, no cliente, das verificações do [NestJS] ([JwtAuthGuard], [RolesGuard]), com uma diferença: uma verificação no cliente é apenas uma comodidade. O aplicativo está nas mãos do usuário; a verdadeira proteção dos dados continua sendo a fornecida pelo SERVIDOR.

// =========================================================================
// ex18/Ex18Activity.kt - o grafo de navegação, com seus guards
// -------------------------------------------------------------------------
// As telas protegidas são envolvidas por Protected(nav, guards...): seus
// guards são avaliados quando a tela abre... e de novo a cada
// mudança da sessão.
// Depois de fazer login, o usuário é enviado de volta à tela que queria
// abrir (seu endereço, armazenado pelo guard em Login.redirect), ou à
// página inicial.
// =========================================================================
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 ->
                        // somente um endereço DESTE aplicativo é aceito
                        // a pilha é esvaziada (popUpTo o grafo inteiro): a página de login
                        // não permanece nela, o botão Voltar não a 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()
                }
            }
        }
    }
}
  • linhas 44–52: após o login, o programa vai para o endereço armazenado pelo guard (somente se for um endereço DESTE aplicativo); caso contrário, vai para a página inicial; [navOptions { popUpTo(nav.graph.id) [ inclusive = true ] }] limpa a pilha: o botão Voltar não reabrirá a tela de login;
  • linhas 58–62: as telas protegidas, envolvidas por [Protected].

O shell e as telas:

// =========================================================================
// ex18/Shell.kt - os links e o usuário logado
// -------------------------------------------------------------------------
// A barra superior lê Session.user: ela é recomposta a cada
// login e logout.
// =========================================================================
@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

    // um link: em negrito se designa a tela exibida
    @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 - as telas do exemplo 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.")
}

// =========================================================================
// o login. Após um login bem-sucedido, onLoggedIn recebe o endereço da
// tela que o usuário queria abrir (parâmetro redirect deixado pelo guard),
// ou 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

À esquerda, “Administration” sem estar autenticado: o guard levou à tela de login; no meio, autenticado como [martin] (papel USER): retorno à página inicial, com o motivo; à direita, autenticado como [admin].