Özellik modülleriyle gezinme

Dinamik Gezgin kitaplığı, Jetpack Gezinme bileşeninin işlevini özellik modüllerinde tanımlanan hedeflerle çalışacak şekilde genişletir. Bu kitaplık, bu hedeflere giderken isteğe bağlı özellik modüllerinin sorunsuz bir şekilde yüklenmesini de sağlar.

Kurulum

Özellik modüllerini desteklemek için uygulama modülünüzün build.gradle dosyasında aşağıdaki bağımlılıkları kullanın:

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

Diğer Navigasyon bağımlılıklarının, özellik modülleriniz tarafından kullanılabilmesi için api yapılandırmalarını kullanması gerektiğini unutmayın.

Temel kullanım

Özellik modüllerini desteklemek için önce uygulamanızdaki tüm NavHostFragment örneklerini androidx.navigation.dynamicfeatures.fragment.DynamicNavHostFragment olarak değiştirin:

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

Ardından, com.android.dynamic-feature modülünüzün gezinme grafiklerinde DynamicNavHostFragment ile ilişkili olan tüm <activity>, <fragment> veya <navigation> hedeflerine bir app:moduleName özelliği ekleyin. Bu özellik, Dinamik Gezgin kitaplığına, hedefin belirttiğiniz ada sahip bir özellik modülüne ait olduğunu bildirir.

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

Bu hedeflerden birine gittiğinizde Dinamik Gezgin kitaplığı, öncelikle özellik modülünün yüklü olup olmadığını kontrol eder. Özellik modülü zaten mevcutsa uygulamanız hedefe beklendiği gibi gider. Modül mevcut değilse uygulamanız, modülü yüklerken ara ilerleme parçası hedefini gösterir. İlerleme fragment'ının varsayılan uygulaması, ilerleme çubuğu içeren temel bir kullanıcı arayüzü gösterir ve yükleme hatalarını işler.

Bir özellik modülüne ilk kez gidildiğinde ilerleme çubuğu içeren kullanıcı arayüzünü gösteren iki yükleme ekranı
Şekil 1. Kullanıcı seç-izle özelliğine ilk kez gittiğinde ilerleme çubuğu gösteren kullanıcı arayüzü. Uygulama, ilgili modül indirilirken bu ekranı gösterir.

Bu kullanıcı arayüzünü özelleştirmek veya yükleme ilerleme durumunu kendi uygulama ekranınızdan manuel olarak yönetmek için bu konudaki İlerleme fragment'ını özelleştirme ve İstek durumunu izleme bölümlerine bakın.

app:moduleName belirtmeyen hedefler, değişiklik yapılmadan çalışmaya devam eder ve uygulamanız normal bir NavHostFragment kullanıyormuş gibi davranır.

İlerleme fragment'ını özelleştirme

app:progressDestination özelliğini, yükleme ilerleme durumunu işlemek için kullanmak istediğiniz hedefin kimliğine ayarlayarak her gezinme grafiği için ilerleme durumu parçası uygulamasını geçersiz kılabilirsiniz. Özel ilerleme hedefiniz, AbstractProgressFragment sınıfından türetilen bir Fragment olmalıdır. Yükleme ilerleme durumu, hatalar ve diğer etkinliklerle ilgili bildirimler için soyut yöntemleri geçersiz kılmanız gerekir. Ardından, yükleme ilerleme durumunu istediğiniz bir kullanıcı arayüzünde gösterebilirsiniz.

Varsayılan uygulamanın DefaultProgressFragment sınıfı, yükleme durumunu göstermek için bu API'yi kullanır.

İstek durumunu izleme

Dinamik Gezgin kitaplığı, Seç-izle yayın için kullanıcı deneyimiyle ilgili en iyi uygulamalar bölümündekine benzer bir kullanıcı deneyimi akışı uygulamanıza olanak tanır. Bu akışta kullanıcı, yüklemenin tamamlanmasını beklerken önceki ekranın bağlamında kalır. Bu, ara kullanıcı arayüzü veya ilerleme parçası göstermeniz gerekmediği anlamına gelir.

Özellik modülünün indirildiğini gösteren bir simge içeren alt gezinme çubuğunun bulunduğu ekran
Şekil 2. Alt gezinme çubuğundan indirme işleminin ilerleme durumunu gösteren ekran.

Bu senaryoda, ilerleme durumu değişiklikleri ve hatalar dahil olmak üzere tüm yükleme durumlarını izlemek ve yönetmek sizin sorumluluğunuzdadır.

Bu engellenmeyen gezinme akışını başlatmak için aşağıdaki örnekte gösterildiği gibi NavController.navigate() yöntemine DynamicInstallMonitor içeren bir DynamicExtras nesnesi iletin:

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() yöntemini çağırdıktan hemen sonra, gezinme denemesinin bir özellik modülü yüklemesiyle sonuçlanıp sonuçlanmadığını görmek için installMonitor.isInstallRequired değerini kontrol etmeniz gerekir.

  • Değer false ise normal bir hedefe gidiyorsunuz demektir ve başka bir işlem yapmanız gerekmez.
  • Değer true ise artık installMonitor.status durumunda olan LiveData nesnesini gözlemlemeye başlamanız gerekir. Bu LiveData nesnesi, Play Core kitaplığından SplitInstallSessionState güncellemeleri yayınlar. Bu güncellemeler, kullanıcı arayüzünü güncellemek için kullanabileceğiniz yükleme ilerleme durumu etkinliklerini içerir. Gerektiğinde kullanıcı onayı isteme de dahil olmak üzere tüm ilgili durumları Play Core kılavuzunda açıklandığı şekilde ele almayı unutmayın.

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

Yükleme tamamlandığında LiveData nesnesi SplitInstallSessionStatus.INSTALLED durumunu gösterir. Ardından NavController.navigate() numarasını tekrar aramanız gerekir. Modül yüklendiği için çağrı artık başarılı olur ve uygulama, beklendiği gibi hedefe gider.

Yükleme tamamlandığında veya başarısız olduğunda olduğu gibi bir terminal durumuna ulaştıktan sonra, bellek sızıntılarını önlemek için LiveData gözlemcinizi kaldırmanız gerekir. SplitInstallSessionStatus.hasTerminalStatus() kullanarak durumun bir terminal durumunu temsil edip etmediğini kontrol edebilirsiniz.

Bu gözlemcinin örnek bir uygulaması için AbstractProgressFragment bölümüne bakın.

Dahil edilen grafikler

Dinamik Gezgin kitaplığı, özellik modüllerinde tanımlanan grafikleri eklemeyi destekler. Bir özellik modülünde tanımlanan grafiği eklemek için aşağıdakileri yapın:

  1. Aşağıdaki örnekte gösterildiği gibi <include/> yerine <include-dynamic/> kullanın:

    <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 ... /> içinde aşağıdaki özellikleri belirtmeniz gerekir:

    • app:graphResName: Gezinme grafiği kaynak dosyasının adı. Ad, grafiğin dosya adından türetilir. Örneğin, grafik res/navigation/nav_graph.xml içindeyse kaynak adı nav_graph olur.
    • android:id: Grafiğin hedef kimliği. Dinamik Gezgin kitaplığı, dahil edilen grafiğin kök öğesinde bulunan tüm android:id değerlerini yoksayar.
    • app:moduleName: Modülün paket adı.

Doğru graphPackage'ı kullanın.

app:graphPackage değerini doğru girmek önemlidir. Aksi takdirde Gezinme bileşeni, özellik modülünden belirtilen navGraph değerini dahil edemez.

Dinamik özellik modülünün paket adı, modülün adının temel uygulama modülünün applicationId öğesine eklenmesiyle oluşturulur. Yani temel uygulama modülünün applicationId değeri com.example.dynamicfeatureapp ise ve dinamik özellik modülünün adı DynamicFeatureModule ise dinamik modülün paket adı com.example.dynamicfeatureapp.DynamicFeatureModule olur. Bu paket adı büyük/küçük harfe duyarlıdır.

Şüpheye düşerseniz oluşturulan AndroidManifest.xml dosyasını kontrol ederek özellik modülünün paket adını doğrulayabilirsiniz. Projeyi derledikten sonra <DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml adresine gidin. Bu adres şuna benzer şekilde görünmelidir:

<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 değeri, dinamik özellik modülünün adıyla eşleşmelidir. Paket ise temel uygulama modülünün applicationId değeriyle eşleşir. app:graphPackage, şunların birleşimidir: com.example.dynamicfeatureapp.DynamicFeatureModule.

Yalnızca bir include-dynamic gezinme grafiğinin startDestination öğesine gidilebilir. Dinamik modül, kendi gezinme grafiğinden sorumludur ve temel uygulama bu konuda bilgi sahibi değildir.

include-dynamic mekanizması, temel uygulama modülünün dinamik modülde tanımlanan iç içe yerleştirilmiş gezinme grafiğini içermesini sağlar. Bu iç içe yerleştirilmiş gezinme grafiği, diğer iç içe yerleştirilmiş gezinme grafikleri gibi davranır. Kök gezinme grafiği (yani iç içe yerleştirilmiş grafiğin üst öğesi), yalnızca iç içe yerleştirilmiş gezinme grafiğini hedef olarak tanımlayabilir, alt öğelerini tanımlayamaz. Bu nedenle, include-dynamicnavigation grafiği hedef olduğunda startDestination kullanılır.

Sınırlamalar

  • Dinamik olarak dahil edilen grafikler şu anda derin bağlantıları desteklemiyor.
  • Dinamik olarak yüklenen iç içe yerleştirilmiş grafikler (yani app:moduleName içeren bir <navigation> öğesi) şu anda derin bağlantıları desteklemez.