Memigrasikan Jetpack Navigation ke Navigation Compose

Navigation Compose API memungkinkan Anda bernavigasi antar-composable di aplikasi Compose, sekaligus memanfaatkan komponen, infrastruktur, dan fitur Jetpack Navigation.

Halaman ini menjelaskan cara melakukan migrasi dari Jetpack Navigation berbasis Fragmen ke Navigation Compose, sebagai bagian dari migrasi UI berbasis View yang lebih besar ke Jetpack Compose.

Prasyarat migrasi

Anda dapat bermigrasi ke Navigation Compose setelah dapat mengganti semua Fragment dengan composable layar yang sesuai. Composable layar dapat berisi campuran konten Compose dan View, tetapi semua tujuan navigasi harus berupa composable untuk mengaktifkan migrasi Navigation Compose. Sementara itu, Anda harus terus menggunakan komponen Navigasi berbasis Fragmen dalam codebase View dan Compose interop Anda. Lihat dokumentasi interop navigasi untuk informasi selengkapnya.

Menggunakan Navigation Compose di aplikasi khusus Compose bukan prasyarat. Anda dapat terus menggunakan komponen Navigasi berbasis Fragmen, selama Anda mempertahankan Fragment untuk menghosting konten composable.

Langkah migrasi

Baik mengikuti strategi migrasi yang direkomendasikan maupun menggunakan pendekatan lain, Anda akan mencapai titik di mana semua tujuan navigasi adalah composable layar, dengan Fragmen hanya bertindak sebagai penampung composable. Pada tahap ini, Anda dapat bermigrasi ke Navigation Compose.

Jika aplikasi Anda sudah mengikuti pola desain UDF dan panduan untuk arsitektur kami, migrasi ke Jetpack Compose dan Navigation Compose tidak akan memerlukan pemfaktoran ulang utama lapisan lain aplikasi Anda, selain dari lapisan UI.

Untuk bermigrasi ke Navigation Compose, ikuti langkah-langkah berikut:

  1. Tambahkan dependensi Navigation Compose ke aplikasi Anda.

  2. Buat composable App-level dan tambahkan ke Activity sebagai titik entri Compose Anda, yang menggantikan penyiapan tata letak View:

    class SampleActivity : ComponentActivity() {

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

  3. Siapkan NavController di tempat semua composable yang perlu mereferensikannya memiliki akses ke composable tersebut (biasanya di dalam composable App). Pendekatan ini mengikuti prinsip pengangkatan status dan memungkinkan Anda menggunakan NavController sebagai sumber tepercaya untuk menavigasi antar-layar composable dan mempertahankan data sebelumnya:

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

  4. Buat NavHost aplikasi Anda di dalam composable Aplikasi dan teruskan navController:

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

    SampleNavHost(navController = navController)
}

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

  5. Tambahkan tujuan composable untuk membuat grafik navigasi. Jika setiap layar sebelumnya telah dimigrasikan ke Compose, langkah ini hanya terdiri dari pengekstrakan composable layar ini dari Fragment ke tujuan 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

  6. Jika Anda mengikuti panduan tentang merancang UI Compose, khususnya cara ViewModel dan peristiwa navigasi harus diteruskan ke composable, langkah berikutnya adalah mengubah cara Anda menyediakan ViewModel ke setiap composable layar. Anda dapat sering menggunakan injeksi Hilt dan titik integrasinya dengan Compose dan Navigation melalui hiltViewModel:

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

  7. Ganti semua panggilan navigasi findNavController() dengan yang navController dan teruskan sebagai peristiwa navigasi ke setiap layar composable, bukan meneruskan seluruh navController. Pendekatan ini mengikuti praktik terbaik mengekspos peristiwa dari fungsi composable ke pemanggil dan mempertahankan navController sebagai satu sumber tepercaya.

    1. Jika sebelumnya Anda menggunakan plugin Safe Args untuk menghasilkan rute dan tindakan navigasi, ganti dengan rute — jalur String ke composable Anda yang unik untuk setiap tujuan.
    2. Untuk mengganti Safe Args saat meneruskan data, lihat Menavigasi dengan argumen.

    3. Untuk keamanan jenis di Navigation Compose, baca bagian Safe Args di bawah.

      @Composable
fun SampleNavHost(
    navController: NavHostController
) {
    NavHost(navController = navController, startDestination = "first") {
        composable("first") {
            FirstScreen(
                onButtonClick = {
                    // findNavController().navigate(firstScreenToSecondScreenAction)
                    navController.navigate("second_screen_route")
                }
            )
        }
        composable("second") {
            SecondScreen(
                onIconClick = {
                    // findNavController().navigate(secondScreenToThirdScreenAction)
                    navController.navigate("third_screen_route")
                }
            )
        }
        // ...
    }
}
      MigrationCommonScenariosSnippets.kt

  8. Menghapus semua Fragment, tata letak XML yang relevan, navigasi yang tidak perlu dan resource lainnya, serta dependensi Fragment dan Jetpack Navigation yang sudah tidak berlaku.

Anda dapat menemukan langkah-langkah yang sama dengan detail terkait Navigation Compose lainnya dalam Dokumentasi penyiapan.

Kasus penggunaan umum

Apa pun komponen Navigasi yang Anda gunakan, prinsip navigasi yang sama berlaku.

Kasus penggunaan umum saat melakukan migrasi mencakup hal berikut:

Untuk informasi lebih detail tentang kasus penggunaan ini, lihat Menavigasi dengan Compose.

Safe Args

Tidak seperti Jetpack Navigation, Navigation Compose tidak mendukung penggunaan plugin Safe Args untuk pembuatan kode. Sebagai gantinya, Anda dapat mencapai keamanan jenis dengan Navigation Compose melalui penataan kode untuk membuatnya aman dari jenis saat runtime.

Mengambil data yang kompleks saat menavigasi

Navigation Compose berbasis rute String dan, tidak seperti Navigasi Jetpack, tidak mendukung penerusan Parcelable dan Serializable kustom sebagai argumen.

Kami sangat menyarankan untuk tidak meneruskan objek data yang kompleks saat bernavigasi. Sebagai gantinya, teruskan informasi minimum yang diperlukan, seperti ID unik atau bentuk ID lainnya, sebagai argumen saat melakukan tindakan navigasi. Anda harus menyimpan objek kompleks sebagai data dalam satu sumber tepercaya, seperti lapisan data. Untuk mengetahui informasi selengkapnya, lihat Mengambil data kompleks saat menavigasi.

Jika Fragment meneruskan objek kompleks sebagai argumen, sebaiknya lakukan pemfaktoran ulang kode Anda terlebih dahulu, dengan cara yang memungkinkan objek ini disimpan dan diambil dari lapisan data. Lihat Repositori Now in Android untuk mengetahui contohnya.

Batasan

Bagian ini menjelaskan batasan saat ini untuk Navigation Compose.

Migrasi inkremental ke Navigation Compose

Saat ini, Anda tidak dapat menggunakan Navigation Compose sambil masih menggunakan Fragment sebagai tujuan dalam kode Anda. Untuk mulai menggunakan Navigation Compose, semua tujuan Anda harus menjadi composable. Anda dapat melacak permintaan fitur ini pada Issue Tracker.

Animasi transisi

Mulai dari Navigation 2.7.0-alpha01, dukungan untuk menyetel transisi kustom, yang sebelumnya dari AnimatedNavHost, kini didukung langsung di NavHost. Baca catatan rilis untuk informasi selengkapnya.

Pelajari lebih lanjut

Untuk informasi selengkapnya tentang cara bermigrasi ke Navigation Compose, lihat referensi berikut:

  • Codelab Navigation Compose: Pelajari dasar-dasar Navigation Compose dengan codelab interaktif.
  • Repositori Now in Android: Aplikasi Android yang berfungsi sepenuhnya dan dibangun sepenuhnya dengan Kotlin dan Jetpack Compose, yang mengikuti praktik terbaik pengembangan dan desain Android serta menyertakan Navigation Compose.
  • Memigrasikan Sunflower ke Jetpack Compose: Postingan blog yang mendokumentasikan perjalanan migrasi aplikasi contoh Sunflower dari View ke Compose, yang juga mencakup migrasi ke Navigation Compose.
  • Jetnews untuk setiap layar: Postingan blog yang mendokumentasikan pemfaktoran ulang dan migrasi contoh Jetnews untuk mendukung semua layar dengan Jetpack Compose dan Navigation Compose.