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.
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.
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
falseise normal bir hedefe gidiyorsunuz demektir ve başka bir işlem yapmanız gerekmez. Değer
trueise artıkinstallMonitor.statusdurumunda olanLiveDatanesnesini gözlemlemeye başlamanız gerekir. BuLiveDatanesnesi, Play Core kitaplığındanSplitInstallSessionStategü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:
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" /><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, grafikres/navigation/nav_graph.xmliçindeyse kaynak adınav_grapholur.android:id: Grafiğin hedef kimliği. Dinamik Gezgin kitaplığı, dahil edilen grafiğin kök öğesinde bulunan tümandroid:iddeğ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.
Dinamik gezinme grafiği içeren bir grafiğe gitme
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:moduleNameiçeren bir<navigation>öğesi) şu anda derin bağlantıları desteklemez.