Nav3 示例集：面向 Jetpack Navigation 3 的实用导航用例与模式

Nav3 官方示例仓库，提供模块化、可复用的导航用例与模式，适合作为迁移、集成与学习 Jetpack Navigation 3 的参考

GitHub android/nav3-recipes 更新 2025-12-07 分支 main 星标 986 分叉 89

Android Jetpack Navigation 3 Jetpack Compose Hilt Koin 示例/样例 Apache-2.0

💡 深度解析

项目如何保证导航状态在配置变更和进程死亡时持久化与恢复？在迁移到生产时需要注意哪些实现细节？

核心分析 ¶

问题核心：如何在配置变更和进程死亡后可靠恢复导航栈与 UI 状态？仓库通过 saveable back stack 示例给出实现模式，但迁移到生产需谨慎处理序列化与版本问题。

saveable back stack：利用 Nav3 的持久化能力让 back stack 在系统恢复时重建。
SavedStateHandle：在 ViewModel 层保存关键状态，确保在重建后还能恢复 UI。
合成栈与初始化顺序：重建合成返回栈时需要按原始入栈顺序恢复，以保证历史一致性。
数据可序列化性：所有保存到 back stack 或 SavedStateHandle 的字段必须可通过 Bundle/Parcel（或自定义序列化）存储。

重要提示：未序列化的数据或 API 变动是导致恢复失败的主要风险源，务必在移植前做全面检查与测试。

总结：仓库提供的 saveable back stack 示例是实现恢复的良好蓝图，但生产采用时需关注序列化、版本锁定与恢复测试，确保鲁棒性。

89.0%

仓库如何实现从 Intent 解析 deep link 并重建合成返回栈（synthetic back stack）以保证 Up/Back 行为一致？

问题核心：Deep link 直接打开深层目的地时，用户期望按 Up/Back 能返回到合理的上层页面。仓库的 advanced 示例通过“合成返回栈”来解决该问题。

重要提示：若直接复制示例代码到生产，请审查 ViewModel 作用域与入栈时机，错误的时机会导致 UI/状态不一致或重复请求。

总结：项目给出了从 Intent 到合成返回栈的端到端示例，是处理 deep link 场景的实用参考，但需要结合 App 的生命周期/作用域策略审慎移植。

88.0%

在仓库中，如何在不同 ViewModel 构造方式（viewModel(), hiltViewModel(), koinViewModel()）下安全地传递导航参数并返回结果？

问题核心：在不同的 ViewModel 构造方式下，如何确保导航参数正确注入且返回结果可被接收，且不会引发生命周期/作用域问题？

参数传递：把导航参数作为 entry 的属性或 navigation key 显式声明，ViewModel 在构造时从 entry 或 SavedStateHandle 中读取。
DI 与作用域对齐：
viewModel(): 默认与 Composable/Activity 的 NavBackStackEntry 作用域相关联。
hiltViewModel(): 需确保 Hilt 的导航组件或 Activity component 与 entry 的作用域匹配，避免跨 entry 复用错误的实例。
koinViewModel(): 类似地，需要配置正确的 Koin scope 并在 navigation module 中声明。
结果返回模式：
事件式：用一次性通道（SharedFlow/事件回调）返回结果，适合短期交互。
状态式：把结果写入 CompositionLocal / SavedStateHandle，使目标在被复用或恢复时可读取。

重要提示：错误的作用域对齐是常见坑，会导致参数为空、ViewModel 被复用或泄露。

总结：仓库展示了三种构造方式下的参数注入与两种结果返回范式。移植时以作用域一致性和 SavedStateHandle 为基础，可显著降低问题发生概率。

88.0%