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 智能体所做的更改，它可能会犯错！

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

常见场景的 Tasty 导航食谱

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

目前有 19 个食谱，包括：

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

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

如果您有想要了解相关方案的常见使用场景，请提交方案请求。

摘要

如需开始使用 Nav3，请查看文档和方案。此外，我们还将在接下来的一周内推出一系列技术内容，包括：

• 有关该 API 的深度解析视频，涵盖模块化、动画和自适应布局。
• 与构建 Nav3 的工程师进行“有问必答”(AMA) 直播。

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

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