---
# System prepended metadata

title: '[Video Note] [Android] [Navigation] Stevdza-San - Everything you need to know about NEW Navigation 3'
tags: [Navigation, Android, Video Note]

---

### 為何需要 Navigation 3

* 提供更簡潔且符合 Compose 編程風格的 API。
* 原先的 Compose Navigation 無法直接觀察 BackStack，導致管理困難。
* 新版 Navigation 3 給予開發者完整控制 BackStack 的能力。
* 解決原先只能顯示單一畫面的限制，支援大型螢幕、平板、桌機與多視窗場景。
* 將支援 Compose Multiplatform，包括 Android、iOS（未來）與 Web（目前 alpha）。

---

### Navigation 3 的核心概念

* **BackStack** 是由開發者自行創建並維護的 `SnapshotStateList`。
* **Key** 代表畫面識別，通常為可序列化的 `data class` 或 `object`，不含實際畫面內容。
* **NavDisplay** 是新版取代 `NavHost` 的容器，用來顯示目前 BackStack 中的畫面。
* **NavEntry** 負責將 Key 與對應的 Composable 畫面綁定起來。
* **EntryProvider** 是函式，用來根據 Key 產出對應的 NavEntry 畫面。

---

### 畫面切換與傳遞參數

* 切換畫面只需將新的 Key 推入 BackStack。
* 若要傳參數，可用 `data class` 搭配建構子傳入。
* 畫面中透過 `entry.key` 取出傳入的參數。
* 無需使用 `popBackStack()`，只要從 BackStack 移除最後一個元素即可。

---

### 畫面旋轉與狀態保存

* BackStack 默認不會在畫面旋轉時保留。
* 使用 `rememberNavBackStack()` 可自動保存與還原 BackStack。
* 所有 Key 類別需實作 `NavKey` 並加上 `@Serializable` 註解。

---

### 使用 ViewModel 保存狀態

* 可將 BackStack 存在 ViewModel 中以支援狀態保留。
* 使用 `viewModel()` 取得 ViewModel 需注意其範圍預設為 Activity 層級。
* 若需限制 ViewModel 的生命週期至某個特定畫面，則需將其綁定至該畫面的 `NavEntry`。

---

### 將 ViewModel 綁定至 NavEntry

* 使用 `lifecycle-viewmodel-navigation-tree` artifact。
* 初始化 ViewModel 時從 `NavEntry` 中呼叫 `viewModel()`。
* 透過 `navDisplay` 的 `entryDecorators` 參數設定 ViewModel 的作用範圍。
* 畫面移除時該 ViewModel 會自動被清除，實現真正的畫面範圍作用域。

---

### 額外功能與未來方向

* 可支援多畫面顯示（Multi-pane layout）。
* 可整合 Bottom Bar、Tabs 等進階場景。
* 將持續強化 Compose Multiplatform 的整合。

---

### Terminlogy
* Jetpack Navigation 3：Jetpack 最新的 Compose 導覽函式庫，提供更符合 Compose 語法的 API 設計。
* Compose Idiomatic API：符合 Jetpack Compose 語言習慣與結構的 API 設計方式。
* Back Stack（返回棧）：畫面堆疊的結構，管理使用者的畫面瀏覽歷程。
* Back Stack Control（返回棧控制）：開發者擁有對返回棧的完全控制權。
* Key（鍵值）：代表畫面的唯一標識，可為資料類別，用來建構 Back Stack。
* Serializable Keys：可序列化的鍵值，允許保存與還原返回棧狀態。
* NavDisplay Composable：新的導航容器，用來顯示對應於返回棧頂層的畫面。
* NavEntry：對應於一個特定畫面的資料封裝，包含 key 與 Composable 畫面內容。
* EntryProvider：根據 key 提供對應的 NavEntry，用來決定要顯示哪個畫面。
* rememberNavBackStack：一個 Composable，用來建立並記憶返回棧，支援狀態保存。
* NavKey 介面：一個標記介面，表示該類別可作為 Navigation 3 返回棧的 key。
* SnapshotStateList：Compose 使用的狀態清單容器，可追蹤與回應清單內容的變化。
* State Hoisting（狀態上提）：將狀態從畫面中提升，便於管理與測試。
* System Back Handler：導航函式用來攔截系統返回按鈕，執行自定義邏輯。
* BackStack Mutation：透過新增或移除鍵值（key）以操作 Back Stack 的過程。
* DSL EntryProvider（DSL 語法 EntryProvider）：提供更簡潔的畫面定義語法。
* Composable Screen Routing：使用鍵值與 EntryProvider 決定畫面顯示的導覽方式。
* Multiplatform Compose：Jetpack Compose 跨平台支援（目前 Android/iOS 穩定，Web 為 alpha）。
* Multiple Screen Support：支援在大型裝置上顯示多個畫面並存，如平板與桌面。
* ViewModel Scope per Entry：讓 ViewModel 的生命週期綁定至特定 NavEntry，而非整個 Activity。
* Lifecycle ViewModel Navigation Tree：Artifact 用來實現 NavEntry 級別的 ViewModel 作用範圍。
* Entry Decorators：用於 NavDisplay 的參數，可配置如 ViewModel 的作用範圍等。
* Composable Content Isolation：畫面 Composable 內容與導航鍵值解耦，提升彈性與測試性。
* Manual BackStack Management：開發者需自行維護返回棧狀態，提供高度彈性。
* ViewModelStoreOwner：用於決定 ViewModel 所屬的生命週期管理者。
* NavEntry Scope ViewModel：限定在單一畫面存活期間的 ViewModel 實例。
* Key-Based Routing：使用鍵值來表示與導覽至特定畫面的方式。
* Compose Navigation Persistence：返回棧內容可透過序列化與 `remember` 保存。
* Composable Key Routing：以資料類別作為畫面路由鍵值進行導覽。
* Argument Passing via Keys：將參數封裝在鍵值中傳遞至下一畫面。
* Dynamic Content Mapping：透過鍵值動態決定要顯示哪個畫面。
* BackStack Pop：透過移除清單最後一項實作返回邏輯。
* NavGraph Replacement：以 NavDisplay 取代 NavHost，使用者可定義完整導覽流程。
* Stateless Navigation Function：NavDisplay 不持有狀態，由使用者提供 BackStack 狀態。
* Compose Multi-Pane Support：新導覽函式庫支援多畫面同時呈現的設計需求。
* Jetpack Navigation 3 Artifact：新的 library 組件名稱，需手動加入 Gradle。
* No NavHost（無 NavHost）：新版不再使用 NavHost，而是 NavDisplay 作為替代。
* Compose Native Navigation：完全符合 Compose 架構的新式導航函式庫。
* EntryProvider Map Routing：透過 key-to-entry 對應決定顯示畫面。
* Screen Rotation State Preservation：維持畫面旋轉後狀態不丟失的機制。
* Multimodule Flexibility：提高模組間畫面導覽的獨立性與可測試性。
* Composable-Based Navigation Architecture：每個畫面都是 Composable，導航邏輯純以鍵值驅動。
* Navigation Lifecycle Management：透過 decorator 控制生命週期範圍。
* Compose Navigation Restoration：導覽狀態可於應用重新啟動後還原。
* Entry Key Matching：透過 `when` 或 DSL 判斷目前是哪個畫面。
* Navigation Tree（導覽樹）：代表導覽結構與返回棧內容的新模式。
* NavEntry Injection Scope：允許在 NavEntry 階段注入依賴（如 ViewModel）。
* Composable Transition Control：可自定進出畫面轉場動畫。
* Clear Separation of Concerns：畫面內容與導航邏輯明確分離。
* Persistent Navigation State：支援導覽狀態持久化以應對應用異常關閉。
* Navigation in Alpha：Jetpack Navigation 3 目前仍處於開發初期階段（alpha）。
* Jetpack Compose Clean API：更乾淨、明確、型安全的 Compose 導覽解法。
