Skip to content

5. 导航

一个应用有多个屏幕。在 [Android] 中,配合 [Compose] 时,并不是每个屏幕打开一个 Activity:由单个 Activity 在路由器的控制下依次显示应用的各个屏幕。这就是 [Jetpack] 的 [navigation-compose] 库,相当于 [Flutter] 的 [go_router] 包。

5.1. 示例 17:路由器

路由器为每个屏幕关联一个路由,并管理一个屏幕栈:一个屏幕([navigate])被压入栈中,手机的返回按钮将它弹出([popBackStack])。示例中的路由:

// =========================================================================
// ex17/Routes.kt - 应用的路由
// -------------------------------------------------------------------------
// 一个应用有多个屏幕(“页面”)。路由器为每个屏幕关联一个
// 路由。Jetpack Navigation 库(navigation-
// compose)管理一个屏幕栈:屏幕被压入栈中(navigate),
// 手机的返回按钮将它弹出(popBackStack)。
// 路由是一个 Kotlin 对象,@Serializable:
//   - 没有参数的屏幕用“object”(Home);
//   - 带参数的屏幕用“data class”:DoctorDetail(id = 2)。
// 参数的类型在编译时检查:DoctorDetail("2")
// 会被拒绝。(Navigation 可以把这些对象存入栈中,因此需要
// @Serializable。)
// 每个屏幕还可以有一个地址,即“深层链接”,
// 例如 app://examples/doctors/2:在 Android 上,这是最接近
// 网址的东西(参见 Ex17Activity.kt)。
// =========================================================================
package fr.stahe.examples.ex17

import kotlinx.serialization.Serializable

@Serializable
object Home

@Serializable
object DoctorList

// 一个路由参数
@Serializable
data class DoctorDetail(val id: Int)

// 一个可选参数(带默认值):地址中的 ?q=...
@Serializable
data class Search(val q: String = "")

@Serializable
object About

// 一个旧地址,它会重定向到医生列表
@Serializable
object Physicians

// 未知地址的屏幕
@Serializable
data class NotFoundPage(val address: String)

// 本示例所有地址的开头部分
const val BASE = "app://examples"
  • 第 23–30 行:路由是一个 [Kotlin] [@Serializable] 对象:没有参数的屏幕用 [object];带参数的屏幕用 [data class]:[DoctorDetail(id = 2)]。参数的类型在编译时检查([DoctorDetail("2")] 会被拒绝);[@Serializable]:[Navigation] 知道如何把这些对象存入栈中,并在 Activity 被重新创建时恢复它们;
  • 第 34 行:一个带默认值的可选参数;
  • 第 48 行:每个屏幕都可以有一个地址,即形如 [app://examples/doctors/2] 的“深层链接”:在 [Android] 中,这是最接近网址的东西。

“硬编码”的数据,以避免依赖服务器:

// ex17/Data.kt - “硬编码”的数据,使本示例不依赖服务器
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"),
)

导航图:每个路由一个条目,以及要显示的屏幕:

// =========================================================================
// ex17/Ex17Activity.kt - NavHost:路由及其屏幕
// -------------------------------------------------------------------------
//   - rememberNavController():导航控制器(即栈);
//   - NavHost(nav, startDestination = Home) { ... }:当前路由的
//     屏幕。该代码块描述导航图:每个路由对应一个
//     composable<Route> { ... } 条目;
//   - entry.toRoute<DoctorDetail>():屏幕的路由对象,带有
//     它的参数;
//   - deepLinks:屏幕的地址。借助 Activity 的
//     意图过滤器(AndroidManifest.xml),app://examples/... 地址
//     甚至可以从应用外部打开:
//         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:医生的屏幕被压入列表之上
                DoctorListPage(onView = { id -> nav.navigate(DoctorDetail(id)) })
            }
            // app://examples/doctors/2:id 参数取自地址
            composable<DoctorDetail>(deepLinks = listOf(navDeepLink<DoctorDetail>(basePath = "$BASE/doctors"))) { entry ->
                val route = entry.toRoute<DoctorDetail>()
                DoctorDetailPage(
                    id = route.id,
                    // popBackStack:弹出屏幕(就像返回按钮);如果
                    // 下面没有屏幕(屏幕是通过地址打开的),则转到列表
                    onBack = { if (!nav.popBackStack()) nav.navigate(DoctorList) },
                    // 替换当前屏幕(不压栈):当前的医生
                    // 在压入下一个之前被弹出(inclusive)
                    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() }
            // 重定向:该屏幕什么也不显示,它立即用另一个路由
            // 替换自己的路由
            composable<Physicians> {
                LaunchedEffect(Unit) {
                    nav.navigate(DoctorList) { popUpTo<Physicians> { inclusive = true } }
                }
            }
            composable<NotFoundPage> { entry ->
                NotFoundScreen(address = entry.toRoute<NotFoundPage>().address, onHome = { nav.goTo(Home) })
            }
        }
    }
}
  • 第 34 行:[import ... as NotFoundScreen]:一个别名,因为屏幕函数 [NotFoundPage] 与路由 [NotFoundPage] 同名;
  • 第 46–48 行:[rememberNavController()]:导航控制器(即栈);[NavHost(nav, startDestination = Home)] 显示当前路由对应的屏幕;
  • 第 49–54 行:每个路由一个 [composable<Route>] 条目,带有它的地址([deepLinks])。屏幕并不知道路由器的存在:它们接收用于导航的函数([onLink]、[onView] 等);
  • 第 57–58 行:[entry.toRoute<DoctorDetail>()]:路由对象,带有它的参数。使用 [navDeepLink<DoctorDetail>(basePath = ...)] 时,参数 [id] 取自地址([.../doctors/2]);
  • 第 63 行:[popBackStack()] 弹出屏幕,就像返回按钮一样,如果它下面没有屏幕则返回 [false](屏幕是通过地址打开的);
  • 第 66–67 行:替换当前屏幕:当前的医生([popUpTo<DoctorDetail> [ inclusive = true ]])在压入下一个之前被弹出;
  • 第 78–80 行:重定向:该屏幕什么也不显示;它立即用另一个路由替换自己的路由。导航是一种“副作用”([LaunchedEffect]):绝不能在显示过程中进行导航。

应用的“外壳”:顶部栏、底部标签栏(移动设备的典型特征),以及两者之间显示当前路由的屏幕:

// =========================================================================
// ex17/Shell.kt - 应用的“外壳”
// -------------------------------------------------------------------------
// 顶部栏、底部导航栏,以及两者之间
// 当前路由的屏幕(content:NavHost,参见 Ex17Activity.kt)。
//   - nav.currentBackStackEntryAsState():栈顶的屏幕,
//     一个被观察的状态(每次导航时外壳都会重组);
//   - destination.hasRoute<DoctorList>():该屏幕是否是
//     这个路由的屏幕?;entry.toRoute<DoctorDetail>():路由对象及
//     它的参数;
//   - navigate(route) { ... }:转到某个路由;代码块中的选项
//     说明如何处理栈(参见 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

// 一个标签页:它通往的路由、它的标签、它的图标,以及用于
// 判断它对给定屏幕是否处于激活状态的测试
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>() },
    // 在医生的屏幕上,Doctors 标签页保持激活
    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>() },
)

// 当前屏幕的地址,用于显示
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 -> "?"
    }
}

// 转到某个标签页:栈被该标签页的栈替换
fun NavHostController.goTo(route: Any) {
    navigate(route) {
        // 一切都被弹出,直到第一个屏幕(不含)……
        popUpTo(graph.findStartDestination().id)
        // ……并且同一个屏幕不会被压入两次
        launchSingleTop = true
    }
}

// 跟随一个链接(一个地址);未知地址会通往 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:底部标签栏,移动端的典型特征
        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() }
        }
    }
}
  • 第 55–62 行:标签页。[hasRoute<DoctorList>()]:这是该路由的屏幕吗?在医生的屏幕上,“Doctors”标签页保持激活;
  • 第 66–75 行:当前屏幕的地址,用于显示;
  • 第 80–85 行:转到某个标签页:栈被替换([popUpTo] 是第一个屏幕),并且同一个屏幕([launchSingleTop])不会被两次压入栈中;
  • 第 90–94 行:跟随一个地址:[navigate(Uri)];未知地址会抛出异常:随后显示“Page not found”屏幕;
  • 第 100–101 行:[currentBackStackEntryAsState()]:栈顶的屏幕,一个被观察的状态:每次导航时外壳都会重建;
  • 第 106–112 行:标签栏([NavigationBar])。

各个屏幕:

// =========================================================================
// ex17/pages/Pages.kt - 示例 17 的屏幕
// -------------------------------------------------------------------------
// 屏幕并不知道路由器的存在:它们接收自己的参数
// (id、q 等)以及用于导航的函数(onView、onBack 等)。由
// NavHost(Ex17Activity.kt)把这些函数与路由连接起来。因此
// 屏幕仍然是一个普通组件,易于单独显示(在
// Android Studio 预览中,在测试中)。
// =========================================================================
@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))
        // 指向特定地址的链接
        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) },
                // 医生被压入栈中;返回按钮会回到这里
                modifier = Modifier.clickable { onView(d.id) },
            )
        }
    }
}

// 一个带参数的页面:路由器向它传递 id,一个 Int
@Composable
fun DoctorDetailPage(id: Int, onBack: () -> Unit, onNext: (Int) -> Unit) {
    // find:第一个匹配的医生,或 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") }
        }
    }
}

// =========================================================================
// 一个由其路由驱动的页面:Search(q = "pediatrician")。搜索
// 意味着转到路由 Search(q = <input>):页面显示
// 路由所说的内容,别无其他(返回按钮会回到上一次
// 搜索)。
// =========================================================================
@Composable
fun SearchPage(q: String, onSearch: (String) -> Unit) {
    TaskTitle("Search")
    val results = doctors.filter { "${it.firstName} ${it.lastName} ${it.specialty}".lowercase().contains(q.lowercase()) }
    // 输入框以路由的值作为起始;rememberSaveable(q):
    // 如果路由变化(返回按钮),输入框会从新的值重新开始
    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,
            // 键盘上的“搜索”键
            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") }
    }
}
  • 第 73 行:[Modifier.clickable]:整行都是一个链接;
  • 第 108–113 行:一个由其路由驱动的页面:“Search”转到路由 [Search(q = input)];该页面显示路由的信息。[rememberSaveable(q)]:如果路由变化(返回按钮),输入框会重置为新的值。

Image

Image

Image

Image

为了让地址能从应用外部打开(邮件中的链接、另一个应用),Activity 在清单中声明一个意图过滤器:

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>

然后你可以在 PC 的命令窗口中使用 [Android] SDK 的 [adb] 工具 (已启动模拟器)来测试它:

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

示例 17 直接打开 2 号医生的屏幕;此时“返回”会带你回到列表([popBackStack()] 返回了 [false])。

5.2. 示例 18:导航守卫

某些屏幕只有已登录的用户或特定角色才能访问。已登录的用户(这里在没有服务器的情况下模拟)存放在一个单独的对象中:

// =========================================================================
// ex18/Session.kt - 一个模拟的会话(没有服务器)
// -------------------------------------------------------------------------
// 已登录的用户必须为屏幕(顶部栏、
// 日程)和路由器的守卫所知。它存储在一个唯一的对象中
// (object:只有一个实例的类,在首次使用时创建):
//   - 一个状态属性,被 Compose 观察(mutableStateOf):任何
//     读取它的组件在它变化时都会被重组;
//   - 修改它的函数。
// (示例 23 将用真实的服务器做同样的事情。)
// =========================================================================
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)

// 三个“硬编码”的账户(密码 = 登录名)
private val accounts = mapOf("admin" to Role.ADMIN, "pelissier" to Role.DOCTOR, "martin" to Role.USER)

object Session {
    // 状态:null 表示没有人登录。private set:只能在这里修改
    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
    }
}
  • 第 25–26 行:[object]:只有一个实例的类,在首次使用时创建;它的属性 [user] 是一个被观察的状态:任何读取它的组件在它变化时都会被重组。

路由和守卫:

// =========================================================================
// ex18/Routes.kt - 由守卫保护的路由
// -------------------------------------------------------------------------
// 守卫是一个函数,它接收已登录的用户(或 null),并
// 返回:
//   - null:可以显示该屏幕;
//   - 一个路由:该屏幕被这个路由替换(重定向)。
// Protected(...) 组件为屏幕应用守卫。由于它读取
// 会话的用户(一个被观察的状态),因此每次
// 登录或退出时都会重新求值:不再被允许的屏幕会被退出。
//
// 这相当于 NestJS 守卫(JwtAuthGuard、
// RolesGuard)在客户端的对应物,但有一个根本的区别:客户端守卫
// 只是一种便利。应用掌握在用户手中,用户
// 可以随意修改它。数据真正的保护仍然
// 来自服务器(参见关于黑盒的章节)。
// =========================================================================
package fr.stahe.examples.ex18

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

// denied:当角色不符时,由 requireRole 守卫留下
@Serializable
data class Home(val denied: String? = null)

// redirect:用户原本想打开的屏幕的地址
@Serializable
data class Login(val redirect: String? = null)

@Serializable
object Schedule

@Serializable
object Administration

const val BASE = "app://examples18"

typealias Guard = (User?) -> Any?

// “需要登录”守卫:未登录 -> 转到登录页面,
// 并记住所请求屏幕的地址
fun requireLogin(address: String): Guard = { u -> if (u == null) Login(redirect = address) else null }

// “需要角色”守卫:已登录,但角色不对 -> 返回
// 主页,并附带原因
fun requireRole(address: String, vararg roles: Role): Guard = { u ->
    if (u == null || u.role !in roles) Home(denied = address) else null
}

// 这些守卫按顺序执行:第一个返回路由的守卫胜出
@Composable
fun Protected(nav: NavHostController, vararg guards: Guard, content: @Composable () -> Unit) {
    val redirection = guards.firstNotNullOfOrNull { guard -> guard(Session.user) }
    if (redirection == null) {
        content()
    } else {
        // 导航是一种“副作用”:我们不会在显示过程中进行导航
        LaunchedEffect(redirection) {
            val here = nav.currentBackStackEntry?.destination?.id ?: return@LaunchedEffect
            // 被拒绝的屏幕被重定向替换(inclusive)
            nav.navigate(redirection) { popUpTo(here) { inclusive = true } }
        }
    }
}
  • 第 41 行:守卫是一个函数,它以用户(或 [null])为参数,返回 [null](可以显示该屏幕)或一个路由(该屏幕被这个路由替换);
  • 第 45–50 行:两个守卫函数:“需要登录”会重定向到登录屏幕,同时保留所请求的地址;“需要角色”会重定向到欢迎屏幕,并附带原因;
  • 第 55–64 行:[Protected] 为一个屏幕应用这些守卫:[firstNotNullOfOrNull],第一个不是 [null] 的结果。由于它读取会话,因此每次登录或退出时都会重新求值:不再被允许的屏幕会被退出。

这相当于 [NestJS] 检查([JwtAuthGuard]、[RolesGuard])在客户端的对应物,但有一点区别:客户端检查仅仅是一种便利。应用掌握在用户手中;真正的数据保护仍然由服务器来提供。

// =========================================================================
// ex18/Ex18Activity.kt - 带有守卫的导航图
// -------------------------------------------------------------------------
// 受保护的屏幕由 Protected(nav, guards...) 包裹:它们的
// 守卫在屏幕打开时求值……并且在会话
// 每次变化时再次求值。
// 登录之后,用户会被送回他原本想
// 打开的屏幕(其地址由守卫存放在 Login.redirect 中),或送回
// 主页。
// =========================================================================
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 ->
                        // 只接受本应用的地址
                        // 栈被清空(popUpTo 整个导航图):登录页面
                        // 不会留在栈中,返回按钮不会重新打开它
                        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()
                }
            }
        }
    }
}
  • 第 44–52 行:登录之后,程序转到守卫所保存的地址(仅当它是本应用的地址时),否则转到主页;[navOptions { popUpTo(nav.graph.id) [ inclusive = true ] }] 清空栈:返回按钮不会重新打开登录屏幕;
  • 第 58–62 行:受保护的屏幕,由 [Protected] 包裹。

外壳和各个屏幕:

// =========================================================================
// ex18/Shell.kt - 链接和已登录的用户
// -------------------------------------------------------------------------
// 顶部栏读取 Session.user:每次
// 登录和退出时它都会被重组。
// =========================================================================
@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

    // 一个链接:如果它指向当前显示的屏幕,则加粗
    @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 - 示例 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.")
}

// =========================================================================
// 登录。登录成功之后,onLoggedIn 接收用户原本想打开的
// 屏幕的地址(由守卫留下的 redirect 参数),
// 或 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

左图:未登录时访问“Administration”:守卫将其引导到登录屏幕;中图:以 [martin](角色 USER)身份登录:返回主页,并附带原因;右图:以 [admin] 身份登录。