將 Jetpack Navigation 遷移至 Navigation Compose

Navigation Compose API 可讓您瀏覽 Compose 應用程式，同時利用 Jetpack Navigation 元件 基礎架構與功能

本頁面說明如何從以 Fragment 為基礎的 Jetpack Navigation 遷移至 Navigation Compose，參與以 View 為基礎的大型 UI 遷移至 Jetpack 。

遷移作業必備條件

只要您能夠將所有 Fragment 替換為對應的畫面可組合項，就可以遷移至 Navigation Compose。螢幕可組合項可包含 Compose 和 View 內容的混合，但所有導覽目的地都必須是可組合項，才能啟用 Navigation Compose 遷移功能。在此之前， 請繼續在互通性檢視畫面中使用以片段為基礎的 Navigation 元件， Compose 程式碼集。詳情請參閱導覽介面互通說明文件。

即使在僅支援 Compose 的應用程式中使用 Navigation Compose 也不是必要條件。你可以 繼續使用 以片段為基礎的 Navigation 元件 用於代管可組合項內容的片段。

遷移步驟

無論您採用建議的遷移策略或其他方法，都會達到一個階段，所有導覽目的地都是螢幕可組合項，而片段只會充當可組合項容器。在這個階段，您可以遷移至 Navigation Compose。

如果您的應用程式已遵循 UDF 設計模式和 遷移至 Jetpack Compose 和 Navigation Compose 時應該不會 需要應用程式其他層的主要重構 (除了 UI 層之外)。

如要遷移至 Navigation Compose，請按照下列步驟操作：

  1. 在應用程式中新增 Navigation Compose 依附元件。

  2. 建立 App-level 可組合函式，並將其新增至 Activity 做為 Compose 進入點，取代 View 版面配置的設定：

    class SampleActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
        setContent {
            SampleApp(/* ... */)
        }
    }
}
    MigrationCommonScenariosSnippets.kt

  3. 為每個導覽目的地建立類型。將 data object 用於以下用途： 不需要任何資料，以及 data class 或 class 的目的地 需要資料的目的地

    @Serializable data object First
@Serializable data class Second(val id: String)
@Serializable data object Third

    MigrationCommonScenariosSnippets.kt

  4. 請在所有需要參照其的可組合項都能存取的位置設定 NavController (通常位於 App 可組合項內)。這種做法符合狀態升降原則，可讓您使用 NavController 做為可組合畫面之間導覽和維護返回堆疊的可靠資料來源：

    @Composable
fun SampleApp() {
    val navController = rememberNavController()
    // ...
}
    MigrationCommonScenariosSnippets.kt

  5. 在 App 可組合項中建立應用程式的 NavHost，並傳遞 navController：

    @Composable
fun SampleApp() {
    val navController = rememberNavController()

    SampleNavHost(navController = navController)
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  6. 新增 composable 目的地以建構導覽圖。如果每個畫面先前已遷移至 Compose，這個步驟只需將這些畫面可組合項從片段擷取至 composable 目的地即可：

    class FirstFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        return ComposeView(requireContext()).apply {
            setContent {
                // FirstScreen(...) EXTRACT FROM HERE
            }
        }
    }
}

@Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(/* ... */) // EXTRACT TO HERE
        }
        composable<Second> {
            SecondScreen(/* ... */)
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  7. 如果您按照設計 Compose UI 的說明操作，特別是如何將 ViewModel 和導覽事件傳遞至可組合函式，下一步就是變更向每個螢幕可組合函式提供 ViewModel 的方式。您通常可以透過 hiltViewModel，使用 Hilt 插入作業及其與 Compose 和 Navigation 的整合點：

    @Composable
fun FirstScreen(
    // viewModel: FirstViewModel = viewModel(),
    viewModel: FirstViewModel = hiltViewModel(),
    onButtonClick: () -> Unit = {},
) {
    // ...
}
    MigrationCommonScenariosSnippets.kt

  8. 將所有 findNavController() 導覽呼叫替換為 navController 呼叫，並將這些呼叫做為導覽事件傳遞至每個可組合項畫面，而不是傳遞整個 navController。這種做法遵循最佳做法，將可組合函式中的事件公開給呼叫端，並將 navController 維持為單一可靠資料來源。

    您可以建立為該目的地定義的路徑類別例項，將資料傳遞至目的地。然後您就可以 從目的地或 ViewModel 的返回堆疊項目中 SavedStateHandle.toRoute()。

    @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = First) {
        composable<First> {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate(Second(id = "ABC"))
                }
            )
        }
        composable<Second> { backStackEntry ->
            val secondRoute = backStackEntry.toRoute<Second>()
            SecondScreen(
                id = secondRoute.id,
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate(Third)
                }
            )
        }
        // ...
    }
}
    MigrationCommonScenariosSnippets.kt

  9. 移除所有 Fragment、相關的 XML 版面配置、不必要的導覽和其他 以及過時的 Fragment 和 Jetpack Navigation 依附元件

您也可以在 設定說明文件。

常見用途

無論您使用何種 Navigation 元件， 導覽元件。

遷移作業的常見用途包括：

如要進一步瞭解這些用途，請參閱「使用 Compose 瀏覽」一文。

瀏覽時擷取複雜資料

強烈建議您不要在導覽時傳遞複雜的資料物件。 而是在執行導覽動作時，將最少必要資訊 (例如專屬 ID 或其他形式的 ID) 做為引數傳遞。請 將複雜物件儲存為單一可靠資料來源中的資料，例如資料 資料層如需詳細資訊，請參閱擷取複雜資料的時機 導航。

如果 Fragment 將複雜物件做為引數傳遞，請先考慮重構程式碼，以便從資料層儲存及擷取這些物件。如需範例，請參閱 Now in Android 存放區。

限制

本節說明 Navigation Compose 目前的限制。

逐步遷移至 Navigation Compose

目前您無法在使用 Fragment 做為 加入到達網頁如要開始使用 Navigation Compose，所有目的地都必須是可組合項。你可以在Issue Tracker 上追蹤這項功能要求。

轉場動畫

從 Navigation 2.7.0-alpha01 開始支援設定自訂功能 原先來自AnimatedNavHost的轉場效果 直接支援 NavHost。詳閱版本資訊 瞭解詳情

瞭解詳情

如要進一步瞭解如何遷移至 Navigation Compose，請參閱下列文章 資源：

  • Navigation Compose 程式碼研究室：透過實作程式碼研究室，瞭解 Navigation Compose 的基本概念。
  • Now in Android 存放區：這是一款功能完整的 Android 應用程式，完全採用 Kotlin 和 Jetpack Compose 建構，遵循 Android 設計和開發最佳做法，並包含 Navigation Compose。
  • 將 Sunflower 遷移至 Jetpack Compose：這篇網誌文章 這份說明文件記錄了 Sunflower 範例應用程式從 View 到 Compose，這也包括遷移至 Navigation Compose。
  • 適用於各種螢幕的 Jetnews：這篇部落格文章記錄了 Jetpack Compose 和 Navigation Compose 如何支援所有螢幕，並記錄了 Jetnews 範例的重構和遷移作業。