Menavigasi dengan modul fitur

Library Dynamic Navigator memperluas fungsi komponen Navigasi Jetpack agar dapat berfungsi dengan tujuan yang ditentukan dalam modul fitur. Library ini juga menyediakan penginstalan modul fitur on-demand yang lancar saat menuju ke tujuan tersebut.

Penyiapan

Untuk mendukung modul fitur, gunakan dependensi berikut dalam file build.gradle modul aplikasi Anda:

Groovy

dependencies {
    def nav_version = "2.10.2"

    api "androidx.navigation:navigation-fragment-ktx:$nav_version"
    api "androidx.navigation:navigation-ui-ktx:$nav_version"
    api "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"
}

Kotlin

dependencies {
    val nav_version = "2.10.2"

    api("androidx.navigation:navigation-fragment-ktx:$nav_version")
    api("androidx.navigation:navigation-ui-ktx:$nav_version")
    api("androidx.navigation:navigation-dynamic-features-fragment:$nav_version")
}

Perhatikan bahwa dependensi Navigation lainnya harus menggunakan konfigurasi api agar tersedia untuk modul fitur Anda.

Penggunaan dasar

Untuk mendukung modul fitur, ubah semua instance NavHostFragment di aplikasi ke androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment terlebih dahulu:

<androidx.fragment.app.FragmentContainerView
    android:id="@+id/nav_host_fragment"
    android:name="androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment"
    app:navGraph="@navigation/nav_graph"
    ... />

Selanjutnya, tambahkan atribut app:moduleName ke tujuan <activity>, <fragment>, atau <navigation> dalam grafik navigasi modul com.android.dynamic-feature yang terkait dengan DynamicNavHostFragment. Atribut ini memberi tahu library Navigator Dinamis bahwa tujuan dimiliki oleh modul fitur dengan nama yang Anda tentukan.

<fragment
    app:moduleName="myDynamicFeature"
    android:id="@+id/featureFragment"
    android:name="com.google.android.samples.feature.FeatureFragment"
    ... />

Saat Anda menavigasi ke salah satu tujuan tersebut, library Navigator Dinamis akan memeriksa terlebih dahulu apakah modul fitur telah diinstal. Jika modul fitur sudah ada, aplikasi Anda akan menavigasi ke tujuan seperti yang diharapkan. Jika modul tidak ada, aplikasi Anda akan menampilkan tujuan fragmen progres menengah saat menginstal modul. Implementasi default fragmen progres menampilkan UI dasar dengan status progres dan menangani error penginstalan.

dua layar pemuatan yang menampilkan UI dengan status progres saat menavigasi ke
         modul fitur untuk pertama kalinya
Gambar 1. UI yang menampilkan status progres saat pengguna membuka fitur on-demand untuk pertama kalinya. Aplikasi menampilkan layar ini sebagai hasil download modul yang sesuai.

Untuk menyesuaikan UI ini, atau menangani progres penginstalan secara manual dari dalam layar aplikasi Anda sendiri, lihat bagian Menyesuaikan fragmen progres dan Memantau status permintaan dalam topik ini.

Tujuan yang tidak menentukan app:moduleName tetap berfungsi tanpa perubahan dan berperilaku seolah-olah aplikasi Anda menggunakan NavHostFragment reguler.

Menyesuaikan fragmen progres

Anda dapat mengganti implementasi fragmen progres untuk setiap grafik navigasi dengan menyetel atribut app:progressDestination ke ID tujuan yang ingin Anda gunakan untuk menangani progres penginstalan. Tujuan progres kustom Anda harus berupa Fragment yang berasal dari AbstractProgressFragment. Anda harus mengganti metode abstrak untuk notifikasi tentang progres penginstalan, error, dan peristiwa lainnya. Kemudian, Anda dapat menampilkan progres penginstalan di UI pilihan Anda.

Class DefaultProgressFragment implementasi default menggunakan API ini untuk menampilkan progres penginstalan.

Memantau status permintaan

Library Dynamic Navigator memungkinkan Anda menerapkan alur UX yang mirip dengan yang ada di Praktik terbaik UX untuk pengiriman on demand, yang membuat pengguna tetap berada dalam konteks layar sebelumnya sambil menunggu penginstalan selesai. Artinya, Anda tidak perlu menampilkan UI perantara atau fragmen progres sama sekali.

layar yang menampilkan menu navigasi bawah dengan ikon yang menunjukkan
         bahwa modul fitur sedang didownload
Gambar 2. Layar yang menampilkan progres download dari menu navigasi bawah.

Dalam skenario ini, Anda bertanggung jawab untuk memantau dan menangani semua status penginstalan, termasuk perubahan progres dan error.

Untuk memulai alur navigasi non-pemblokiran ini, teruskan objek DynamicExtras yang berisi DynamicInstallMonitor ke NavController.navigate(), seperti yang ditunjukkan dalam contoh berikut:

Kotlin

val navController = ...
val installMonitor = DynamicInstallMonitor()

navController.navigate(
    destinationId,
    null,
    null,
    DynamicExtras(installMonitor)
)

Java

NavController navController = ...
DynamicInstallMonitor installMonitor = new DynamicInstallMonitor();

navController.navigate(
    destinationId,
    null,
    null,
    new DynamicExtras(installMonitor);
)

Setelah memanggil navigate(), Anda harus memeriksa nilai installMonitor.isInstallRequired untuk melihat apakah navigasi yang dicoba menghasilkan penginstalan modul fitur.

  • Jika nilainya false, Anda akan menavigasi ke tujuan normal dan tidak perlu melakukan apa pun.
  • Jika nilainya adalah true, Anda harus mulai mengamati objek LiveData yang sekarang berada di installMonitor.status. Objek LiveData ini memunculkan update SplitInstallSessionState dari library Play Core. Update ini berisi peristiwa progres penginstalan yang dapat Anda gunakan untuk memperbarui UI. Jangan lupa untuk menangani semua status yang relevan seperti yang diuraikan dalam panduan Play Core, termasuk meminta konfirmasi pengguna jika perlu.

Kotlin

val navController = ...
val installMonitor = DynamicInstallMonitor()

navController.navigate(
    destinationId,
    null,
    null,
    DynamicExtras(installMonitor)
)

if (installMonitor.isInstallRequired) {
    installMonitor.status.observe(this, object : Observer<SplitInstallSessionState> {
        override fun onChanged(sessionState: SplitInstallSessionState) {
            when (sessionState.status()) {
                SplitInstallSessionStatus.INSTALLED -> {
                    // Call navigate again here or after user taps again in the UI:
                    // navController.navigate(destinationId, destinationArgs, null, null)
                }
                SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION -> {
                    SplitInstallManager.startConfirmationDialogForResult(...)
                }

                // Handle all remaining states:
                SplitInstallSessionStatus.FAILED -> {}
                SplitInstallSessionStatus.CANCELED -> {}
            }

            if (sessionState.hasTerminalStatus()) {
                installMonitor.status.removeObserver(this);
            }
        }
    });
}

Java

NavController navController = ...
DynamicInstallMonitor installMonitor = new DynamicInstallMonitor();

navController.navigate(
    destinationId,
    null,
    null,
    new DynamicExtras(installMonitor);
)

if (installMonitor.isInstallRequired()) {
    installMonitor.getStatus().observe(this, new Observer<SplitInstallSessionState>() {
        @Override
        public void onChanged(SplitInstallSessionState sessionState) {
            switch (sessionState.status()) {
                case SplitInstallSessionStatus.INSTALLED:
                    // Call navigate again here or after user taps again in the UI:
                    // navController.navigate(mDestinationId, mDestinationArgs, null, null);
                    break;
                case SplitInstallSessionStatus.REQUIRES_USER_CONFIRMATION:
                    SplitInstallManager.startConfirmationDialogForResult(...)
                    break;

                // Handle all remaining states:
                case SplitInstallSessionStatus.FAILED:
                    break;
                case SplitInstallSessionStatus.CANCELED:
                    break;
            }

            if (sessionState.hasTerminalStatus()) {
                installMonitor.getStatus().removeObserver(this);
            }
        }
    });
}

Setelah penginstalan selesai, objek LiveData akan menampilkan status SplitInstallSessionStatus.INSTALLED. Kemudian Anda harus memanggil NavController.navigate() lagi. Karena modul telah terinstal, panggilan sekarang akan berhasil berjalan dan aplikasi akan menavigasi ke tujuan seperti yang diharapkan.

Setelah mencapai status terminal, seperti saat penginstalan selesai atau saat penginstalan gagal, Anda harus menghapus LiveData observer untuk menghindari kebocoran memori. Anda dapat memeriksa apakah status mewakili status terminal dengan menggunakan SplitInstallSessionStatus.hasTerminalStatus().

Lihat AbstractProgressFragment untuk contoh penerapan observer ini.

Grafik yang disertakan

Library Navigator Dinamis mendukung penyertaan grafik yang ditentukan dalam modul fitur. Untuk menyertakan grafik yang ditentukan dalam modul fitur, lakukan hal berikut:

  1. Gunakan <include-dynamic/>, bukan <include/>, seperti yang ditunjukkan pada contoh berikut:

    <include-dynamic
        android:id="@+id/includedGraph"
        app:moduleName="includedgraphfeature"
        app:graphResName="included_feature_nav"
        app:graphPackage="com.google.android.samples.dynamic_navigator.included_graph_feature" />
    
  2. Di dalam <include-dynamic ... />, Anda harus menentukan atribut berikut:

    • app:graphResName: nama file resource grafik navigasi. Nama ini berasal dari nama file grafik. Misalnya, jika grafik menggunakan res/navigation/nav_graph.xml, nama resource-nya adalah nav_graph.
    • android:id - ID tujuan grafik. Library Navigator Dinamis mengabaikan nilai android:id mana pun yang ditemukan dalam elemen root grafik yang disertakan.
    • app:moduleName: nama paket modul.

Menggunakan graphPackage yang benar

Penting untuk mendapatkan app:graphPackage yang benar karena komponen Navigasi tidak akan dapat menyertakan navGraph yang ditentukan dari modul fitur.

Nama paket modul fitur dinamis dikonstruksi dengan menambahkan nama modul ke applicationId modul aplikasi dasar. Jadi, jika modul aplikasi dasar memiliki applicationId dari com.example.dynamicfeatureapp dan modul fitur dinamis bernama DynamicFeatureModule, maka nama paket modul dinamis akan menjadi com.example.dynamicfeatureapp.DynamicFeatureModule. Nama paket ini peka terhadap huruf besar/kecil.

Jika ragu, Anda dapat mengonfirmasi nama paket modul fitur dengan memeriksa AndroidManifest.xml yang dihasilkan. Setelah membangun project, buka <DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml, yang akan terlihat seperti ini:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:dist="http://schemas.android.com/apk/distribution"
    featureSplit="DynamicFeatureModule"
    package="com.example.dynamicfeatureapp"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-sdk
        android:minSdkVersion="21"
        android:targetSdkVersion="30" />

    <dist:module
        dist:instant="false"
        dist:title="@string/title_dynamicfeaturemodule" >
        <dist:delivery>
            <dist:install-time />
        </dist:delivery>

        <dist:fusing dist:include="true" />
    </dist:module>

    <application />

</manifest>

Nilai featureSplit harus cocok dengan nama modul fitur dinamis, dan paket akan cocok dengan applicationId modul aplikasi dasar. app:graphPackage adalah kombinasi dari: com.example.dynamicfeatureapp.DynamicFeatureModule.

Anda hanya dapat menavigasi ke startDestination grafik navigasi include-dynamic. Modul dinamis bertanggung jawab atas grafik navigasinya sendiri dan aplikasi dasarnya tidak memiliki pengetahuan tentang hal tersebut.

Mekanisme include-dynamic memungkinkan modul aplikasi dasar menyertakan grafik navigasi bertingkat yang ditentukan dalam modul dinamis. Grafik navigasi bertingkat ini berperilaku seperti grafik navigasi bertingkat lainnya. Grafik navigasi root (yaitu, induk dari grafik bertingkat) hanya dapat menentukan grafik navigasi bertingkat itu sendiri sebagai tujuan, bukan turunannya. Dengan demikian, startDestination digunakan saat grafik include-dynamicnavigation adalah tujuan.

Batasan

  • Grafik yang disertakan secara dinamis saat ini tidak mendukung deep link.
  • Grafik bertingkat yang dimuat secara dinamis (yaitu, elemen <navigation> dengan app:moduleName) saat ini tidak mendukung deep link.