Práticas recomendadas para interação de navegação com o mapa

Esta página explica as práticas recomendadas para interagir com o mapa de navegação no app.

Use NavigationFragment em vez de NavigationView sempre que possível

O NavigationFragment encapsula o NavigationView e processa automaticamente os callbacks do ciclo de vida dele. Assim, você não precisa gerenciar esses callbacks. Essa abordagem é menos propensa a erros e é a maneira recomendada de usar a navegação no app. Ao usar NavigationFragment, não invoque eventos de ciclo de vida NavigationView diretamente.

Se estiver usando NavigationView, use a ordenação estrita ao invocar métodos de ciclo de vida

O NavigationView hospeda o mapa de navegação e segue de perto os eventos do ciclo de vida como atividades e fragmentos do Android, tomando ações específicas quando esses eventos do ciclo de vida são invocados. O NavigationView executa várias inicializações em NavigationView#onCreate e NavigationView#onStart, além de limpezas em NavigationView#onStop e NavigationView#onDestroy, e quando outros eventos do ciclo de vida são processados.

Os métodos de ciclo de vida de NavigationView têm o mesmo significado que em atividades ou fragmentos do Android. Por exemplo, onCreate de NavigationView é aproximadamente traduzido e precisa ser invocado por callbacks do ciclo de vida da atividade ou do fragmento do Android. Como os callbacks do ciclo de vida do NavigationView são baseados e invocados na mesma ordem dos callbacks do ciclo de vida do Android, é necessário um ordenamento estrito desses métodos do NavigationView. Caso contrário, você pode ter vazamentos de memória, erros de interface, localização não atualizada e outros problemas.

Para mais informações sobre o ciclo de vida da atividade do Android, consulte a seção Conceitos do ciclo de vida da atividade na documentação para desenvolvedores Android.

A tabela a seguir mostra quando outros métodos de ciclo de vida devem ser invocados após métodos de ciclo de vida especificados:

Não chame esses métodos do ciclo de vida várias vezes sem chamar o método de fechamento correspondente primeiro. Além disso, se alguns desses callbacks do ciclo de vida do Android forem gerenciados pelo próprio app, e o NavigationView for adicionado ao fragmento após a criação ou o início, o app precisará chamar os métodos específicos na ordem correta para inicializar o SDK Navigation.

Para mais orientações sobre como usar esses métodos, consulte o app de demonstração do SDK Navigation.

Se você estiver usando NavigationView, invoque eventos de ciclo de vida da atividade ou do fragmento, não de ambos.

Para manter a ordem estrita dos métodos de ciclo de vida, invoque esses eventos nos callbacks de ciclo de vida da atividade ou do fragmento, que recebem esses eventos em ordem. Essa abordagem garante que os apps não precisem coordenar entre fragmentos e atividades e causar chamadas duplicadas.

Atualização de SupportNavigationFragment para NavigationFragment

A partir do SDK Navigation v8.0.0, NavigationFragment substitui o descontinuado SupportNavigationFragment como o contêiner de fragmentos padrão para navegação guiada e exibição de mapa.

O NavigationFragment mantém a paridade total de API com o SupportNavigationFragment. Para atualizar o app, substitua SupportNavigationFragment por NavigationFragment nos arquivos de layout XML e nas importações de código-fonte. Todas as assinaturas de método e chamadas getSupportFragmentManager() permanecem idênticas.

Atualizar o XML de layout

Substitua SupportNavigationFragment por NavigationFragment nos arquivos XML de layout:

Antes (v7.x e versões anteriores):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Depois (v8.0.0 ou mais recente):

<fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Se o app usa FragmentContainerView (recomendado para hospedagem de fragmentos), atualize o atributo android:name:

<androidx.fragment.app.FragmentContainerView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/navigation_fragment"
    android:name="com.google.android.libraries.navigation.NavigationFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Atualizar o código do aplicativo

Substitua importações e conversões de classe no seu código Java ou Kotlin. Como as duas classes estendem androidx.fragment.app.Fragment, continue usando getSupportFragmentManager() para pesquisar o fragmento:

Antes (v7.x e versões anteriores):

import com.google.android.libraries.navigation.SupportNavigationFragment;

public class MainActivity extends AppCompatActivity {
  private SupportNavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (SupportNavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.SupportNavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: SupportNavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as SupportNavigationFragment
  }
}
    

Depois (v8.0.0 ou mais recente):

import com.google.android.libraries.navigation.NavigationFragment;

public class MainActivity extends AppCompatActivity {
  private NavigationFragment mNavFragment;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    mNavFragment = (NavigationFragment) getSupportFragmentManager()
        .findFragmentById(R.id.navigation_fragment);
  }
}
    

import com.google.android.libraries.navigation.NavigationFragment

class MainActivity : AppCompatActivity() {
  private lateinit var navFragment: NavigationFragment

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    navFragment = supportFragmentManager
        .findFragmentById(R.id.navigation_fragment) as NavigationFragment
  }
}
    

Paridade de API

Não é necessário fazer outras mudanças de comportamento nem reestruturar o código. O NavigationFragment é compatível com todos os métodos públicos, interfaces de listener e controles de interface personalizados do SupportNavigationFragment com assinaturas de método idênticas (incluindo getMapAsync(), getNavigator(), setEtaCardEnabled() e setStylingOptions()).