ไลบรารี 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 พื้นฐานพร้อมแถบความคืบหน้าและจัดการข้อผิดพลาดในการติดตั้ง
หากต้องการปรับแต่ง UI นี้ หรือจัดการความคืบหน้าในการติดตั้งด้วยตนเองจากภายในหน้าจอแอปของคุณเอง โปรดดูส่วนปรับแต่งส่วนย่อยของความคืบหน้าและตรวจสอบสถานะคำขอในหัวข้อนี้
ปลายทางที่ไม่ได้ระบุ app:moduleName จะยังคงทำงานต่อไปโดยไม่มีการเปลี่ยนแปลง และทำงานเหมือนกับว่าแอปของคุณใช้ NavHostFragment ปกติ
ปรับแต่งส่วนความคืบหน้า
คุณสามารถลบล้างการติดตั้งใช้งาน Fragment ความคืบหน้าสำหรับกราฟการนำทางแต่ละรายการได้โดยตั้งค่าแอตทริบิวต์ app:progressDestination เป็นรหัสของปลายทางที่ต้องการใช้เพื่อจัดการความคืบหน้าในการติดตั้ง ปลายทางความคืบหน้าที่กำหนดเองควรเป็น Fragment ที่มาจาก AbstractProgressFragment คุณต้องลบล้างเมธอด Abstract สำหรับการแจ้งเตือนเกี่ยวกับความคืบหน้าในการติดตั้ง ข้อผิดพลาด และเหตุการณ์อื่นๆ จากนั้นคุณจะแสดงความคืบหน้าในการติดตั้งใน UI ที่ต้องการได้
คลาส DefaultProgressFragment ของการติดตั้งใช้งานเริ่มต้นใช้ API นี้เพื่อแสดงความคืบหน้าของการติดตั้ง
ตรวจสอบสถานะคำขอ
ไลบรารี Dynamic Navigator ช่วยให้คุณใช้ขั้นตอน UX ที่คล้ายกับขั้นตอนในแนวทางปฏิบัติแนะนำด้าน UX สำหรับการนำส่งแบบออนดีมานด์ ซึ่งผู้ใช้จะยังคงอยู่ในบริบทของหน้าจอก่อนหน้าขณะรอให้การติดตั้งเสร็จสิ้น ซึ่งหมายความว่าคุณไม่จำเป็นต้องแสดง UI ระดับกลางหรือส่วนย่อยของความคืบหน้าเลย
ในกรณีนี้ คุณมีหน้าที่รับผิดชอบในการตรวจสอบและจัดการสถานะการติดตั้งทั้งหมด รวมถึงการเปลี่ยนแปลงความคืบหน้าและข้อผิดพลาด
หากต้องการเริ่มขั้นตอนการไปยังส่วนต่างๆ แบบไม่บล็อกนี้ ให้ส่งออบเจ็กต์ 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 รองรับการรวมกราฟที่กำหนดไว้ในโมดูลฟีเจอร์ หากต้องการรวมกราฟที่กำหนดไว้ในโมดูลฟีเจอร์ ให้ทำดังนี้
ใช้
<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" />ภายใน
<include-dynamic ... />คุณต้องระบุแอตทริบิวต์ต่อไปนี้app:graphResName: ชื่อไฟล์ทรัพยากรกราฟการนําทาง ชื่อจะมาจากชื่อไฟล์ของกราฟ เช่น หากกราฟอยู่ในres/navigation/nav_graph.xmlชื่อทรัพยากรจะเป็นnav_graphandroid: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 ในขณะนี้