原生移动开发 / 系统课时

导航参数与类型安全

导航参数与类型安全

这一节解决 Compose 导航中最容易出错的参数传递:把必选参数、可选参数直接建模为 Kotlin 类型,并在目的地用同一类型读取。完成后,你不需要手拼路由字符串,也能让参数缺失和类型不匹配尽量在编码阶段暴露出来。

学习目标

  • 用 @Serializable 路由类型区分必选参数与可选参数
  • 使用 navigate() 和 toRoute() 发送、读取类型安全参数
  • 判断哪些数据适合放进路由,哪些数据应只传稳定 ID

用路由类型表达参数

类型安全导航的关键不是“给字符串加封装”,而是让一个可序列化类型同时描述目的地和参数。非空且没有默认值的属性就是必选参数;带默认值的可空属性可以作为可选参数。例如详情页必须知道用户 ID,但标签页可以不指定。

类型安全导航参数从路由对象到目的地的传递过程

这里的 userId 应代表稳定身份,而不是整份用户对象。把大型对象、数据库实体或可变业务状态塞进路由,会增加序列化负担,也容易让返回栈里的数据变旧。目的地拿到 ID 后,再从 Repository 或 ViewModel 读取最新数据通常更可靠。

准备类型安全导航

下面是 app/build.gradle.kts 的片段示例。Kotlin Serialization 插件版本应与项目 Kotlin 版本保持一致;示例使用 Navigation Compose 2.10.0。

kotlin
plugins {
    id("org.jetbrains.kotlin.plugin.serialization")
}

dependencies {
    implementation("androidx.navigation:navigation-compose:2.10.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
}

这段配置生效后,@Serializable 路由类型可以参与导航参数序列化。若项目在根构建脚本集中声明插件版本,模块中只需按现有方式应用插件,不要再重复声明版本。

发送并读取必选与可选参数

下面的 MainActivity.kt 是一个完整主示例。Profile.userId 没有默认值,因此构造路由时必须传入;tab 默认为 null,调用方可以省略。

kotlin
package com.example.navigationdemo

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.navigation.compose.NavHost
import androidx.navigation.compose.composable
import androidx.navigation.compose.rememberNavController
import androidx.navigation.toRoute
import kotlinx.serialization.Serializable

@Serializable
data object Home

@Serializable
data class Profile(
    val userId: Long,
    val tab: String? = null
)

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                App()
            }
        }
    }
}

@Composable
private fun App() {
    val navController = rememberNavController()

    NavHost(
        navController = navController,
        startDestination = Home
    ) {
        composable<Home> {
            Column(
                modifier = Modifier.fillMaxSize(),
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally
            ) {
                Button(onClick = {
                    // 只传必选参数,tab 使用默认值 null。
                    navController.navigate(Profile(userId = 42L))
                }) {
                    Text("打开默认资料页")
                }

                Button(onClick = {
                    navController.navigate(
                        Profile(userId = 42L, tab = "posts")
                    )
                }) {
                    Text("打开动态标签页")
                }
            }
        }

        composable<Profile> { backStackEntry ->
            // 读取时仍使用同一个路由类型,不手工解析字符串。
            val route = backStackEntry.toRoute<Profile>()

            Column(
                modifier = Modifier.fillMaxSize(),
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally
            ) {
                Text("userId=${route.userId}")
                Text("tab=${route.tab ?: "overview"}")
                Button(onClick = { navController.popBackStack() }) {
                    Text("返回")
                }
            }
        }
    }
}

预期结果

text
点击“打开默认资料页”:
userId=42
tab=overview

返回后点击“打开动态标签页”:
userId=42
tab=posts

实际页面没有固定的控制台输出;上面的文本对应界面可见内容。

处理参数边界

必选参数的优势是构造 Profile(...) 时就必须给出 userId,避免运行到目标页面才发现参数缺失。可选参数则应该提供明确默认值,让旧入口、深链或其他调用方在不关心该参数时仍能正常导航。

如果参数来自外部深链,还要把它视为不可信输入:类型安全能保证解析后的类型,却不能保证业务值一定有效。例如 userId=-1 仍然是合法的 Long,目的地或数据层仍需检查取值范围和资源是否存在。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

导航参数与类型安全

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通