นำทางด้วยโมดูลฟีเจอร์

ไลบรารี Dynamic Navigator ขยายฟังก์ชันการทำงานของคอมโพเนนต์การนำทาง Jetpack เพื่อให้ทำงานร่วมกับปลายทางที่กำหนดไว้ในโมดูลฟีเจอร์ได้ นอกจากนี้ ไลบรารียังช่วยให้ติดตั้งโมดูลฟีเจอร์แบบออนดีมานด์ได้อย่างราบรื่นเมื่อไปยังปลายทางเหล่านี้

ตั้งค่า

หากต้องการรองรับโมดูลฟีเจอร์ ให้ใช้ทรัพยากร Dependency ต่อไปนี้ในไฟล์ build.gradle ของโมดูลแอป

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")
}

โปรดทราบว่าทรัพยากร Dependency อื่นๆ ของการนำทางควรใช้การกำหนดค่า API เพื่อให้พร้อมใช้งานสำหรับโมดูลฟีเจอร์

การใช้งานพื้นฐาน

หากต้องการรองรับโมดูลฟีเจอร์ ให้เปลี่ยนอินสแตนซ์ทั้งหมดของ NavHostFragment ในแอปเป็น androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment ก่อน โดยทำดังนี้

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

จากนั้นเพิ่มแอตทริบิวต์ app:moduleName ลงในปลายทาง <activity>, <fragment> หรือ <navigation> ในกราฟการนำทางของโมดูล com.android.dynamic-feature ที่เชื่อมโยงกับ DynamicNavHostFragment แอตทริบิวต์นี้จะบอกไลบรารี Dynamic Navigator ว่าปลายทางเป็นของโมดูลฟีเจอร์ที่มีชื่อที่คุณระบุ

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

เมื่อคุณไปยังปลายทางเหล่านี้ ไลบรารี Dynamic Navigator จะตรวจสอบก่อนว่ามีการติดตั้งโมดูลฟีเจอร์หรือไม่ หากมีโมดูลฟีเจอร์อยู่แล้ว แอปจะไปยังปลายทางตามที่คาดไว้ หากไม่มีโมดูล แอปจะแสดงปลายทาง Fragment ความคืบหน้าระดับกลางขณะติดตั้งโมดูล การติดตั้งใช้งานเริ่มต้นของส่วนความคืบหน้าจะแสดง UI พื้นฐานพร้อมแถบความคืบหน้าและจัดการข้อผิดพลาดในการติดตั้ง

หน้าจอการโหลด 2 หน้าจอที่แสดง UI พร้อมแถบความคืบหน้าเมื่อไปยังโมดูลฟีเจอร์เป็นครั้งแรก
รูปที่ 1 UI แสดงแถบความคืบหน้าเมื่อผู้ใช้ไปยังฟีเจอร์แบบออนดีมานด์เป็นครั้งแรก แอปจะแสดงหน้าจอนี้เมื่อดาวน์โหลดโมดูลที่เกี่ยวข้อง

หากต้องการปรับแต่ง UI นี้ หรือจัดการความคืบหน้าในการติดตั้งด้วยตนเองจากภายในหน้าจอแอปของคุณเอง โปรดดูส่วนปรับแต่งส่วนย่อยของความคืบหน้าและตรวจสอบสถานะคำขอในหัวข้อนี้

ปลายทางที่ไม่ได้ระบุ app:moduleName จะยังคงทำงานต่อไปโดยไม่มีการเปลี่ยนแปลง และทำงานเหมือนกับว่าแอปของคุณใช้ NavHostFragment ปกติ

ปรับแต่งส่วนความคืบหน้า

คุณสามารถลบล้างการติดตั้งใช้งาน Fragment ความคืบหน้าสำหรับกราฟการนำทางแต่ละรายการได้โดยตั้งค่าแอตทริบิวต์ app:progressDestination เป็นรหัสของปลายทางที่ต้องการใช้เพื่อจัดการความคืบหน้าในการติดตั้ง ปลายทางความคืบหน้าที่กำหนดเองควรเป็น Fragment ที่มาจาก AbstractProgressFragment คุณต้องลบล้างเมธอด Abstract สำหรับการแจ้งเตือนเกี่ยวกับความคืบหน้าในการติดตั้ง ข้อผิดพลาด และเหตุการณ์อื่นๆ จากนั้นคุณจะแสดงความคืบหน้าในการติดตั้งใน UI ที่ต้องการได้

คลาส DefaultProgressFragment ของการติดตั้งใช้งานเริ่มต้นใช้ API นี้เพื่อแสดงความคืบหน้าของการติดตั้ง

ตรวจสอบสถานะคำขอ

ไลบรารี Dynamic Navigator ช่วยให้คุณใช้ขั้นตอน UX ที่คล้ายกับขั้นตอนในแนวทางปฏิบัติแนะนำด้าน UX สำหรับการนำส่งแบบออนดีมานด์ ซึ่งผู้ใช้จะยังคงอยู่ในบริบทของหน้าจอก่อนหน้าขณะรอให้การติดตั้งเสร็จสิ้น ซึ่งหมายความว่าคุณไม่จำเป็นต้องแสดง UI ระดับกลางหรือส่วนย่อยของความคืบหน้าเลย

หน้าจอที่แสดงแถบนำทางด้านล่างพร้อมไอคอนที่ระบุว่ากำลังดาวน์โหลดโมดูลฟีเจอร์
รูปที่ 2 หน้าจอที่แสดงความคืบหน้าในการดาวน์โหลดจากแถบการนำทางด้านล่าง

ในกรณีนี้ คุณมีหน้าที่รับผิดชอบในการตรวจสอบและจัดการสถานะการติดตั้งทั้งหมด รวมถึงการเปลี่ยนแปลงความคืบหน้าและข้อผิดพลาด

หากต้องการเริ่มขั้นตอนการไปยังส่วนต่างๆ แบบไม่บล็อกนี้ ให้ส่งออบเจ็กต์ DynamicExtras ที่มี DynamicInstallMonitor ไปยัง NavController.navigate() ดังที่แสดงในตัวอย่างต่อไปนี้

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);
)

ทันทีหลังจากเรียกใช้ navigate() คุณควรตรวจสอบค่าของ installMonitor.isInstallRequired เพื่อดูว่าการพยายามไปยังส่วนต่างๆ ส่งผลให้มีการติดตั้งโมดูลฟีเจอร์หรือไม่

  • หากค่าเป็น false แสดงว่าคุณกำลังไปยังปลายทางปกติและไม่ต้องดำเนินการใดๆ เพิ่มเติม
  • หากค่าเป็น true คุณควรเริ่มสังเกตออบเจ็กต์ LiveData ซึ่งตอนนี้อยู่ใน installMonitor.status ออบเจ็กต์ LiveData นี้จะส่งการอัปเดต SplitInstallSessionState จากไลบรารี Play Core การอัปเดตเหล่านี้ประกอบด้วยเหตุการณ์ความคืบหน้าในการติดตั้งที่คุณสามารถใช้เพื่ออัปเดต UI ได้ อย่าลืมจัดการสถานะที่เกี่ยวข้องทั้งหมดตามที่ระบุไว้ในคู่มือ Play Core ซึ่งรวมถึงการขอการยืนยันจากผู้ใช้หากจำเป็น

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);
            }
        }
    });
}

เมื่อติดตั้งเสร็จแล้ว ออบเจ็กต์ LiveData จะแสดงสถานะ SplitInstallSessionStatus.INSTALLED จากนั้นคุณควรโทรหา NavController.navigate() อีกครั้ง เนื่องจากมีการติดตั้งโมดูลแล้ว การเรียกใช้จึงสำเร็จ และแอปจะไปยังปลายทางตามที่คาดไว้

หลังจากถึงสถานะสุดท้าย เช่น เมื่อการติดตั้งเสร็จสมบูรณ์หรือเมื่อการติดตั้งล้มเหลว คุณควรนำ LiveData observer ออกเพื่อหลีกเลี่ยงหน่วยความจำรั่วไหล คุณตรวจสอบได้ว่าสถานะแสดงถึงสถานะเทอร์มินัลหรือไม่โดยใช้ SplitInstallSessionStatus.hasTerminalStatus()

ดูตัวอย่างการใช้งานออบเซอร์เวอร์นี้ได้ที่ AbstractProgressFragment

กราฟที่รวมอยู่

ไลบรารี Dynamic Navigator รองรับการรวมกราฟที่กำหนดไว้ในโมดูลฟีเจอร์ หากต้องการรวมกราฟที่กำหนดไว้ในโมดูลฟีเจอร์ ให้ทำดังนี้

  1. ใช้ <include-dynamic/> แทน <include/> ดังที่แสดงในตัวอย่างต่อไปนี้

    <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. ภายใน <include-dynamic ... /> คุณต้องระบุแอตทริบิวต์ต่อไปนี้

    • app:graphResName: ชื่อไฟล์ทรัพยากรกราฟการนําทาง ชื่อจะมาจากชื่อไฟล์ของกราฟ เช่น หากกราฟอยู่ใน res/navigation/nav_graph.xml ชื่อทรัพยากรจะเป็น nav_graph
    • android:id - รหัสปลายทางของกราฟ ไลบรารี Dynamic Navigator จะละเว้นค่า android:id ที่พบในองค์ประกอบรูทของกราฟที่รวมไว้
    • app:moduleName: ชื่อแพ็กเกจของโมดูล

ใช้ graphPackage ที่ถูกต้อง

คุณต้องระบุ app:graphPackage ให้ถูกต้อง เนื่องจากคอมโพเนนต์ การนำทางจะไม่สามารถรวม navGraph ที่ระบุจากโมดูล ฟีเจอร์ได้

ชื่อแพ็กเกจของโมดูลฟีเจอร์แบบไดนามิกสร้างขึ้นโดยการเพิ่มชื่อของโมดูลต่อท้าย applicationId ของโมดูลแอปพื้นฐาน ดังนั้นหากโมดูลแอปพื้นฐานมี applicationId เป็น com.example.dynamicfeatureapp และโมดูลฟีเจอร์แบบไดนามิกมีชื่อว่า DynamicFeatureModule ชื่อแพ็กเกจของโมดูลแบบไดนามิกจะเป็น com.example.dynamicfeatureapp.DynamicFeatureModule ชื่อแพ็กเกจนี้คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

หากไม่แน่ใจ คุณสามารถยืนยันชื่อแพ็กเกจของโมดูลฟีเจอร์ได้โดยตรวจสอบ AndroidManifest.xml ที่สร้างขึ้น หลังจากสร้างโปรเจ็กต์แล้ว ให้ไปที่ <DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml ซึ่งควรมีลักษณะดังนี้

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

ค่า featureSplit ควรตรงกับชื่อของโมดูลฟีเจอร์แบบไดนามิก และแพ็กเกจจะตรงกับ applicationId ของโมดูลแอปพื้นฐาน app:graphPackage คือการรวมกันของสิ่งต่อไปนี้ com.example.dynamicfeatureapp.DynamicFeatureModule

คุณจะไปยัง startDestination ของกราฟการนำทาง include-dynamic ได้เท่านั้น โมดูลแบบไดนามิกมีหน้าที่รับผิดชอบกราฟการนำทางของตัวเอง และแอปพื้นฐานไม่มีข้อมูลเกี่ยวกับเรื่องนี้

กลไก include-dynamic ช่วยให้โมดูลแอปพื้นฐานรวมกราฟการนําทางที่ฝังอยู่ซึ่งกําหนดไว้ภายในโมดูลแบบไดนามิกได้ กราฟการนําทางที่ฝังนี้จะทํางานเหมือนกับกราฟการนําทางที่ฝังอื่นๆ กราฟการนําทางระดับรูท (นั่นคือระดับบนสุดของกราฟที่ฝัง) จะกําหนดได้เฉพาะกราฟการนําทางที่ฝังเป็นปลายทางเท่านั้น ไม่ใช่ระดับย่อย ดังนั้น ระบบจะใช้ startDestination เมื่อกราฟ include-dynamicnavigation เป็นปลายทาง

ข้อจำกัด

  • กราฟที่รวมแบบไดนามิกไม่รองรับ Deep Link ในขณะนี้
  • กราฟที่ฝังซึ่งโหลดแบบไดนามิก (นั่นคือองค์ประกอบ <navigation> ที่มี app:moduleName) ยังไม่รองรับ Deep Link ในขณะนี้