La libreria Dynamic Navigator estende la funzionalità del componente Jetpack Navigation per funzionare con le destinazioni definite nei moduli delle funzionalità. Questa libreria fornisce anche un'installazione fluida dei moduli delle funzionalità on demand quando si naviga verso queste destinazioni.
Configurazione
Per supportare i moduli delle funzionalità, utilizza le seguenti dipendenze nel file build.gradle del modulo dell'app:
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") }
Tieni presente che le altre dipendenze di navigazione devono utilizzare le configurazioni API in modo che siano disponibili per i moduli delle funzionalità.
Utilizzo di base
Per supportare i moduli delle funzionalità, modifica innanzitutto tutte le istanze di
NavHostFragment nella tua app in
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"
... />
Successivamente, aggiungi un attributo app:moduleName a qualsiasi destinazione <activity>, <fragment> o <navigation> nei grafici di navigazione del modulo com.android.dynamic-feature associati a un DynamicNavHostFragment.
Questo attributo indica alla libreria Dynamic Navigator che la destinazione appartiene a un modulo della funzionalità con il nome specificato.
<fragment
app:moduleName="myDynamicFeature"
android:id="@+id/featureFragment"
android:name="com.google.android.samples.feature.FeatureFragment"
... />
Quando accedi a una di queste destinazioni, la libreria Dynamic Navigator controlla innanzitutto se il modulo della funzionalità è installato. Se il modulo della funzionalità è già presente, l'app passa alla destinazione come previsto. Se il modulo non è presente, l'app mostra una destinazione del frammento di avanzamento intermedio durante l'installazione del modulo. L'implementazione predefinita del frammento di avanzamento mostra una UI di base con una barra di avanzamento e gestisce eventuali errori di installazione.
Per personalizzare questa UI o per gestire manualmente l'avanzamento dell'installazione dalla schermata della tua app, consulta le sezioni Personalizza il frammento di avanzamento e Monitora lo stato della richiesta in questo argomento.
Le destinazioni che non specificano app:moduleName continuano a funzionare senza modifiche e si comportano come se la tua app utilizzasse un NavHostFragment normale.
Personalizza il frammento di avanzamento
Puoi eseguire l'override dell'implementazione del frammento di avanzamento per ogni grafico di navigazione impostando l'attributo app:progressDestination sull'ID della destinazione che vuoi utilizzare per gestire l'avanzamento dell'installazione. La destinazione di avanzamento personalizzata deve essere un Fragment che deriva da AbstractProgressFragment. Devi eseguire l'override dei metodi astratti per le notifiche relative all'avanzamento dell'installazione, agli errori e ad altri eventi. Puoi quindi mostrare l'avanzamento dell'installazione in una UI di tua scelta.
La classe DefaultProgressFragment dell'implementazione predefinita utilizza questa API per mostrare l'avanzamento dell'installazione.
Monitora lo stato della richiesta
La libreria Dynamic Navigator ti consente di implementare un flusso UX simile a quello descritto in Best practice per l'esperienza utente per la distribuzione on demand, in cui un utente rimane nel contesto di una schermata precedente in attesa del completamento dell'installazione. Ciò significa che non è necessario mostrare un'interfaccia utente intermedia o un frammento di avanzamento.
In questo scenario, sei responsabile del monitoraggio e della gestione di tutti gli stati di installazione, incluse le modifiche allo stato di avanzamento e gli errori.
Per avviare questo flusso di navigazione non bloccante, passa un oggetto DynamicExtras contenente un DynamicInstallMonitor a NavController.navigate(), come mostrato nell'esempio seguente:
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);
)
Subito dopo aver chiamato navigate(), devi controllare il valore di installMonitor.isInstallRequired per verificare se il tentativo di navigazione ha comportato l'installazione di un modulo della funzionalità.
- Se il valore è
false, stai navigando verso una destinazione normale e non devi fare altro. Se il valore è
true, devi iniziare a osservare l'oggettoLiveDatache ora si trova ininstallMonitor.status. Questo oggettoLiveDataemette aggiornamentiSplitInstallSessionStatedalla libreria di base Play. Questi aggiornamenti contengono eventi di avanzamento dell'installazione che puoi utilizzare per aggiornare la UI. Ricorda di gestire tutti gli stati pertinenti come descritto nella guida alla libreria di base Play, inclusa la richiesta di conferma dell'utente, se necessario.
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);
}
}
});
}
Al termine dell'installazione, l'oggetto LiveData genera uno stato SplitInstallSessionStatus.INSTALLED. Dovresti quindi chiamare di nuovo NavController.navigate(). Poiché il modulo è ora installato, la chiamata va a buon fine e l'app si sposta alla destinazione come previsto.
Dopo aver raggiunto uno stato terminale, ad esempio quando l'installazione viene completata o non va a buon fine, devi rimuovere l'observer LiveData per evitare perdite di memoria. Puoi verificare se lo stato rappresenta uno stato terminale utilizzando
SplitInstallSessionStatus.hasTerminalStatus().
Per un esempio di implementazione di questo osservatore, consulta AbstractProgressFragment.
Grafici inclusi
La libreria Dynamic Navigator supporta l'inclusione di grafici definiti nei moduli delle funzionalità. Per includere un grafico definito in un modulo della funzionalità:
Utilizza
<include-dynamic/>anziché<include/>, come mostrato nell'esempio seguente:<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" />All'interno di
<include-dynamic ... />, devi specificare i seguenti attributi:app:graphResName: il nome del file di risorse del grafico di navigazione. Il nome deriva dal nome file del grafico. Ad esempio, se il grafico si trova inres/navigation/nav_graph.xml, il nome della risorsa ènav_graph.android:id: l'ID destinazione del grafico. La libreria Dynamic Navigator ignora i valoriandroid:idpresenti nell'elemento root del grafico incluso.app:moduleName: il nome del pacchetto del modulo.
Utilizza il graphPackage corretto
È importante che app:graphPackage sia corretto, altrimenti il componente di navigazione non potrà includere l'elemento navGraph specificato dal modulo della funzionalità.
Il nome del pacchetto di un modulo di funzionalità dinamica viene creato aggiungendo il nome del modulo al applicationId del modulo dell'app di base. Quindi, se il modulo dell'app di base ha un applicationId di com.example.dynamicfeatureapp e il modulo della funzionalità dinamica è denominato DynamicFeatureModule, il nome del pacchetto del modulo dinamico sarà com.example.dynamicfeatureapp.DynamicFeatureModule. Questo nome del pacchetto è sensibile alle maiuscole.
In caso di dubbi, puoi confermare il nome di pacchetto del modulo della funzionalità controllando il file AndroidManifest.xml generato.
Dopo aver creato il progetto, vai a <DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml, che dovrebbe avere un aspetto simile a questo:
<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>
Il valore featureSplit deve corrispondere al nome del modulo della funzionalità dinamica e il pacchetto corrisponderà al applicationId del modulo dell'app di base. app:graphPackage è la combinazione di:
com.example.dynamicfeatureapp.DynamicFeatureModule.
Navigazione a un grafico di navigazione include-dynamic
È possibile navigare solo verso startDestination di un grafico di navigazione include-dynamic. Il modulo dinamico è responsabile del proprio grafico di navigazione e l'app di base non ne è a conoscenza.
Il meccanismo include-dynamic consente al modulo dell'app di base di includere un grafico di navigazione nidificato definito all'interno del modulo dinamico. Questo grafico di navigazione nidificato si comporta come qualsiasi grafico di navigazione nidificato. Il grafico di navigazione principale (ovvero l'elemento principale del grafico nidificato) può definire solo il grafico di navigazione nidificato stesso come destinazione e non i relativi elementi secondari. Pertanto,
startDestination viene utilizzato quando il grafico include-dynamicnavigation è la
destinazione.
Limitazioni
- I grafici inclusi dinamicamente al momento non supportano i deep link.
- I grafici nidificati caricati dinamicamente (ovvero un elemento
<navigation>con unapp:moduleName) al momento non supportano i deep link.