compose-navigation

用途

Compose Navigation 用于在 Jetpack Compose 应用中实现类型安全的导航，基于 Navigation Compose 库。当需要搭建导航、在屏幕之间传递参数、处理深链接、组织嵌套导航图、实现自适应导航或编写导航测试时，可使用该技能。

主要能力

• 类型安全路由：使用 @Serializable 数据类或对象定义路由，支持无参数、必填参数、可选参数和多参数屏幕。
• NavHost 与 NavController：创建 NavController 并在 NavHost 中声明各屏幕的 composable 目标。
• 参数处理：在 Composable 中通过 backStackEntry.toRoute() 获取参数，在 ViewModel 中通过 SavedStateHandle.toRoute<T>() 获取参数。
• 导航模式：支持前进导航、返回、弹出到指定目标、带选项导航（popUpTo、launchSingleTop、restoreState）以及底部导航模式。
• 深链接：通过 navDeepLink 定义深链接，并配置 AndroidManifest 的 intent-filter，以及为通知创建 PendingIntent。
• 嵌套导航：使用 navigation<Graph> 创建嵌套导航图，例如认证流程。
• 自适应导航：使用 NavigationSuiteScaffold 实现响应式导航（手机底部栏、平板侧边栏）。
• 测试：使用 navigation-testing 库和 TestNavHostController 验证起始目标和导航行为。

使用方式

1. 添加依赖：在 build.gradle.kts 中加入 navigation-compose 与 kotlinx-serialization-json，并启用 serialization 插件。
2. 定义路由：使用 @Serializable 标注 object 或 data class。
3. 创建 NavController：在 Composable 中调用 rememberNavController()。
4. 创建 NavHost：指定 startDestination，并为每个路由声明 composable<Route>。
5. 导航：调用 navController.navigate(Route(...))，可配合 popUpTo、launchSingleTop、restoreState 等选项。
6. 获取参数：在 Composable 中使用 backStackEntry.toRoute()，在 ViewModel 中使用 savedStateHandle.toRoute<T>()。
7. 深链接：在 composable 中传入 deepLinks 参数，并在 Manifest 中配置 intent-filter。
8. 测试：添加 navigation-testing 依赖，使用 TestNavHostController 和 createComposeRule 编写测试。

适用场景

• Android Jetpack Compose 应用需要多屏幕导航。
• 需要在屏幕之间传递参数（推荐只传 ID 或基本类型）。
• 需要处理深链接，例如从通知或外部链接跳转到指定页面。
• 需要组织嵌套导航图，例如登录/注册流程。
• 需要自适应导航布局，适配手机与平板。
• 需要为导航逻辑编写自动化测试。

限制与注意事项

• 不要将复杂对象作为导航参数传递，应只传递 ID 或基本类型，再在 ViewModel 中从仓库获取数据。
• 不要在 NavHost 内部创建 NavController。
• 不要在 LaunchedEffect 中无正确 key 的情况下执行导航。
• 为 PendingIntent 设置 FLAG_IMMUTABLE（Android 12+）。
• 避免使用基于字符串的路由（旧模式），推荐使用类型安全路由。
• 该技能的具体收费、价格、平台支持范围等事实暂未提供。