了解并实现基本功能

导航是指用户在应用中移动的方式。用户通常通过点按或点击界面元素与界面元素互动，而应用会通过显示新内容来响应。如果用户想返回上一个内容，可以使用返回手势或点按返回按钮。

对导航状态进行建模

模拟此行为的一种便捷方法是使用内容堆叠。当用户向前浏览到新内容时，系统会将其推送到堆栈顶部。当用户从该内容返回时，系统会将其从堆栈中弹出，并显示之前的内容。在导航术语中，此堆栈通常称为返回堆栈，因为它表示用户可以返回的内容。

图 1. 显示返回堆栈如何随用户导航事件而变化的图表。

创建返回堆栈

在 Navigation 3 中，返回堆栈实际上不包含内容。而是包含对内容的引用，称为键。键可以是任何类型，但通常是简单的可序列化数据类。使用引用而非内容具有以下优势：

• 通过将按键推送到返回堆栈，即可轻松导航。
• 只要键可序列化，返回堆栈便可保存到永久存储空间，从而使其在发生配置更改和进程终止后继续存在。这一点很重要，因为用户希望离开您的应用，稍后再返回，并从上次离开时的位置继续观看，同时系统会显示相同的内容。如需了解详情，请参阅保存返回堆栈。

Navigation 3 API 中的一个关键概念是，您拥有返回堆栈。该库：

• 预计您的返回堆栈将是基于快照状态的 List<T>，其中 T 是返回堆栈 keys 的类型。您可以使用 Any，也可以提供自己的更严格类型的键。当您看到“push”或“pop”一词时，底层实现是从列表的末尾添加或移除项。
• 观察返回堆栈，并使用 NavDisplay 在界面中反映其状态。

以下示例展示了如何创建按键和返回堆栈，以及如何修改返回堆栈以响应用户导航事件：

// Define keys that will identify content
data object ProductList
data class ProductDetail(val id: String)

@Composable
fun MyApp() {

    // Create a back stack, specifying the key the app should start with
    val backStack = remember { mutableStateListOf<Any>(ProductList) }

    // Supply your back stack to a NavDisplay so it can reflect changes in the UI
    // ...more on this below...

    // Push a key onto the back stack (navigate forward), the navigation library will reflect the change in state
    backStack.add(ProductDetail(id = "ABC"))

    // Pop a key off the back stack (navigate back), the navigation library will reflect the change in state
    backStack.removeLastOrNull()
}
BasicSnippets.kt

将键解析为内容

在 Navigation 3 中，内容是使用 NavEntry 进行建模的，它是一个包含可组合函数的类。它表示一个目的地，即用户可以前往和返回的单个内容。

NavEntry 还可以包含元数据，即内容相关信息。容器对象（例如 NavDisplay）可以读取这些元数据，以帮助它们决定如何显示 NavEntry 的内容。例如，元数据可用于替换特定 NavEntry 的默认动画。NavEntry metadata 是 String 键与 Any 值的映射，可提供多样化的数据存储。

如需将 key 转换为 NavEntry，请创建条目提供程序。这是一个接受 key 并为该 key 返回 NavEntry 的函数。在创建 NavDisplay 时，它通常定义为 lambda 参数。

您可以通过以下两种方式创建条目提供程序：直接创建 lambda 函数，或使用 entryProvider DSL。

直接创建条目提供程序函数

您通常使用 when 语句创建条目提供程序函数，并为每个键提供一个分支。

entryProvider = { key ->
    when (key) {
        is ProductList -> NavEntry(key) { Text("Product List") }
        is ProductDetail -> NavEntry(
            key,
            metadata = mapOf("extraDataKey" to "extraDataValue")
        ) { Text("Product ${key.id} ") }

        else -> {
            NavEntry(Unit) { Text(text = "Invalid Key: $it") }
        }
    }
}
BasicSnippets.kt

使用 entryProvider DSL

entryProvider DSL 可以简化 lambda 函数，因为您无需针对每个键类型进行测试，并且无需为每个键类型构建 NavEntry。为此，请使用 entryProvider 构建器函数。它还包含在未找到键时采用的默认回退行为（抛出错误）。

entryProvider = entryProvider {
    entry<ProductList> { Text("Product List") }
    entry<ProductDetail>(
        metadata = mapOf("extraDataKey" to "extraDataValue")
    ) { key -> Text("Product ${key.id} ") }
}
BasicSnippets.kt

请注意该代码段中的以下内容：

• entry 用于定义具有给定类型和可组合项内容的 NavEntry
• entry 接受 metadata 参数以设置 NavEntry.metadata

显示返回堆栈

返回堆栈表示应用的导航状态。每当返回堆栈发生变化时，应用界面都应反映新的返回堆栈状态。在 Navigation 3 中，NavDisplay 会观察返回堆栈并相应地更新其界面。使用以下参数构造它：

• 返回堆栈 - 此项应为 SnapshotStateList<T> 类型，其中 T 是返回堆栈键的类型。它是一个可观察的 List，因此当它发生变化时，会触发 NavDisplay 的重组。
• 用于将返回堆栈中的键转换为 NavEntry 的 entryProvider。
• （可选）向 onBack 参数提供 lambda。当用户触发返回事件时，系统会调用此方法。

以下示例展示了如何创建 NavDisplay。

data object Home
data class Product(val id: String)

@Composable
fun NavExample() {

    val backStack = remember { mutableStateListOf<Any>(Home) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = { key ->
            when (key) {
                is Home -> NavEntry(key) {
                    ContentGreen("Welcome to Nav3") {
                        Button(onClick = {
                            backStack.add(Product("123"))
                        }) {
                            Text("Click to navigate")
                        }
                    }
                }

                is Product -> NavEntry(key) {
                    ContentBlue("Product ${key.id} ")
                }

                else -> NavEntry(Unit) { Text("Unknown route") }
            }
        }
    )
}
BasicSnippets.kt

默认情况下，NavDisplay 会以单窗格布局显示返回堆栈中最顶层的 NavEntry。以下录制内容展示了此应用的运行情况：

图 2. 具有两个目的地的 NavDisplay 默认行为。

总结

下图显示了数据如何在 Navigation 3 中的各种对象之间流动：

图 3. 显示数据如何在 Navigation 3 中的各种对象中流动的图表。

1. 导航事件会发起更改。系统会根据用户互动情况，向返回堆栈添加或从中移除按键。

2. 返回堆栈状态的更改会触发内容检索。NavDisplay（用于渲染返回堆栈的可组合项）会观察返回堆栈。在默认配置下，它会在单个窗格布局中显示最顶层的返回堆栈条目。当返回堆栈上的顶部按键发生变化时，NavDisplay 会使用此按键从条目提供程序请求相应内容。

3. 条目提供程序提供内容。条目提供程序是一种将键解析为 NavEntry 的函数。从 NavDisplay 收到键后，条目提供程序会提供关联的 NavEntry，其中包含键和内容。

4. 内容会显示。NavDisplay 会接收 NavEntry 并显示内容。