用途:指导在 Jetpack Compose 中实现并迁移到 Jetpack Navigation 3,优先级 P1(HIGH)。
主要能力:Navigation 3 用状态驱动方式取代旧的 NavHost/NavController 模式。路由为 Kotlin 数据对象/类而非字符串;返回栈是普通的 mutableStateListOf<Any>;NavDisplay 依据 lambda 渲染当前路由。资料覆盖基础导航与参数、底部导航多返回栈、深链(基础与合成返回栈)、对话框与底部弹窗、条件导航(认证流程)、屏幕间返回结果、以及用 Hilt 或 Koin 的模块化导航。
使用方式:基础用法为 val backStack = remember { mutableStateListOf<Any>(RouteHome) },再调用 NavDisplay(backStack = backStack, onBack = { backStack.removeLastOrNull() }, entryProvider = { key -> when (key) { is RouteHome -> NavEntry(key) { HomeScreen(onNavigate = { backStack.add(it) }) } is RouteDetail -> NavEntry(key) { DetailScreen(key.id) } else -> error("Unknown route: $key") } })。从 Navigation 2 迁移的要点:用数据对象/类替换字符串路由;用 NavDisplay 替换 NavHost;用直接操作列表替换 NavController.navigate();用数据类属性替换 navArgument。
验证清单:路由为数据对象/类、无字符串路由;返回栈为 mutableStateListOf<Any>;NavDisplay 的 entryProvider 处理所有路由;./gradlew build 成功。
限制与反模式:不要使用字符串路由;新项目不要用 NavController;不要使用 remember { navController() },Navigation 3 不使用 NavController。迁移指南与代码配方见技能内 references/migration-guide.md 与 references/recipes.md。