Fornecer navegação personalizada no sentido contrário

A navegação de retorno é a forma como os usuários se movem para trás no histórico de telas que eles visitaram anteriormente. Todos os dispositivos Android oferecem um botão "Voltar" para esse tipo de navegação. Portanto, não adicione um botão "Voltar" à IU do app. Dependendo do dispositivo Android do usuário, esse botão pode ser um botão físico ou de software.

O Android mantém uma pilha de retorno de destinos à medida que o usuário navega no seu app. Isso permite que o Android navegue corretamente destinos anteriores quando o botão "Voltar" é pressionado. No entanto, existem algumas casos em que o app precise implementar o próprio comportamento de retorno para para oferecer a melhor experiência possível ao usuário.

Por exemplo, ao usar WebView, substitua o comportamento padrão do botão "Voltar" para permitir que o usuário navegar de volta pelo histórico de navegação da Web em vez das telas anteriores; no seu app.

O Android 13 e versões mais recentes incluem um gesto de volta preditivo para os dispositivos Android. Para Saiba mais sobre esse recurso em Adicionar suporte para o gesto de volta preditivo.

Implementar a navegação de retorno personalizada

ComponentActivity, a base classe para FragmentActivity e AppCompatActivity, permite que você controle o comportamento do botão Voltar usando o OnBackPressedDispatcher, que você pode recuperar chamando getOnBackPressedDispatcher().

O OnBackPressedDispatcher controla como os eventos do botão "Voltar" são enviados para um ou mais objetos OnBackPressedCallback. O construtor de OnBackPressedCallback aceita um valor booleano para o estado inicial ativado. Quando um callback é ativado, ou seja, isEnabled() retorna true, o agente chama o método handleOnBackPressed() para processar o evento do botão "Voltar". Você pode alterar o estado ativado chamando setEnabled().

Os callbacks são adicionados usando os métodos addCallback. Recomendamos usar addCallback() que usa um LifecycleOwner. Isso garante que OnBackPressedCallback seja adicionado somente quando LifecycleOwner for Lifecycle.State.STARTED. A atividade também remove callbacks registrados quando os LifecycleOwner é destruído, o que evita vazamentos de memória e faz com que LifecycleOwner adequado para uso em fragmentos ou outros proprietários de ciclo de vida que tenham um ciclo de vida mais curto do que a atividade.

Confira um exemplo de implementação de callback:

Kotlin

class MyFragment : Fragment() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // This callback is only called when MyFragment is at least started
        val callback = requireActivity().onBackPressedDispatcher.addCallback(this) {
            // Handle the back button event
        }

        // The callback can be enabled or disabled here or in the lambda
    }
    ...
}

Java

public class MyFragment extends Fragment {

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // This callback is only called when MyFragment is at least started
        OnBackPressedCallback callback = new OnBackPressedCallback(true /* enabled by default */) {
            @Override
            public void handleOnBackPressed() {
                // Handle the back button event
            }
        };
        requireActivity().getOnBackPressedDispatcher().addCallback(this, callback);

        // The callback can be enabled or disabled here or in handleOnBackPressed()
    }
    ...
}

É possível fornecer vários callbacks usando addCallback(). Quando você faz isso, os callbacks são invocados na ordem inversa em relação à ordem em que você adicioná-los: o retorno de chamada adicionado por último é o primeiro com a chance de lidar com o Evento do botão "Voltar". Por exemplo, se você adicionar três callbacks chamados one, two e three, nessa ordem, são invocados na ordem three, two e one.

Os callbacks seguem o padrão Cadeia de responsabilidade. Cada callback na cadeia será invocado somente se o callback anterior não tiver sido ativado. Isso significa que, exemplo anterior, o callback two é invocado somente se o callback three não está ativado, e o callback one só será invocado se o callback two não está ativado.

Quando o callback é adicionado usando addCallback(), ela não é adicionada à cadeia de responsabilidade até que LifecycleOwner entra no estado Lifecycle.State.STARTED.

Recomendamos mudar o estado ativado no OnBackPressedCallback para alterações temporárias, pois isso mantém a ordem descrita acima. Isto é especialmente importante se você tem retornos de chamada registrados em vários proprietários de ciclo de vida aninhados.

Nos casos em que você quiser remover OnBackPressedCallback completamente, Você pode chamar remove(). Isso geralmente não é necessário, porque os callbacks são removidos automaticamente quando o LifecycleOwner associado a ele é destruídos.

Atividade onBackPressed()

Se você estiver usando onBackPressed() para processar eventos do botão "Voltar", recomendamos o uso de um OnBackPressedCallback. No entanto, se não for possível fazer essa alteração, as seguintes regras serão aplicadas:

  • Todos os callbacks registrados por addCallback serão avaliados quando você chamar super.onBackPressed().
  • No Android 12 (nível 32 da API) e em versões anteriores, onBackPressed é sempre chamado, independente de qualquer instância registrada de OnBackPressedCallback.