ניווט באמצעות מודולים של מאפיינים

ספריית Dynamic Navigator מרחיבה את הפונקציונליות של רכיב הניווט של Jetpack כדי לעבוד עם יעדים שמוגדרים במודולים של תכונות. הספרייה הזו גם מאפשרת התקנה חלקה של מודולים של תכונות מתי שנוח כשמנווטים ליעדים האלה.

הגדרה

כדי לתמוך במודולים של תכונות, צריך להשתמש ביחסי התלות הבאים בקובץ 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")
}

שימו לב ששאר יחסי התלות של Navigation צריכים להשתמש בהגדרות 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. המאפיין הזה מציין לספריית הניווט הדינמי שהיעד שייך למודול של תכונות עם השם שציינתם.

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

כשמנווטים לאחד מהיעדים האלה, ספריית Dynamic Navigator בודקת קודם אם מודול של תכונות מותקן. אם מודול התכונות כבר קיים, האפליקציה תנווט ליעד כצפוי. אם המודול לא קיים, האפליקציה תציג יעד של קטע התקדמות ביניים בזמן שהיא מתקינה את המודול. ההטמעה שמוגדרת כברירת מחדל של קטע ההתקדמות מציגה ממשק משתמש בסיסי עם סרגל התקדמות ומטפלת בשגיאות בהתקנה.

שני מסכי טעינה שמציגים ממשק משתמש עם סרגל התקדמות כשמנווטים
         למודול של תכונות בפעם הראשונה
תרשים 1. ממשק משתמש שמוצג בו סרגל התקדמות כשמשתמש מנווט לתכונה על פי דרישה בפעם הראשונה. האפליקציה מציגה את המסך הזה בזמן שהמודול המתאים יורד.

כדי להתאים אישית את ממשק המשתמש הזה, או כדי לטפל באופן ידני בהתקדמות ההתקנה מתוך מסך האפליקציה שלכם, עיינו בקטעים התאמה אישית של קטע ההתקדמות ומעקב אחר מצב הבקשה בנושא הזה.

יעדים שלא מציינים את app:moduleName ממשיכים לפעול ללא שינויים ומתנהגים כאילו האפליקציה משתמשת ב-NavHostFragment רגיל.

התאמה אישית של קטע ההתקדמות

אפשר לשנות את ההטמעה של קטע ההתקדמות בכל תרשים ניווט על ידי הגדרת המאפיין app:progressDestination למזהה היעד שבו רוצים להשתמש כדי לטפל בהתקדמות ההתקנה. יעד ההתקדמות בהתאמה אישית צריך להיות Fragment שנגזר מ-AbstractProgressFragment. צריך לשנות את השיטות המופשטות כדי לקבל התראות על התקדמות ההתקנה, שגיאות ואירועים אחרים. אחר כך אפשר להציג את התקדמות ההתקנה בממשק משתמש לבחירתכם.

המחלקה DefaultProgressFragment של הטמעת ברירת המחדל משתמשת ב-API הזה כדי להציג את התקדמות ההתקנה.

מעקב אחרי מצב הבקשה

ספריית Dynamic Navigator מאפשרת לכם להטמיע תהליך של חוויית משתמש שדומה לזה שמתואר במאמר שיטות מומלצות לחוויית משתמש בהעברה על פי דרישה, שבו המשתמש נשאר בהקשר של מסך קודם בזמן ההמתנה לסיום ההתקנה. זה אומר שאתם לא צריכים להציג ממשק משתמש ביניים או מקטע התקדמות בכלל.

מסך שמוצג בו סרגל ניווט תחתון עם סמל שמציין
         שמודול של תכונות נמצא בתהליך הורדה
איור 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. העדכונים האלה מכילים אירועים של התקדמות ההתקנה, שבהם אפשר להשתמש כדי לעדכן את ממשק המשתמש. חשוב לטפל בכל הסטטוסים הרלוונטיים כפי שמתואר במדריך של 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 כדי למנוע דליפות זיכרון. אפשר לבדוק אם הסטטוס מייצג מצב סופי באמצעות 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 – מזהה היעד של התרשים. ספריית הניווט הדינמי מתעלמת מכל ערכי 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 הוא היעד.

מגבלות

  • תרשימים שנוספים באופן דינמי לא תומכים כרגע בקישורי עומק.
  • תרשימים מוטמעים שנטענים באופן דינמי (כלומר, רכיב <navigation> עם app:moduleName) לא תומכים כרגע בקישורי עומק.