Skip to content

5. Navigation

Eine Anwendung hat mehrere Bildschirme. Unter [Android] wird zusammen mit [Compose] nicht pro Bildschirm eine Activity geöffnet: Eine EINZIGE Activity zeigt nacheinander die Bildschirme der Anwendung an, gesteuert von einem ROUTER. Das ist die Bibliothek [navigation-compose] von [Jetpack], das Äquivalent des Pakets [go_router] für [Flutter].

5.1. Beispiel 17: Der Router

Der Router ordnet jedem Bildschirm eine ROUTE zu und verwaltet einen STAPEL von Bildschirmen: Ein Bildschirm wird auf den Stapel gelegt ([navigate]), und die Zurück-Taste des Smartphones nimmt ihn wieder herunter ([popBackStack]). Die Routen im Beispiel:

// =========================================================================
// ex17/Routes.kt - die ROUTEN der Anwendung
// -------------------------------------------------------------------------
// Eine Anwendung hat mehrere Bildschirme ("Seiten"). Der ROUTER ordnet jedem Bildschirm eine
// ROUTE zu. Die Bibliothek Jetpack Navigation (navigation-
// compose) verwaltet einen STAPEL von Bildschirmen: Ein Bildschirm wird aufgelegt (navigate), die
// Zurück-Taste des Smartphones nimmt ihn wieder ab (popBackStack).
// Eine Route ist ein Kotlin-Objekt, @Serializable:
//   - ein "object" für einen Bildschirm ohne Parameter (Home);
//   - eine "data class" für einen Bildschirm mit Parametern: DoctorDetail(id = 2).
// Der Typ der Parameter wird zur Compile-Zeit geprüft: DoctorDetail("2")
// würde abgelehnt. (Navigation kann diese Objekte im Stapel speichern, daher
// @Serializable.)
// Jeder Bildschirm kann auch eine ADRESSE haben, einen "Deep Link"
// wie app://examples/doctors/2: Das ist das, was Webadressen unter Android
// am nächsten kommt (vgl. Ex17Activity.kt).
// =========================================================================
package fr.stahe.examples.ex17

import kotlinx.serialization.Serializable

@Serializable
object Home

@Serializable
object DoctorList

// ein Routenparameter
@Serializable
data class DoctorDetail(val id: Int)

// ein OPTIONALER Parameter (mit Standardwert): ?q=... in der Adresse
@Serializable
data class Search(val q: String = "")

@Serializable
object About

// eine alte Adresse, die auf die Arztliste UMLEITET
@Serializable
object Physicians

// der Bildschirm für unbekannte Adressen
@Serializable
data class NotFoundPage(val address: String)

// der Anfang aller Adressen dieses Beispiels
const val BASE = "app://examples"
  • Zeilen 23–30: Eine Route ist ein [Kotlin]-Objekt [@Serializable]: ein [object] für einen Bildschirm ohne Parameter; eine [data class] für einen Bildschirm mit Parametern: [DoctorDetail(id = 2)]. Der Typ der Parameter wird zur Kompilierzeit geprüft ([DoctorDetail("2")] würde abgelehnt); [@Serializable]: [Navigation] weiß, wie diese Objekte auf dem Stapel gespeichert und wiederhergestellt werden, wenn die Activity neu erzeugt wird;
  • Zeile 34: ein optionaler Parameter mit Standardwert;
  • Zeile 48: Jeder Bildschirm kann eine ADRESSE haben, einen „Deep Link“ der Form [app://examples/doctors/2]: Das ist unter [Android] das, was Webadressen am nächsten kommt.

„Fest codierte“ Daten, um die Abhängigkeit von einem Server zu vermeiden:

// ex17/Data.kt - "fest codierte" Daten, um in diesem Beispiel nicht von einem Server abzuhängen
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"),
)

Der Navigationsgraph: ein Eintrag pro Route und der anzuzeigende Bildschirm:

// =========================================================================
// ex17/Ex17Activity.kt - der NavHost: die Routen und ihre Bildschirme
// -------------------------------------------------------------------------
//   - rememberNavController(): der Navigations-Controller (der Stapel);
//   - NavHost(nav, startDestination = Home) { ... }: der Bildschirm der
//     aktuellen Route. Der Block beschreibt den Navigations-GRAPHEN: ein
//     Eintrag composable<Route> { ... } pro Route;
//   - entry.toRoute<DoctorDetail>(): das Routenobjekt des Bildschirms, mit
//     seinen Parametern;
//   - deepLinks: die Adresse des Bildschirms. Dank des Intent-Filters der
//     Activity (AndroidManifest.xml) kann eine Adresse app://examples/...
//     sogar von außerhalb der Anwendung geöffnet werden:
//         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: Der Bildschirm des Arztes wird oben auf die Liste GELEGT
                DoctorListPage(onView = { id -> nav.navigate(DoctorDetail(id)) })
            }
            // app://examples/doctors/2: Der Parameter id wird der Adresse entnommen
            composable<DoctorDetail>(deepLinks = listOf(navDeepLink<DoctorDetail>(basePath = "$BASE/doctors"))) { entry ->
                val route = entry.toRoute<DoctorDetail>()
                DoctorDetailPage(
                    id = route.id,
                    // popBackStack: den Bildschirm abnehmen (wie die Zurück-Taste); wenn
                    // darunter nichts liegt (durch eine Adresse geöffneter Bildschirm), zur Liste wechseln
                    onBack = { if (!nav.popBackStack()) nav.navigate(DoctorList) },
                    // den aktuellen Bildschirm ERSETZEN (kein Auflegen): Der aktuelle Arzt
                    // wird (inklusive) abgenommen, bevor der nächste aufgelegt wird
                    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() }
            // eine UMLEITUNG: Der Bildschirm zeigt nichts an, er ersetzt sofort
            // seine eigene Route durch eine andere
            composable<Physicians> {
                LaunchedEffect(Unit) {
                    nav.navigate(DoctorList) { popUpTo<Physicians> { inclusive = true } }
                }
            }
            composable<NotFoundPage> { entry ->
                NotFoundScreen(address = entry.toRoute<NotFoundPage>().address, onHome = { nav.goTo(Home) })
            }
        }
    }
}
  • Zeile 34: [import ... as NotFoundScreen]: ein Alias, weil die Bildschirmfunktion [NotFoundPage] denselben Namen hat wie die Route [NotFoundPage];
  • Zeilen 46–48: [rememberNavController()]: der Navigationscontroller (der Stapel); [NavHost(nav, startDestination = Home)] zeigt den Bildschirm der aktuellen Route an;
  • Zeilen 49–54: ein Eintrag [composable<Route>] pro Route, mit ihrer Adresse ([deepLinks]). Die Bildschirme kennen den Router nicht: Sie erhalten FUNKTIONEN zum Navigieren ([onLink], [onView] ...);
  • Zeilen 57–58: [entry.toRoute<DoctorDetail>()]: das Routenobjekt mit seinen Parametern. Mit [navDeepLink<DoctorDetail>(basePath = ...)] wird der Parameter [id] der Adresse entnommen ([.../doctors/2]);
  • Zeile 63: [popBackStack()] nimmt den Bildschirm vom Stapel, wie die Zurück-Taste, und gibt [false] zurück, wenn darunter nichts liegt (Bildschirm, der über eine Adresse geöffnet wurde);
  • Zeilen 66–67: den aktuellen Bildschirm ERSETZEN: Der aktuelle Arzt wird vom Stapel genommen ([popUpTo<DoctorDetail> [ inclusive = true ]]), bevor der nächste daraufgelegt wird;
  • Zeilen 78–80: eine WEITERLEITUNG: Der Bildschirm zeigt nichts an; er ersetzt seine Route sofort durch eine andere. Die Navigation ist ein „Effekt“ ([LaunchedEffect]): Man navigiert nie WÄHREND der Anzeige.

Die „Hülle“ der App: die obere Leiste, die untere Tab-Leiste – typisch für ein Mobilgerät – und dazwischen der Bildschirm der aktuellen Route:

// =========================================================================
// ex17/Shell.kt - die "Shell" der Anwendung
// -------------------------------------------------------------------------
// Die Top-Bar, die untere Navigationsleiste und dazwischen
// der Bildschirm der aktuellen Route (content: der NavHost, vgl. Ex17Activity.kt).
//   - nav.currentBackStackEntryAsState(): der Bildschirm OBEN auf dem Stapel,
//     ein beobachteter Zustand (die Shell wird bei jeder Navigation rekomponiert);
//   - destination.hasRoute<DoctorList>(): ist der Bildschirm der
//     dieser Route?; entry.toRoute<DoctorDetail>(): das Routenobjekt und
//     seine Parameter;
//   - navigate(route) { ... }: zu einer Route wechseln; die Optionen des Blocks
//     sagen, was mit dem Stapel geschehen soll (vgl. 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

// ein Tab: die Route, zu der er führt, sein Label, sein Icon und der Test, der
// angibt, ob er für einen bestimmten Bildschirm aktiv ist
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>() },
    // der Tab Doctors bleibt auf dem Bildschirm eines Arztes aktiv
    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>() },
)

// die Adresse des aktuellen Bildschirms, um sie anzuzeigen
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 -> "?"
    }
}

// zu einem Tab wechseln: Der Stapel wird durch den dieses Tabs ERSETZT
fun NavHostController.goTo(route: Any) {
    navigate(route) {
        // alles wird abgenommen, bis zum ersten Bildschirm (ausgenommen) ...
        popUpTo(graph.findStartDestination().id)
        // ... und derselbe Bildschirm wird nicht zweimal aufgelegt
        launchSingleTop = true
    }
}

// einem LINK (einer Adresse) folgen; eine unbekannte Adresse führt zu 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: die untere Tab-Leiste, typisch für ein Smartphone
        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() }
        }
    }
}
  • Zeilen 55–62: die Tabs. [hasRoute<DoctorList>()]: Ist das der Bildschirm dieser Route? Der Tab „Doctors“ bleibt auf dem Bildschirm eines Arztes aktiv;
  • Zeilen 66–75: die Adresse des aktuellen Bildschirms, um sie anzuzeigen;
  • Zeilen 80–85: Zu einem Tab wechseln: Der Stapel wird ERSETZT ([popUpTo] ist der erste Bildschirm), und derselbe Bildschirm ([launchSingleTop]) wird nicht zweimal auf den Stapel gelegt;
  • Zeilen 90–94: einer Adresse folgen: [navigate(Uri)]; eine unbekannte Adresse löst eine Ausnahme aus: Dann wird der Bildschirm „Seite nicht gefunden“ angezeigt;
  • Zeilen 100–101: [currentBackStackEntryAsState()]: der Bildschirm OBEN auf dem Stapel, ein beobachteter Zustand: Die Hülle wird bei jeder Navigation neu aufgebaut;
  • Zeilen 106–112: die Tab-Leiste ([NavigationBar]).

Die Bildschirme:

// =========================================================================
// ex17/pages/Pages.kt - die Bildschirme von Beispiel 17
// -------------------------------------------------------------------------
// Die Bildschirme kennen den Router nicht: Sie erhalten ihre Parameter
// (id, q ...) und FUNKTIONEN zum Navigieren (onView, onBack ...). Der
// NavHost (Ex17Activity.kt) verknüpft diese Funktionen mit den Routen. Ein Bildschirm
// bleibt so eine gewöhnliche Komponente, die sich leicht für sich allein anzeigen lässt (in einer
// Android-Studio-Vorschau, in einem Test).
// =========================================================================
@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 zu bestimmten Adressen
        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) },
                // der Arzt wird AUFGELEGT; die Zurück-Taste führt hierher zurück
                modifier = Modifier.clickable { onView(d.id) },
            )
        }
    }
}

// eine Seite mit einem Parameter: Der Router übergibt ihr id, einen Int
@Composable
fun DoctorDetailPage(id: Int, onBack: () -> Unit, onNext: (Int) -> Unit) {
    // find: der erste passende Arzt oder 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") }
        }
    }
}

// =========================================================================
// eine von ihrer Route gesteuerte Seite: Search(q = "pediatrician"). Suchen
// bedeutet, zur Route Search(q = <Eingabe>) ZU WECHSELN: Die Seite zeigt an, was
// die Route sagt, und nichts anderes (die Zurück-Taste führt zur vorherigen
// Suche).
// =========================================================================
@Composable
fun SearchPage(q: String, onSearch: (String) -> Unit) {
    TaskTitle("Search")
    val results = doctors.filter { "${it.firstName} ${it.lastName} ${it.specialty}".lowercase().contains(q.lowercase()) }
    // die Eingabe beginnt mit dem Wert der Route; rememberSaveable(q):
    // Wenn sich die Route ändert (Zurück-Taste), beginnt die Eingabe erneut mit dem neuen Wert
    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,
            // die Taste "Suchen" der Tastatur
            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") }
    }
}
  • Zeile 73: [Modifier.clickable]: Die gesamte Zeile ist ein Link;
  • Zeilen 108–113: eine von ihrer Route gesteuerte Seite: „Search“ GEHT zur Route [Search(q = input)]; die Seite zeigt die Routeninformationen an. [rememberSaveable(q)]: Wenn sich die Route ändert (Zurück-Taste), wird die Eingabe auf den neuen Wert zurückgesetzt.

Image

Image

Image

Image

Damit eine Adresse von AUSSERHALB der App geöffnet werden kann (ein Link in einer E-Mail, eine andere App), deklariert die Activity im Manifest einen Intent-Filter:

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>

Sie können dies dann in einem Befehlsfenster auf dem PC mit dem Werkzeug [adb] aus dem [Android]-SDK testen (Emulator gestartet):

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

Beispiel 17 öffnet sich direkt auf dem Bildschirm von Arzt Nr. 2; „Zurück“ führt dann zur Liste ([popBackStack()] hat [false] zurückgegeben).

5.2. Beispiel 18: Navigations-Guards

Bestimmte Bildschirme sind nur für einen angemeldeten Benutzer oder für bestimmte Rollen zugänglich. Der angemeldete Benutzer – hier ohne Server simuliert – wird in einem einzigen Objekt gespeichert:

// =========================================================================
// ex18/Session.kt - eine SIMULIERTE Sitzung (ohne Server)
// -------------------------------------------------------------------------
// Der angemeldete Benutzer muss den BILDSCHIRMEN (die Top-Bar,
// der Terminkalender) und den GUARDS des Routers bekannt sein. Er wird in einem EINZIGEN Objekt
// gespeichert (object: eine Klasse, die nur eine Instanz hat, bei der ersten Verwendung erzeugt):
//   - eine Zustandseigenschaft, von Compose beobachtet (mutableStateOf): Jede
//     Komponente, die sie liest, wird rekomponiert, wenn sie sich ändert;
//   - Funktionen, um sie zu ändern.
// (Beispiel 23 macht dasselbe mit einem echten Server.)
// =========================================================================
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)

// drei "fest codierte" Konten (Passwort = Login)
private val accounts = mapOf("admin" to Role.ADMIN, "pelissier" to Role.DOCTOR, "martin" to Role.USER)

object Session {
    // der Zustand: null, niemand ist angemeldet. private set: nur hier änderbar
    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
    }
}
  • Zeilen 25–26: [object]: eine Klasse mit nur einer Instanz, die bei der ersten Verwendung erzeugt wird; ihre Eigenschaft [user] ist ein beobachteter Zustand: Jede Komponente, die sie liest, wird bei einer Änderung neu zusammengesetzt.

Routen und Guards:

// =========================================================================
// ex18/Routes.kt - durch Guards GESCHÜTZTE Routen
// -------------------------------------------------------------------------
// Ein GUARD ist eine Funktion, die den angemeldeten Benutzer (oder null) erhält und
// Folgendes zurückgibt:
//   - null: Der Bildschirm kann angezeigt werden;
//   - eine Route: Der Bildschirm wird durch diese Route ERSETZT (eine Umleitung).
// Die Komponente Protected(...) wendet die Guards eines Bildschirms an. Da sie den
// Benutzer der Sitzung LIEST (ein beobachteter Zustand), wird sie bei jeder
// An- oder Abmeldung neu ausgewertet: Ein nicht mehr erlaubter Bildschirm wird verlassen.
//
// Das ist das clientseitige Äquivalent der NestJS-Guards (JwtAuthGuard,
// RolesGuard) - mit einem GRUNDLEGENDEN Unterschied: Ein Client-Guard ist
// nur eine Annehmlichkeit. Die Anwendung ist in der Hand des Benutzers, der sie
// nach Belieben ändern kann. Der eigentliche Schutz der Daten bleibt
// der des SERVERS (vgl. Kapitel über die Blackbox).
// =========================================================================
package fr.stahe.examples.ex18

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

// denied: vom Guard requireRole gesetzt, wenn die Rolle nicht passt
@Serializable
data class Home(val denied: String? = null)

// redirect: die Adresse des Bildschirms, den der Benutzer öffnen wollte
@Serializable
data class Login(val redirect: String? = null)

@Serializable
object Schedule

@Serializable
object Administration

const val BASE = "app://examples18"

typealias Guard = (User?) -> Any?

// der Guard "Anmeldung erforderlich": nicht angemeldet -> zur Anmeldeseite,
// unter Merken der Adresse des angeforderten Bildschirms
fun requireLogin(address: String): Guard = { u -> if (u == null) Login(redirect = address) else null }

// der Guard "Rolle erforderlich": angemeldet, aber nicht mit der richtigen Rolle -> zurück zur
// Startseite, mit einer Begründung
fun requireRole(address: String, vararg roles: Role): Guard = { u ->
    if (u == null || u.role !in roles) Home(denied = address) else null
}

// die Guards der Reihe nach: Der erste, der eine Route zurückgibt, gewinnt
@Composable
fun Protected(nav: NavHostController, vararg guards: Guard, content: @Composable () -> Unit) {
    val redirection = guards.firstNotNullOfOrNull { guard -> guard(Session.user) }
    if (redirection == null) {
        content()
    } else {
        // Navigation ist ein "Effekt": Wir navigieren nicht WÄHREND der Anzeige
        LaunchedEffect(redirection) {
            val here = nav.currentBackStackEntry?.destination?.id ?: return@LaunchedEffect
            // der abgelehnte Bildschirm wird (inklusive) durch die Umleitung ersetzt
            nav.navigate(redirection) { popUpTo(here) { inclusive = true } }
        }
    }
}
  • Zeile 41: Ein GUARD ist eine Funktion, die den Benutzer (oder [null]) als Argument erhält und [null] zurückgibt (der Bildschirm darf angezeigt werden) oder eine ROUTE (der Bildschirm wird durch diese Route ersetzt);
  • Zeilen 45–50: zwei Guard-Funktionen: „Anmeldung erforderlich“ leitet unter Beibehaltung der angeforderten Adresse zum Anmeldebildschirm um; „Rolle erforderlich“ leitet mit einer Begründung zum Willkommensbildschirm um;
  • Zeilen 55–64: [Protected] wendet die Guards für einen Bildschirm an: [firstNotNullOfOrNull], das erste Ergebnis, das nicht [null] ist. Da es die Sitzung LIEST, wird es bei jeder An- oder Abmeldung neu ausgewertet: Ein Bildschirm, der nicht mehr erlaubt ist, wird verlassen.

Das ist das clientseitige Äquivalent der Prüfungen von [NestJS] ([JwtAuthGuard], [RolesGuard]), mit einem Unterschied: Eine clientseitige Prüfung ist lediglich eine Annehmlichkeit. Die Anwendung liegt in den Händen des Benutzers; der wirkliche Schutz der Daten bleibt der, den der SERVER bietet.

// =========================================================================
// ex18/Ex18Activity.kt - der Navigationsgraph mit seinen Guards
// -------------------------------------------------------------------------
// Die geschützten Bildschirme werden von Protected(nav, guards...) umhüllt: Ihre
// Guards werden ausgewertet, wenn der Bildschirm sich öffnet ... und erneut bei jeder
// Änderung der Sitzung.
// Nach der Anmeldung wird der Benutzer zu dem Bildschirm zurückgeschickt, den er
// öffnen wollte (seine Adresse, vom Guard in Login.redirect gespeichert), oder zur
// Startseite.
// =========================================================================
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 ->
                        // nur eine Adresse DIESER Anwendung wird akzeptiert
                        // der Stapel wird geleert (popUpTo den ganzen Graphen): Die Anmeldeseite
                        // bleibt nicht darin, Zurück öffnet sie nicht erneut
                        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()
                }
            }
        }
    }
}
  • Zeilen 44–52: Nach der Anmeldung geht das Programm zu der vom Guard gespeicherten Adresse (nur wenn es eine Adresse DIESER Anwendung ist), andernfalls zur Startseite; [navOptions { popUpTo(nav.graph.id) [ inclusive = true ] }] leert den Stapel: Die Zurück-Taste öffnet den Anmeldebildschirm nicht erneut;
  • Zeilen 58–62: die geschützten Bildschirme, von [Protected] umschlossen.

Die Hülle und die Bildschirme:

// =========================================================================
// ex18/Shell.kt - die Links und der angemeldete Benutzer
// -------------------------------------------------------------------------
// Die Top-Bar liest Session.user: Sie wird bei jeder
// An- und Abmeldung rekomponiert.
// =========================================================================
@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

    // ein Link: fett, wenn er den angezeigten Bildschirm bezeichnet
    @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 - die Bildschirme von Beispiel 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.")
}

// =========================================================================
// die Anmeldung. Nach erfolgreicher Anmeldung erhält onLoggedIn die Adresse
// des Bildschirms, den der Benutzer öffnen wollte (vom Guard hinterlassener redirect-Parameter),
// oder 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

Links „Administration“ ohne Anmeldung: Der Guard hat zum Anmeldebildschirm geführt; in der Mitte angemeldet als [martin] (Rolle USER): Rückkehr zur Startseite mit der Begründung; rechts angemeldet als [admin].