Memigrasikan Jetpack Navigation ke Navigation Compose

Navigation Compose API memungkinkan Anda beralih antar-composable dalam Aplikasi Compose, sambil memanfaatkan komponen Jetpack Navigation, infrastruktur, dan fitur.

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 Tulis.

Prasyarat migrasi

Anda dapat bermigrasi ke Navigation Compose setelah dapat mengganti semua Fragmen dengan composable layar yang sesuai. Composable layar dapat berisi campuran konten Compose dan View, tetapi semua tujuan navigasi harus composable untuk mengaktifkan migrasi Navigation Compose. Sebelum itu, Anda seharusnya terus menggunakan komponen Navigasi Berbasis Fragmen dalam Tampilan interop Anda dan Codebase Compose. Lihat dokumentasi interop navigasi untuk informasi selengkapnya tidak akurat atau tidak sesuai.

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

Langkah migrasi

Apakah Anda mengikuti strategi migrasi yang kami rekomendasikan atau mengambil pendekatan lain, Anda akan mencapai titik di mana semua tujuan navigasi composable layar, dengan Fragment bertindak hanya sebagai penampung composable. Di Anda dapat bermigrasi ke Navigation Compose.

Jika aplikasi Anda sudah mengikuti pola desain UDF dan panduan untuk arsitektur, migrasi ke Jetpack Compose dan Navigation Compose tidak boleh memerlukan pemfaktoran ulang utama lapisan lain aplikasi Anda, selain 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, 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. Menyiapkan NavController di tempat semua composable yang memerlukan untuk mereferensikannya, file tersebut dapat mengaksesnya (biasanya ada di dalam App composable). Pendekatan ini mengikuti prinsip pengangkatan status dan memungkinkan Anda menggunakan NavController sebagai sumber kebenaran untuk menavigasi di antara 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 sebelumnya telah dimigrasikan ke Compose, langkah ini hanya terdiri dari mengekstrak composable layar ini dari Fragment ke dalam composable tujuan:

    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 penerusan ViewModel dan peristiwa navigasi ke composable, langkah berikutnya adalah mengubah cara menyediakan ViewModel untuk setiap composable layar. Anda dapat sering menggunakan injeksi Hilt dan 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 navController dan meneruskannya sebagai peristiwa navigasi ke setiap layar composable, bukan daripada meneruskan seluruh navController. Pendekatan ini mengikuti cara terbaik praktik mengekspos peristiwa dari fungsi composable ke pemanggil dan mempertahankan navController sebagai satu-satunya sumber kebenaran.

    1. Jika sebelumnya Anda menggunakan plugin Safe Args untuk membuat 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 ini.

      @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. Hapus semua Fragment, tata letak XML yang relevan, navigasi yang tidak perlu, dan resource, dan dependensi Jetpack Navigation yang sudah tidak berlaku.

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

Kasus penggunaan umum

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

Kasus penggunaan umum saat melakukan migrasi mencakup hal berikut:

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

Safe Args

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

Mengambil data yang kompleks saat menavigasi

Navigation Compose berbasis rute String dan, tidak seperti Jetpack Navigation, melakukannya tidak mendukung penerusan Parcelable kustom dan Serializable 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 lain, sebagai argumen saat melakukan tindakan navigasi. Anda seharusnya menyimpan objek yang kompleks sebagai data dalam satu sumber yang terpercaya, seperti data . Untuk informasi selengkapnya, baca artikel Mengambil data kompleks saat menavigasi.

Jika Fragment Anda meneruskan objek kompleks sebagai argumen, pertimbangkan pemfaktoran ulang kode Anda terlebih dahulu, dengan cara yang memungkinkan penyimpanan dan pengambilan objek ini dari lapisan data. Lihat Repositori Now in Android untuk contoh.

Batasan

Bagian ini menjelaskan batasan saat ini untuk Navigation Compose.

Migrasi inkremental ke Navigation Compose

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

Animasi transisi

Dimulai dengan Navigation 2.7.0-alpha01, dukungan untuk setelan kustom transisi, sebelumnya dari AnimatedNavHost, kini menjadi didukung secara langsung di NavHost. Baca catatan rilis untuk informasi selengkapnya.

Pelajari lebih lanjut

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

  • Codelab Navigation Compose: Pelajari dasar-dasar Navigation Compose dengan codelab langsung.
  • Now in Android repository: Aplikasi Android yang berfungsi penuh sepenuhnya dibangun dengan Kotlin dan Jetpack Compose, yang mengikuti desain Android dan praktik terbaik pengembangan, 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.