Jetpack Navigation 3 稳定版已发布

Jetpack Navigation 3 1.0 版已稳定 🎉。现在就可以在正式版应用中使用它。JetBrains 已在其 KotlinConf 应用中使用该功能。

Navigation 3 是一个全新的导航库，从头开始构建，旨在充分利用 Jetpack Compose 状态。它让您能够完全控制返回堆栈，帮助您保留导航状态，并让您能够轻松创建自适应布局（例如列表-详情）。JetBrains 甚至还推出了一个跨平台版本。

为什么需要新库？

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

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

此外，Nav2 具有自己的内部状态，因此很难为导航状态提供单一事实来源。使用 Navigation 3 时，您需要自行提供状态，从而实现完全控制。

最后，您希望获得更高的灵活性和可定制性。Nav3 并非提供单一、庞大的 API，而是提供更小、解耦的 API（或“构建块”），这些 API 可以组合在一起，以创建复杂的功能。Navigation 3 本身会使用这些构建块，为定义明确的导航用例提供合理的默认设置。

通过这种方法，您可以：

• 在全局和单个级别自定义屏幕动画
• 同时显示多个窗格，并使用 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 键）：“Migrate this project to Navigation 3 using ”。
• 输入 @migration-guide.md，这会将指南作为上下文提供给智能体。

一如既往，请务必仔细检查 AI 智能体所做的更改，因为它可能会出错！

我们非常期待了解您或您的代理人的表现，请点击此处发送反馈。

适用于常见场景的 Tasty 导航食谱

对于常见但细微的使用场景，我们提供了一个方案代码库。这展示了如何以特定方式组合 Nav3 API，以便您根据特定需求选择或修改方案。如果某个方案很受欢迎，我们会考虑将其不细微的部分“升级”到核心 Nav3 库或插件库中。

目前有 19 个配方，包括：

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

我们目前正在开发深层链接方案，以及 Koin 集成，并计划推出更多方案。JetBrains 的一位工程师还发布了这些食谱的 Compose Multiplatform 版本。

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

摘要

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

• 一个深入探究该 API 的视频，涵盖模块化、动画和自适应布局。
• 与 Nav3 开发者进行实时问答 (AMA)。

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

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