Adicionar e gerenciar ações

Testar o Compose

O Jetpack Compose é o kit de ferramentas de interface recomendado para Android. Aprenda a adicionar componentes no Compose.

Barra de apps na parte de cima dinâmica →

A barra de apps permite adicionar botões para ações do usuário. Com esse recurso, é possível colocar as ações mais importantes para o contexto atual na parte de cima do app. Por exemplo, um app para procurar fotos pode mostrar os botões compartilhar e criar álbum na parte de cima quando o usuário está vendo o rolo de fotos. Quando o usuário olha para uma foto individual, o app pode mostrar os botões crop e filter.

O espaço na barra de apps é limitado. Se um app declarar ações demais na barra de apps, ela enviará as ações em excesso para um menu flutuante. O app também pode especificar que uma ação sempre aparece no menu flutuante, em vez de aparecer na barra de apps.

Figura 1. Um ícone de ação no app "Now in Android".

Adicionar botões de ação

Todos os botões de ação e outros itens disponíveis no menu flutuante são definidos em um recurso de menu XML. Para adicionar ações à barra de ação, crie um novo arquivo XML no diretório res/menu/ do projeto.

Adicione um elemento <item> para cada item que você quer incluir na barra de ação, conforme mostrado no arquivo XML de menu de exemplo abaixo:

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

    <!-- "Mark Favorite", must appear as action button if possible. -->
    <item
        android:id="@+id/action_favorite"
        android:icon="@drawable/ic_favorite_black_48dp"
        android:title="@string/action_favorite"
        app:showAsAction="ifRoom"/>

    <!-- Settings, must always be in the overflow. -->
    <item android:id="@+id/action_settings"
          android:title="@string/action_settings"
          app:showAsAction="never"/>

</menu>

O atributo app:showAsAction especifica se a ação é mostrada como um botão na barra de apps. Se você definir app:showAsAction="ifRoom", como na ação favorite do código de exemplo, a ação será exibida como um botão se houver espaço na barra de apps. Se não houver espaço suficiente, as ações em excesso serão enviadas para o menu flutuante. Se você definir app:showAsAction="never", como na ação settings do código de exemplo, a ação será sempre listada no menu flutuante e não será exibida na barra de apps.

Se a ação for exibida na barra de apps, o sistema vai usar o ícone dela como botão de ação. Você pode encontrar muitos ícones úteis em Ícones do Material Design (link em inglês).

Responder a ações

Quando o usuário seleciona um dos itens da barra de apps, o sistema chama o método de callback onOptionsItemSelected() da atividade e transmite um objeto MenuItem para indicar qual item foi tocado. Na implementação de onOptionsItemSelected(), chame o método MenuItem.getItemId() para determinar qual item foi tocado. O ID retornado corresponde ao valor declarado no atributo android:id do elemento <item> correspondente.

Por exemplo, o snippet de código a seguir verifica qual ação o usuário seleciona. Se o método não reconhecer a ação do usuário, ele invocará o método da superclasse:

Kotlin

override fun onOptionsItemSelected(item: MenuItem) = when (item.itemId) {
    R.id.action_settings -> {
        // User chooses the "Settings" item. Show the app settings UI.
        true
    }

    R.id.action_favorite -> {
        // User chooses the "Favorite" action. Mark the current item as a
        // favorite.
        true
    }

    else -> {
        // The user's action isn't recognized.
        // Invoke the superclass to handle it.
        super.onOptionsItemSelected(item)
    }
}

Java

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    switch (item.getItemId()) {
        case R.id.action_settings:
            // User chooses the "Settings" item. Show the app settings UI.
            return true;

        case R.id.action_favorite:
            // User chooses the "Favorite" action. Mark the current item as a
            // favorite.
            return true;

        default:
            // The user's action isn't recognized.
            // Invoke the superclass to handle it.
            return super.onOptionsItemSelected(item);

    }
}