Como usar a AppBar

A barra de apps superior proporciona um lugar consistente na parte superior da janela do app para exibir informações e ações da tela atual.

Ao usar fragmentos, a barra de apps pode ser implementada como uma ActionBar que pertence à atividade do host ou a uma barra de ferramentas no layout do fragmento. A propriedade da barra de apps varia de acordo com as necessidades do app.

Se todas as suas telas usam a mesma barra de apps que está sempre na parte superior e se estende pela largura da tela, você precisa usar uma barra de ações fornecida por tema hospedada pela atividade. O uso de barras de apps em temas ajuda a manter uma aparência consistente e oferece um local para hospedar menus de opção e um botão para cima.

Use uma barra de ferramentas hospedada pelo fragmento se você quiser ter mais controle sobre o tamanho, a posição e a animação da barra de apps em várias telas. Por exemplo, talvez você precise de uma barra de apps recolhível ou de uma que se estenda apenas até a metade da tela e seja centralizada verticalmente.

Entender as diferentes abordagens e empregar uma opção correta economiza tempo e ajuda a garantir que o app funcione corretamente. Diferentes situações exigem diferentes abordagens para aspectos como inflação de menus e resposta à interação do usuário.

Os exemplos neste tópico se referem a um ExampleFragment que contém um perfil editável. O fragmento infla o seguinte menu definido por XML na barra de apps:

<!-- sample_menu.xml -->
<menu
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/action_settings"
        android:icon="@drawable/ic_settings"
        android:title="@string/settings"
        app:showAsAction="ifRoom"/>
    <item
        android:id="@+id/action_done"
        android:icon="@drawable/ic_done"
        android:title="@string/done"
        app:showAsAction="ifRoom|withText"/>

</menu>

O menu contém duas opções: uma para navegar até uma tela de perfil e outra para salvar as mudanças feitas no perfil.

Barra de apps da atividade

A barra de apps geralmente é de propriedade da atividade do host. Quando a barra de apps pertence a uma atividade, os fragmentos podem interagir com ela substituindo os métodos de framework que são chamados durante a criação de fragmentos.

Registrar com atividades

Informe ao sistema que o fragmento da barra de apps está participando do preenchimento do menu de opções. Para fazer isso, chame setHasOptionsMenu(true) no método onCreate(Bundle) do fragmento, conforme mostrado no exemplo a seguir:

class ExampleFragment : Fragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setHasOptionsMenu(true)
    }
}

public class ExampleFragment extends Fragment {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setHasOptionsMenu(true);
    }
}

setHasOptionsMenu(true) informa ao sistema que seu fragmento quer receber callbacks relacionados ao menu. Quando ocorre um evento relacionado a um menu (criação, cliques e assim por diante), o método de gerenciamento de eventos é chamado na atividade antes de ser chamado no fragmento. Observe que a lógica do aplicativo não pode depender dessa ordem. Se vários fragmentos estiverem hospedados pela mesma atividade, cada um deles poderá fornecer opções de menu. Nesse caso, a ordem do callback depende da ordem em que os fragmentos foram adicionados.

Como inflar um menu

Para mesclar seu menu ao menu de opções da barra de apps, substitua onCreateOptionsMenu() no seu fragmento. Esse método recebe o menu da barra de apps atual e um MenuInflater como parâmetros. Use o inflador de menu para criar uma instância do menu do fragmento e mescle-a no menu atual, como mostrado no exemplo a seguir:

class ExampleFragment : Fragment() {
    ...

    override fun onCreateOptionsMenu(menu: Menu, inflater: MenuInflater) {
        inflater.inflate(R.menu.sample_menu, menu)
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public void onCreateOptionsMenu(@NonNull Menu menu, @NonNull MenuInflater inflater) {
       inflater.inflate(R.menu.sample_menu, menu);
    }
}

A Figura 2 mostra o menu atualizado.

Processamento de eventos de clique

Todos os fragmentos e atividades que participam no menu de opções podem responder aos toques. O onOptionsItemSelected() do fragmento recebe o item de menu selecionado como um parâmetro e retorna um booleano para indicar se o toque foi consumido ou não. Quando uma atividade ou um fragmento retorna true de onOptionsItemSelected(), nenhum outro fragmento participante recebe o callback.

Na sua implementação de onOptionsItemSelected(), use uma instrução switch no itemId do item do menu. Se o item selecionado for seu, processe o toque adequadamente e retorne true para indicar que o evento de clique foi processado. Se o item selecionado não for seu, chame a implementação de super. Por padrão, a implementação de super retorna o valor false para permitir que o processamento do menu continue.

class ExampleFragment : Fragment() {
    ...

    override fun onOptionsItemSelected(item: MenuItem): Boolean {
        return when (item.itemId) {
            R.id.action_settings -> {
                // navigate to settings screen
                true
            }
            R.id.action_done -> {
                // save profile changes
                true
            }
            else -> super.onOptionsItemSelected(item)
        }
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public boolean onOptionsItemSelected(@NonNull MenuItem item) {
        switch (item.getItemId()) {
            case R.id.action_settings:  {
                // navigate to settings screen
                return true;
            }
            case R.id.action_done: {
                // save profile changes
                return true;
            }
            default:
                return super.onOptionsItemSelected(item);
        }

    }

}

Modificar o menu de forma dinâmica

A lógica para ocultar ou mostrar um botão ou mudar o ícone precisa ser colocada em onPrepareOptionsMenu(). Esse método é chamado logo antes de cada instância exibida no menu.

Continuando com o exemplo anterior, o botão Salvar ficará invisível até que o usuário inicie a edição e desaparecerá depois que o usuário salvá-la. A adição dessa lógica a onPrepareOptionsMenu() garante que o menu sempre seja apresentado corretamente:

class ExampleFragment : Fragment() {
    ...

    override fun onPrepareOptionsMenu(menu: Menu){
        super.onPrepareOptionsMenu(menu)
        val item = menu.findItem(R.id.action_done)
        item.isVisible = isEditing
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public void onPrepareOptionsMenu(@NonNull Menu menu) {
        super.onPrepareOptionsMenu(menu);
        MenuItem item = menu.findItem(R.id.action_done);
        item.setVisible(isEditing);
    }
}

Quando você precisar atualizar o menu, como quando um usuário pressionar o botão Editar para editar as informações do perfil, chame invalidateOptionsMenu() na atividade do host para solicitar que o sistema chame onCreateOptionsMenu(). Após a invalidação, é possível fazer as atualizações em onCreateOptionsMenu(). Depois que o menu é inflado, o sistema chama onPrepareOptionsMenu() e atualiza o menu para refletir o estado atual do fragmento.

class ExampleFragment : Fragment() {
    ...

    fun updateOptionsMenu() {
        isEditing = !isEditing
        requireActivity().invalidateOptionsMenu()
    }
}

public class ExampleFragment extends Fragment {
    ...

    public void updateOptionsMenu() {
        isEditing = !isEditing;
        requireActivity().invalidateOptionsMenu();
    }
}

Barra de apps do fragmento

Se a maioria das telas do seu app não precisar de uma barra de apps ou se uma tela precisar de uma barra muito diferente, adicione uma Toolbar ao layout do fragmento. Embora você possa adicionar uma Toolbar em qualquer lugar dentro da hierarquia de visualização do fragmento, ela geralmente precisa ser mantida na parte superior da tela. Para usar a Toolbar no seu fragmento, forneça um ID e consiga uma referência a ele no fragmento, da mesma forma que você faria com qualquer outra visualização.

<androidx.appcompat.widget.Toolbar
    android:id="@+id/myToolbar"
    ... />

Ao usar uma barra de apps de um fragmento, é altamente recomendado o uso direto das APIs Toolbar. Não use setSupportActionBar() e as APIs de menu do Fragment, que são adequadas apenas para barras de apps de atividades.

Como inflar um menu

O método de conveniência inflateMenu(int) da Toolbar usa o ID de um recurso de menu como parâmetro. Para inflar um recurso de menu XML na barra de ferramentas, transmita o resId para esse método, conforme mostrado no exemplo a seguir:

class ExampleFragment : Fragment() {
    ...

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        ...

        viewBinding.myToolbar.inflateMenu(R.menu.sample_menu)
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        ...

        viewBinding.myToolbar.inflateMenu(R.menu.sample_menu);
    }

}

Para inflar outro recurso de menu XML, chame o método novamente com o resId do novo menu. Os novos itens são adicionados ao menu, e os itens existentes não são modificados nem removidos.

Se você quiser substituir o conjunto de menus existente, limpe o menu antes de chamar inflateMenu(int) com o ID do novo menu.

class ExampleFragment : Fragment() {
    ...

    fun clearToolbarMenu() {
        viewBinding.myToolbar.menu.clear()
    }
}

public class ExampleFragment extends Fragment {

    ...
    public void clearToolbarMenu() {

        viewBinding.myToolbar.getMenu().clear()

    }

}

Processamento de eventos de clique

Você pode transmitir um OnMenuItemClickListener diretamente para a barra de ferramentas usando o método setOnMenuItemClickListener(). Esse listener é invocado sempre que um usuário seleciona um item de menu usando os botões de ação apresentados no final da barra de ferramentas ou no menu flutuante associado. O MenuItem selecionado é transmitido para o método onMenuItemClick() do listener e pode ser usado para consumir a ação, conforme mostrado no exemplo a seguir:

class ExampleFragment : Fragment() {
    ...

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        ...

        viewBinding.myToolbar.setOnMenuItemClickListener {
            when (it.itemId) {
                R.id.action_settings -> {
                    // Navigate to settings screen
                    true
                }
                R.id.action_done -> {
                    // Save profile changes
                    true
                }
                else -> false
            }
        }
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        ...

        viewBinding.myToolbar.setOnMenuItemClickListener(item -> {
            switch (item.getItemId()) {
                case R.id.action_settings:
                    // Navigate to settings screen
                    return true;
                case R.id.action_done:
                    // Save profile changes
                    return true;
                default:
                    return false;
            }
        });
    }
}

Modificar o menu de forma dinâmica

Quando seu fragmento é proprietário da barra de apps, você pode modificar a Toolbar no ambiente de execução da mesma forma que faria com qualquer outra visualização.

Continuando com o exemplo anterior, a opção de menu Salvar ficará invisível até o usuário iniciar a edição, desaparecendo novamente depois que for pressionada:

class ExampleFragment : Fragment() {
    ...

    fun updateToolbar() {
        isEditing = !isEditing

        val saveItem = viewBinding.myToolbar.menu.findItem(R.id.action_done)
        saveItem.isVisible = isEditing

    }
}

public class ExampleFragment extends Fragment {
    ...

    public void updateToolbar() {
        isEditing = !isEditing;

        MenuItem saveItem = viewBinding.myToolbar.getMenu().findItem(R.id.action_done);
        saveItem.setVisible(isEditing);
    }

}

Como adicionar um ícone de navegação

Se estiver presente, o botão de navegação aparecerá no início da barra de ferramentas. Quando você define um ícone de navegação na barra de ferramentas, ela fica visível. Você também pode definir um onClickListener() específico de navegação, que será chamado sempre que o usuário clicar no botão de navegação, conforme mostrado no exemplo a seguir:

class ExampleFragment : Fragment() {
    ...

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        ...

        myToolbar.setNavigationIcon(R.drawable.ic_back)

        myToolbar.setNavigationOnClickListener { view ->
            // Navigate somewhere
        }
    }
}

public class ExampleFragment extends Fragment {
    ...

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        ...

        viewBinding.myToolbar.setNavigationIcon(R.drawable.ic_back);
        viewBinding.myToolbar.setNavigationOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                // Navigate somewhere
            }
        });
    }
}