Usar provedores e visualizações de ação

Experimente trabalhar com o Compose
O Jetpack Compose é o kit de ferramentas de UI recomendado para Android. Saiba como adicionar componentes no Compose.
Barra de apps →

A Toolbar da biblioteca AndroidX oferece diferentes maneiras para os usuários interagirem com seu app. Adicionar e processar ações descreve como definir uma ação, que pode ser um botão ou um item de menu. Neste documento, descrevemos como adicionar dois componentes versáteis:

  • Uma visualização de ação oferece recursos avançados na barra de apps. Por exemplo, uma visualização de ação de pesquisa permite que o usuário digite o texto de pesquisa na barra de apps sem ter que mudar atividades ou fragmentos.
  • Um provedor de ações é uma ação que tem o próprio layout personalizado. A ação aparece inicialmente como um botão ou item de menu. Quando o usuário toca nela, o provedor de ações controla o comportamento resultante da maneira que você quiser definir. Por exemplo, o provedor de ações pode responder a um toque exibindo um menu.

O AndroidX oferece vários widgets especializados de visualização de ação e de provedor de ações. Por exemplo, o widget SearchView implementa uma visualização de ação para inserir consultas de pesquisa. O widget ShareActionProvider implementa um provedor de ações para compartilhar informações com outros apps. Você também pode definir suas próprias visualizações e provedores de ações.

Adicionar uma visualização de ação

Para adicionar uma visualização de ação, crie um elemento <item> no recurso de menu da barra de ferramentas, conforme descrito em Adicionar e processar ações. Adicione um dos seguintes atributos ao elemento <item>:

  • actionViewClass: a classe de um widget que implementa a ação
  • actionLayout: um recurso de layout que descreve os componentes da ação.

Defina o atributo showAsAction como "ifRoom|collapseActionView" ou "never|collapseActionView". A flag collapseActionView indica como mostrar o widget quando o usuário não está interagindo com ele. Se o widget estiver na barra de apps, o app vai mostrar o widget como um ícone. Se o widget estiver no menu flutuante, o app vai exibi-lo como um item de menu. Quando o usuário interage com a visualização de ação, ela é expandida para preencher a barra de apps.

Por exemplo, o código a seguir adiciona um widget SearchView à barra de apps:

<item android:id="@+id/action_search"
     android:title="@string/action_search"
     android:icon="@drawable/ic_search"
     app:showAsAction="ifRoom|collapseActionView"
     app:actionViewClass="androidx.appcompat.widget.SearchView" />

Se o usuário não estiver interagindo com o widget, o app vai mostrar o widget como o ícone especificado por android:icon. Se não houver espaço na barra de apps, o app adicionará a ação ao menu flutuante.

Imagem mostrando uma barra de pesquisa com ícones à esquerda e à direita.
Figura 1. Barra de pesquisa com ícones à esquerda e à direita.

Quando o usuário toca no ícone ou no item de menu, o widget se expande para preencher a barra de ferramentas, permitindo que o usuário interaja com ele.

Uma imagem mostrando uma visualização de pesquisa aberta depois que a barra de pesquisa é focada.
Figura 2. A visualização de pesquisa é aberta quando a barra de pesquisa está em foco.

Se você precisar, configure a ação no callback onCreateOptionsMenu() da sua atividade. Você pode ver a referência de objeto da visualização de ação chamando o método getActionView(). Por exemplo, o código a seguir usa a referência do objeto para o widget SearchView definido no exemplo de código anterior:

Kotlin

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
    menuInflater.inflate(R.menu.main_activity_actions, menu)

    val searchItem = menu?.findItem(R.id.action_search)
    val searchView = searchItem?.actionView as SearchView

    // Configure the search info and add any event listeners.

    return super.onCreateOptionsMenu(menu)
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.main_activity_actions, menu);

    MenuItem searchItem = menu.findItem(R.id.action_search);
    SearchView searchView =
            (SearchView) searchItem.getActionView();

    // Configure the search info and add any event listeners.

    return super.onCreateOptionsMenu(menu);
}

Responder a uma visualização de ação expandida

Se o elemento <item> da ação tiver uma flag collapseActionView, o app vai mostrar a visualização de ação como um ícone até que o usuário interaja com ela. Quando o usuário toca no ícone, o gerenciador integrado de onOptionsItemSelected() expande a visualização de ação. Se a subclasse de atividade modificar o método onOptionsItemSelected(), o método modificado precisará chamar super.onOptionsItemSelected() para que a superclasse possa expandir a visualização de ação.

Se você quiser fazer algo quando a ação é expandida ou recolhida, defina uma classe que implemente MenuItem.OnActionExpandListener e transmita um membro dessa classe para setOnActionExpandListener(). Por exemplo, é possível que você queira atualizar a atividade depois que uma visualização de ação é expandida ou recolhida. O snippet de código a seguir mostra como definir e transmitir um listener:

Kotlin

override fun onCreateOptionsMenu(menu: Menu?): Boolean {
    menuInflater.inflate(R.menu.options, menu)

    // Define the listener.
    val expandListener = object : MenuItem.OnActionExpandListener {
        override fun onMenuItemActionCollapse(item: MenuItem): Boolean {
            // Do something when the action item collapses.
            return true // Return true to collapse the action view.
        }

        override fun onMenuItemActionExpand(item: MenuItem): Boolean {
            // Do something when it expands.
            return true // Return true to expand the action view.
        }
    }

    // Get the MenuItem for the action item.
    val actionMenuItem = menu?.findItem(R.id.myActionItem)

    // Assign the listener to that action item.
    actionMenuItem?.setOnActionExpandListener(expandListener)

    // For anything else you have to do when creating the options menu,
    // do the following:

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.options, menu);

    // Define the listener.
    OnActionExpandListener expandListener = new OnActionExpandListener() {
        @Override
        public boolean onMenuItemActionCollapse(MenuItem item) {
            // Do something when the action item collapses.
            return true;  // Return true to collapse action view.
        }

        @Override
        public boolean onMenuItemActionExpand(MenuItem item) {
            // Do something when it expands.
            return true;  // Return true to expand the action view.
        }
    };

    // Get the MenuItem for the action item.
    MenuItem actionMenuItem = menu.findItem(R.id.myActionItem);

    // Assign the listener to that action item.
    MenuItemCompat.setOnActionExpandListener(actionMenuItem, expandListener);

    // For anything else you have to do when creating the options menu,
    // do the following:

    return true;
}

Adicionar um provedor de ações

Para declarar um provedor de ações, crie um elemento <item> no recurso de menu da barra de ferramentas, conforme descrito em Adicionar e processar ações. Adicione um atributo actionProviderClass e configure-o com o nome de classe totalmente qualificado para a classe do provedor de ações.

Por exemplo, o código a seguir declara um ShareActionProvider, que é um widget definido na biblioteca AndroidX que permite que seu app compartilhe dados com outros apps:

<item android:id="@+id/action_share"
    android:title="@string/share"
    app:showAsAction="ifRoom"
    app:actionProviderClass="androidx.appcompat.widget.ShareActionProvider"/>

Nesse caso, não é necessário declarar um ícone para o widget, porque ShareActionProvider disponibiliza os próprios gráficos. Se você estiver usando uma ação personalizada, declare um ícone.

Outros recursos

  • Consulte ShareActionProvider para um exemplo de como adicionar uma ação de compartilhamento à barra de apps na parte de cima.
  • Consulte ActionProvider para mais informações sobre como criar um provedor de ações personalizadas.