Jetpack Navigation 3 1.0 版已穩定發布 🎉，歡迎立即在正式版應用程式中使用。JetBrains 已在 KotlinConf 應用程式中使用。

Navigation 3 是從頭建構的新導覽程式庫，可支援 Jetpack Compose 狀態。您可以完全掌控返回堆疊、保留導覽狀態，並輕鬆建立自適應版面配置 (例如清單/詳細資料)。JetBrains 甚至還提供跨平台版本。

為什麼要推出新版媒體庫？

原始的 Jetpack Navigation 程式庫 (現為 Nav2) 是 7 年前設計的，雖然能達成原始目標，且經過反覆改良，但現在建構應用程式的方式已徹底改變。

使用宣告式 UI 進行反應式程式設計已成為常態。Nav3 採用這種做法。舉例來說，NavDisplay (顯示畫面的 Nav3 UI 元件) 只會觀察由 Compose 狀態支援的鍵清單 (每個鍵代表一個畫面)，並在該清單變更時更新 UI。

Nav2 也有自己的內部狀態，因此很難為導覽狀態提供單一可靠資料來源。使用 Nav3 時，您可自行提供狀態，因此能全面掌控。

最後，您希望有更多彈性和自訂選項。Nav3 並非單一的單體式 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 的 Agent Mode 版 Gemini 試用這項功能，請按照下列步驟操作：

• 將本指南的 Markdown 版本儲存到專案中。
• 將這個提示詞貼到代理程式 (但不要按 Enter 鍵)："Migrate this project to Navigation 3 using "。
• 輸入 @migration-guide.md，將指南提供給代理程式做為背景資訊。

請務必仔細檢查 AI 代理程式所做的變更，因為它可能會出錯！

歡迎在這裡分享你或服務專員的表現。

常見情境的實用導覽食譜

對於常見但細微的用途，我們提供食譜存放區。這項範例說明如何以特定方式組合使用 Nav3 API，讓您選擇或修改配方，以滿足特定需求。如果某個食譜很受歡迎，我們會考慮將其中不精細的部分「升級」至核心 Nav3 程式庫或附加程式庫。

目前共有 19 個食譜，包括：

• 多個返回堆疊
• 模組化和依附元件插入
• 將導覽引數傳遞至 ViewModel (包括使用 Koin)
• 從畫面傳回結果 (依事件和共用狀態)

我們目前正著手開發深層連結配方和 Koin 整合，並已規劃許多其他功能。JetBrains 的工程師也發布了食譜的 Compose Multiplatform 版本。

如果您有常見的用途，並希望我們提供相關食譜，請提出食譜要求。

摘要

如要開始使用 Nav3，請參閱說明文件和食譜。此外，我們還準備了一整週的技術內容，包括：

• 這部影片深入探索 API，涵蓋模組化、動畫和自動調整式版面配置。
• 與建構 Nav3 的工程師進行即時問答 (AMA)。

Nav3 Spotlight Week 將於 2025 年 12 月 1 日開始。

如有任何問題，請在這裡回報。