Jetpack Navigation 3 版本 1.0 已是稳定版 🎉。欢迎立即在生产应用中使用。JetBrains 已在其 KotlinConf 应用中使用该版本。

Navigation 3 是一个全新的导航库，从头开始构建，旨在支持 Jetpack Compose 状态。借助该库，您可以完全掌控返回堆栈，保留导航状态，并轻松创建自适应布局（如列表详情）。JetBrains 甚至还推出了跨平台版本。

为什么要推出新库？

最初的 Jetpack Navigation 库（现在的 Nav2）是 7 年前设计的。虽然该库很好地实现了最初的目标，并且经过了迭代改进，但现在的应用构建方式已发生了根本性变化。

现在，使用声明式界面进行响应式编程已成为常态。Nav3 采用了这种方法。例如，NavDisplay（用于显示屏幕的 Nav3 界面组件）只需观察由 Compose 状态支持的键列表（每个键代表一个屏幕），并在该列表发生变化时更新其界面。

Nav2 还可以让导航状态难以拥有 单一可靠来源，因为它有自己的内部状态。借助 Nav3，您可以提供自己的状态，从而完全掌控。

最后，您要求提供更高的灵活性和可自定义性。Nav3 没有采用单一的整体式 API，而是提供了更小、解耦的 API（或“构建块”），这些 API 可以组合在一起以创建复杂的功能。Nav3 本身使用这些构建块为明确定义的导航用例提供合理的默认值。

借助这种方法，您可以：

• 在全局和个人层面自定义屏幕动画
• 同时显示多个窗格，并使用 Scenes API 创建灵活的布局
• 如果您需要自定义行为，可以轻松地将 Nav3 组件替换为您自己的实现

如需详细了解其设计和功能，请参阅发布博文。

从 Navigation 2 迁移

如果您已在使用 Nav2（尤其是 Navigation Compose），则应考虑迁移到 Nav3。为了帮助您完成此操作，我们提供了迁移指南。主要步骤如下：

1. 添加 Navigation 3 依赖项。
2. 更新导航路线以实现 NavKey。您的路线不必实现此接口即可使用 Nav3，但如果实现，您可以利用 Nav3 的 rememberNavBackStack 函数创建持久性返回堆栈。
3. 创建用于保存和修改导航状态的类 - 这是保存返回堆栈的位置。
4. 将 NavController 替换为这些类。
5. 将目的地从 NavHost 的 NavGraph 移到 entryProvider 中。
6. 将 NavHost 替换为 NavDisplay。

试用 AI 智能体迁移

您可能想尝试使用 AI 智能体来阅读迁移指南，并在您的项目中执行这些步骤。如需在 Android Studio 的代理模式下使用 Gemini 尝试此操作，请执行以下操作：

• 将本指南的 Markdown 版本保存到您的项目中。
• 将此提示粘贴到代理（但不要按 Enter 键）：“使用 将此项目迁移到 Navigation 3”。
• 输入 @migration-guide.md - 这会将指南作为上下文提供给代理。

与往常一样，请务必仔细检查 AI 智能体所做的更改 - 它可能会犯错！

我们很想了解您或您的代理的表现，请在此处发送反馈。

常见场景的实用导航配方

对于常见但细致的用例，我们提供了一个配方代码库。该代码库展示了如何以特定方式组合 Nav3 API，让您可以根据自己的特定需求选择或修改配方。如果某个配方很受欢迎，我们会考虑将其非细致部分“毕业”到核心 Nav3 库或附加库中。

目前有 19 个配方，包括：

• 多个返回堆栈
• 模块化和依赖项注入
• 将导航参数传递给 ViewModel（包括使用 Koin）
• 通过事件和共享状态从屏幕返回结果

我们目前正在开发一个深层链接配方和一个Koin 集成，并计划推出更多配方。JetBrains 的一位工程师还发布了配方的 Compose Multiplatform 版本。

如果您有希望看到配方的常见用例，请提交配方请求。

摘要

如需开始使用 Nav3，请查看 文档 和 配方。此外，请留意为期一周的技术内容，包括：

• 关于 API 的深入视频，涵盖模块化、动画和自适应布局。
• 与构建 Nav3 的工程师进行“随便问” (AMA) 直播。

Nav3 Spotlight Week 将于 2025 年 12 月 1 日开始。

与往常一样，如果您发现任何问题，请在此处提交。