返回栈还给你

先说清楚:Nav2 到底哪儿不行

推倒一套用了六年、无数项目在用的 API,理由必须硬。Nav2 的问题不是「不好用」,是三个结构性的死结。

死结一:一次只能画一个目的地

NavHost 的模型是:返回栈栈顶是谁,就画谁。一次一个。

这在手机上没问题。但上一章说了,Android 16 起大屏不能再锁方向 —— 平板、折叠屏、桌面窗口, 你必须做列表-详情双栏这种布局。而双栏意味着:要同时画两个目的地。

Nav2 做不到。所以过去大家是怎么绕的?

// Nav2 时代做双栏,你得在 NavHost 外面自己搭一套影子状态:
var selectedId by remember { mutableStateOf<String?>(null) }   // ← 第二份「返回栈」
val windowSize = calculateWindowSizeClass(activity)

if (windowSize.widthSizeClass == Expanded) {
    Row {
        ListPane(onSelect = { selectedId = it })              // 不走 navController
        DetailPane(selectedId)                                 // 也不走 navController
    }
} else {
    NavHost(...) { /* 走 navController */ }                   // 手机上才走导航
}
// 现在请回答:用户在双栏模式下按返回,该退到哪?
// 你得自己写。而且 selectedId 和 navController 的返回栈,是两份会打架的状态。

死结二:你不能自由操作那个栈

想「跳到登录页,并且清掉之前所有页面」?Nav2 里你得念这段咒:

navController.navigate("login") {
    popUpTo(navController.graph.startDestinationId) { inclusive = true }
    launchSingleTop = true
    restoreState = false
}
// 这四行到底会产生什么样的栈?说实话,你得跑一遍才知道。

为什么这么别扭?因为栈不是你的。你不能直接改它,只能通过一组「导航选项」描述你希望它变成什么样, 然后祈祷框架理解对了你的意思。

死结三:参数靠 Bundle 往返,类型是幻觉

"detail/{id}" 这种字符串路由,参数最终要序列化进 Bundle。Nav 2.8(2024 年 8 月) 用 @Serializable 的路由类型在表面上修好了这个 —— 但底下还是那套 Bundle 往返。

Nav3 的答案:把栈还给你

Navigation 3 的核心决定,一句话就能说完:

下面这个模拟器里,左边那个栈是真的一个数组。点按钮 push / pop,看它怎么变; 然后把窗口宽度拉到 600dp 以上,看那件 Nav2 做不到的事情发生:

代码长什么样

整个 Nav3 的 API 表面小得惊人。这就是全部:

// 1. 路由 key —— 就是普通的 Kotlin 类型,实现 NavKey
@Serializable data object Home : NavKey
@Serializable data class Detail(val id: String) : NavKey

@Composable
fun App() {
    // 2. 返回栈 —— 你持有它
    val backStack = rememberNavBackStack(Home)

    // 3. NavDisplay —— 它只负责「把当前该显示的东西画出来」
    NavDisplay(
        backStack = backStack,
        onBack = { count -> repeat(count) { backStack.removeLastOrNull() } },

        // 4. entryProvider —— key 到 UI 的映射表
        entryProvider = entryProvider {
            entry<Home> {
                HomeScreen(onOpen = { id -> backStack.add(Detail(id)) })   // ← 导航
            }
            entry<Detail> { key ->
                DetailScreen(key.id)      // ← key 就是那个 data class,类型是真的
            }
        },
    )
}

Scene:栈没变,只是画法变了

现在回到死结一。Nav3 怎么在不引入第二份状态的前提下做双栏?

答案是 SceneStrategy:它是一个「看一眼当前的返回栈,决定这一帧该怎么摆」的策略对象。

val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

NavDisplay(
    backStack = backStack,
    sceneStrategy = listDetailStrategy,        // ← 加这一行
    entryProvider = entryProvider {
        entry<Home>(metadata = ListDetailSceneStrategy.listPane()) { ... }
        entry<Detail>(metadata = ListDetailSceneStrategy.detailPane()) { ... }
    },
)

窗口够宽、并且栈顶恰好是「一个 listPane + 一个 detailPane」时,这个策略就把 两个 entry 一起渲染进一个双栏 Scene。窗口变窄,它自动塌回单栏。

三个 decorator:那些「消失了的」框架职责

等等 —— 如果返回栈只是个 List,那么谁来管每个页面的生命周期、状态保存、ViewModel 作用域?

Nav3 的回答很诚实:这些都是可插拔的装饰器,你自己列出来。

NavDisplay(
    backStack = backStack,
    entryDecorators = listOf(
        rememberSceneSetupNavEntryDecorator(),      // 生命周期:谁该是 RESUMED
        rememberSavedStateNavEntryDecorator(),      // 状态保存:进程死了能恢复
        rememberViewModelStoreNavEntryDecorator(),  // ViewModel 作用域:每个 entry 一个
    ),
    ...
)

为什么它反而更好模块化

entryProvider 看起来像个大而全的映射表,会不会所有 feature 都得挤在 :app 里注册?

不会。因为它就是个普通的 builder,你可以让每个 feature 模块自己贡献自己那几条:

// :feature:news 模块里,自己管自己的 entry
fun EntryProviderBuilder<NavKey>.newsEntries(backStack: NavBackStack) {
    entry<NewsList> { NewsListScreen(onOpen = { backStack.add(NewsDetail(it)) }) }
    entry<NewsDetail> { NewsDetailScreen(it.id) }
}

// :app 模块里,把各个 feature 的 entry 拼起来
entryProvider {
    newsEntries(backStack)        // 来自 :feature:news
    bookmarkEntries(backStack)    // 来自 :feature:bookmarks
    settingsEntries(backStack)    // 来自 :feature:settings
}

路由 key(那些 @Serializable 的 data class)放在一个薄薄的 :core:navigation 模块里,谁都能依赖。这样 :feature:news 想跳到收藏页,只需要知道那个 key 的类型,不需要依赖 :feature:bookmarks 的实现 —— 第 6 章的模块图会再回到这一点。

那 Mihon 为什么用 Voyager?

Mihon 没用 Nav2,也没用 Nav3,它用的是社区库 Voyager。这不是掉队,恰恰相反:

迁移:该怎么办

地基里最大的那块换完了。接下来两章进入第三幕:三档流派。 先从一个你以为早有定论的问题开始 —— 状态到底该住在哪儿? 官方说 ViewModel,Mihon 说不需要,还有一派说:presenter 本身就该是个 @Composable。