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" à interface 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 para destinos anteriores quando o botão "Voltar" é pressionado. No entanto, há casos em que o app precisa implementar um comportamento de retorno próprio para oferecer a melhor experiência do usuário possível.

Por exemplo, ao usar um WebView, convém modificar o comportamento padrão do botão "Voltar" para permitir que o usuário navegue 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 dispositivos Android. Para saber mais sobre esse recurso, confira Adicionar suporte ao gesto de volta preditivo.

Implementar a navegação de retorno personalizada

ComponentActivity, a classe de base de FragmentActivity e AppCompatActivity, permite controlar o comportamento do botão "Voltar" usando OnBackPressedDispatcher, que você pode extrair 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 está ativado, ou seja, isEnabled retorna true, o agente chama o método handleOnBackPressed do callback para processar o evento do botão "Voltar". É possível mudar o estado de ativação chamando setEnabled.

Os callbacks são adicionados usando os métodos addCallback. Recomendamos o uso do método addCallback(), que usa um LifecycleOwner. Isso garante que o OnBackPressedCallback seja adicionado somente quando o LifecycleOwner for Lifecycle.State.STARTED. A atividade também remove callbacks registrados quando o LifecycleOwner associado é destruído, o que evita vazamentos de memória e torna o LifecycleOwner adequado para uso em fragmentos ou outros proprietários de ciclo de vida que tenham um ciclo mais curto que o da 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 à que foram adicionados. O último callback adicionado é o primeiro a ter a chance de processar o evento do botão "Voltar". Por exemplo, se você adicionar três callbacks chamados one, two e three, nessa ordem, eles serão invocados na ordem three, two, one.

Os callbacks seguem o padrão Chain of Responsibility. Cada callback na cadeia é invocado apenas se o callback anterior não tiver sido ativado. Isso significa que, no exemplo anterior, o callback two só será invocado se o callback three não estiver ativado, e o callback one só será invocado se o callback two não estiver ativado.

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

Recomendamos mudar o estado ativado no OnBackPressedCallback para mudanças temporárias, já que isso mantém a ordem descrita acima. Isso é importante principalmente se você tiver callbacks registrados em vários proprietários de ciclo de vida aninhados.

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

Atividade onBackPressed()

Se você estiver usando onBackPressed() para processar eventos do botão "Voltar", recomendamos usar um OnBackPressedCallback. No entanto, se você não conseguir fazer essa alteração, as regras abaixo serão aplicáveis:

  • Todos os callbacks registrados usando 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.