A biblioteca Dynamic Navigator estende a funcionalidade do componente de navegação do Jetpack para trabalhar com destinos definidos em módulos de recursos. Essa biblioteca também oferece uma instalação simples de módulos de recursos on demand ao navegar para esses destinos.
Configuração
Para oferecer suporte a módulos de recursos, use as seguintes dependências no arquivo build.gradle do módulo do 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") }
Observe que as outras dependências de navegação precisam usar configurações de API (link em inglês) para ficarem disponíveis para os módulos de recursos.
Uso básico
Para oferecer suporte a módulos de recursos, primeiro mude todas as instâncias de
NavHostFragment no app para
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"
... />
Em seguida, adicione um atributo app:moduleName para qualquer destino <activity>, <fragment> ou
<navigation> nos gráficos
de navegação de um módulo com.android.dynamic-feature associados a um DynamicNavHostFragment.
Esse atributo informa à biblioteca Dynamic Navigator que o destino
pertence a um módulo de recurso com o nome especificado por você.
<fragment
app:moduleName="myDynamicFeature"
android:id="@+id/featureFragment"
android:name="com.google.android.samples.feature.FeatureFragment"
... />
Quando você navega para um desses destinos, a biblioteca Dynamic Navigator confere primeiro se o módulo de recursos está instalado. Se o módulo de recursos já estiver presente, o app navegará para o destino conforme o esperado. Se o módulo não estiver presente, o app mostrará um destino de fragmento de progresso intermediário à medida que o módulo é instalado. A implementação padrão do fragmento de progresso mostra uma IU básica com uma barra de progresso e processa todos os erros de instalação.
Para personalizar essa interface ou processar manualmente o progresso da instalação na tela do seu app, consulte as seções Personalizar o fragmento de progresso e Monitorar o estado da solicitação neste tópico.
Os destinos que não especificam app:moduleName continuam funcionando sem
alterações e se comportam como se o app estivesse usando um NavHostFragment normal.
Personalizar o fragmento de progresso
É possível substituir a implementação do fragmento de progresso para cada gráfico de navegação
definindo o atributo app:progressDestination como o ID do destino
que você quer usar para processar o progresso da instalação. O destino de progresso personalizado
precisa ser um Fragment que deriva de
AbstractProgressFragment. É necessário substituir os métodos abstratos para
notificações sobre o progresso da instalação, erros e outros eventos. Em seguida,
você pode mostrar o progresso da instalação em uma interface de sua escolha.
A classe DefaultProgressFragment da implementação padrão usa essa API
para mostrar o progresso da instalação.
Monitorar o estado da solicitação
A biblioteca Dynamic Navigator permite implementar um fluxo de UX semelhante ao descrito em Práticas recomendadas de UX para entrega on demand, em que o usuário permanece no contexto de uma tela anterior enquanto aguarda a conclusão da instalação. Isso significa que não é necessário mostrar uma interface intermediária ou um fragmento de progresso.
Nesse cenário, você é responsável por monitorar e processar todos os estados de instalação, incluindo mudanças de progresso e erros.
Para iniciar esse fluxo de navegação sem bloqueio, transmita um objeto DynamicExtras
que contenha um DynamicInstallMonitor para
NavController.navigate(), conforme mostrado no exemplo a seguir:
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);
)
Imediatamente após chamar navigate(), verifique o valor de
installMonitor.isInstallRequired para ver se a tentativa de navegação resultou
em uma instalação do módulo de recurso.
- Se o valor for
false, você estará navegando para um destino normal e não precisará fazer mais nada. Se o valor for
true, comece a observar o objetoLiveDataque agora está eminstallMonitor.status. Esse objetoLiveDataemite atualizações deSplitInstallSessionStateda biblioteca Play Core. Essas atualizações contêm eventos de progresso da instalação que podem ser usados para atualizar a interface. Lembre-se de processar todos os status relevantes, conforme descrito no guia do Play Core, incluindo solicitar a confirmação do usuário, se necessário.
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);
}
}
});
}
Quando a instalação é concluída, o objeto LiveData emite um status SplitInstallSessionStatus.INSTALLED. Em seguida, chame
NavController.navigate() novamente. Como agora o módulo está instalado, a chamada
será bem-sucedida e o app navegará para o destino conforme o esperado.
Depois de alcançar um estado terminal, como quando a instalação é concluída ou quando
a instalação falha, remova o observador LiveData para evitar vazamentos
de memória. É possível verificar se o status representa um estado de terminal usando
SplitInstallSessionStatus.hasTerminalStatus().
Consulte AbstractProgressFragment para ver um exemplo de implementação desse
observador.
Gráficos incluídos
A biblioteca Dynamic Navigator é compatível com a inclusão de gráficos definidos em módulos de recursos. Para incluir um gráfico definido em um módulo de recursos, faça o seguinte:
Use
<include-dynamic/>em vez de<include/>, como mostrado no exemplo a seguir:<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" />Dentro de
<include-dynamic ... />, você precisa especificar os seguintes atributos:app:graphResName: o nome do arquivo de recursos do gráfico de navegação. O nome é derivado do nome de arquivo do gráfico. Por exemplo, se o gráfico estiver emres/navigation/nav_graph.xml, o nome do recurso seránav_graph.android:id: ID do gráfico de destino. A biblioteca Dynamic Navigator ignora todos os valoresandroid:idencontrados no elemento raiz do gráfico incluído.app:moduleName: nome do pacote do módulo.
Usar o graphPackage correto
É importante que o app:graphPackage esteja correto, porque, caso contrário, o componente de navegação
não poderá incluir o navGraph especificado do módulo de
recurso.
O nome do pacote para um módulo de recurso dinâmico é composto pelo
nome do módulo unido ao applicationId do módulo do app base. Assim, se o
módulo do app base tiver com.example.dynamicfeatureapp como a propriedade applicationId, e
o módulo do recurso dinâmico for chamado de DynamicFeatureModule, o nome do
pacote para o módulo dinâmico será
com.example.dynamicfeatureapp.DynamicFeatureModule. Esse nome de pacote
diferencia maiúsculas de minúsculas.
Se tiver dúvidas, confirme o nome do pacote do módulo de recurso
verificando o AndroidManifest.xml gerado.
Depois de criar o projeto, acesse
<DynamicFeatureModule>/build/intermediates/merged_manifest/debug/AndroidManifest.xml,
que será parecido com este:
<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>
O valor featureSplit precisa corresponder ao nome do módulo de recurso dinâmico,
e o pacote precisa corresponder ao applicationId do módulo de app de base. O
app:graphPackage é a combinação de:
com.example.dynamicfeatureapp.DynamicFeatureModule.
Como acessar um gráfico de navegação com inclusão dinâmica
Só é possível acessar o startDestination de um
gráfico de navegação include-dynamic. O módulo dinâmico é responsável pelo
próprio gráfico de navegação, e o app base não tem conhecimento disso.
O mecanismo de inclusão dinâmica permite que o módulo base do app inclua um gráfico de navegação
aninhado definido no módulo dinâmico. Esse gráfico de navegação
aninhado se comporta como qualquer outro. O gráfico de navegação raiz (ou seja, o pai do gráfico aninhado) só pode definir o próprio gráfico de navegação aninhado como destino, não os filhos dele. Assim, o
startDestination é usado quando o gráfico include-dynamicnavigation é o
destino.
Limitações
- Os gráficos incluídos dinamicamente não são compatíveis com links diretos.
- Gráficos aninhados carregados dinamicamente (ou seja, um elemento
<navigation>com umapp:moduleName) não são compatíveis com links diretos atualmente.