用途:在 Jetpack Compose 中用 Navigation 3 实现状态驱动导航。与 Navigation Compose 不同,它把导航建模为应用状态,而非依赖 NavController。
主要能力:用不可变可序列化对象定义导航键(navigation keys),以可变状态返回栈替代 NavController;提供 NavDisplay 承载目的地展示;支持前进、返回、替换当前屏、清空返回栈、弹回根等返回栈操作;通过入口装饰器(entry decorators)实现场景创建、已保存状态与 ViewModel 作用域;支持 Material Adaptive 单双窗格等自适应布局、深链、场景过渡动画、状态恢复与测试。
使用方式:添加 androidx.navigation3:navigation3-runtime 与 navigation3-ui,以及 lifecycle-viewmodel-navigation3 和 kotlinx-serialization-json,并启用 kotlin("plugin.serialization")。用 @Serializable 定义 Home、Profile、Settings 等键,用 mutableStateListOf 创建返回栈,调用 NavDisplay 并按 key 分支渲染。导航通过 backStack += Profile(id)、removeLast() 等状态操作完成。参数保存在导航键内,并建议只传 ID,再由 ViewModel 通过 savedStateHandle.toRoute<Profile>() 取回对象。ViewModel 作用域依赖 rememberSceneSetupNavEntryDecorator()、rememberSavedStateNavEntryDecorator()、rememberViewModelStoreNavEntryDecorator()。深链应解析为导航键,避免手写路由字符串。动画使用 transitionSpec,如 fadeIn() togetherWith fadeOut()。状态恢复使用 rememberSaveable(saver = navBackStackSaver())。
适用场景:需要状态驱动导航、返回栈可控、自适应多窗格布局、深链与状态恢复的 Compose 应用,以及从 Navigation Compose 迁移的项目。
限制:资料中未提供具体价格、收费、平台、效果或其他未提及细节;部分 API 仍处于 alpha,动画 API 可能变化;必须保证导航键可序列化,不要混用 Navigation Compose 与 Navigation 3 API。