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

O Toolbar da biblioteca do AndroidX oferece diferentes maneiras para os usuários interagirem com seu app. A seção Adicionar e processar ações descreve como definir uma ação, que pode ser um botão ou um item de menu. Este documento descreve 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 precisar mudar atividades ou fragmentos.
  • Um provedor de ações é uma ação que tem o próprio layout personalizado. Inicialmente, a ação aparece como um botão ou item de menu. Quando o usuário toca na ação, o provedor controla o comportamento dela de qualquer maneira que você 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 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. Também é possível definir visualizações e provedores de ação próprios.

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 sinalização collapseActionView indica como exibir o widget quando o usuário não estiver interagindo com ele. Se o widget estiver na barra de apps, ele o exibirá como um ícone. Se o widget estiver no menu flutuante, o app o exibirá como um item de menu. Quando o usuário interage com a visualização de ação, ela se expande para preencher a barra de apps.

Por exemplo, o código abaixo 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 o exibirá como o ícone especificado por android:icon. Se não houver espaço na barra de apps, o app vai adicionar a ação ao menu flutuante.

Imagem que mostra 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 item de menu, o widget é expandido para preencher a barra de ferramentas, permitindo que o usuário interaja com ele.

Imagem de uma visualização de pesquisa aberta quando a barra de pesquisa está em foco.
Figura 2. A visualização de pesquisa é aberta quando o foco da barra de pesquisa é selecionado.

Se você precisar configurar a ação, faça isso no callback onCreateOptionsMenu() da atividade. Você pode conferir a referência do objeto da visualização de ação chamando o método getActionView(). Por exemplo, o código a seguir usa a referência de 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 à expansão da visualização de ação

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ções. Se a subclasse de atividade modificar o método onOptionsItemSelected(), seu método de substituição precisará chamar super.onOptionsItemSelected() para que a superclasse possa expandir a visualização de ação.

Caso queira fazer algo quando a ação for aberta ou recolhida, defina uma classe que implemente MenuItem.OnActionExpandListener e transmita um membro dessa classe para setOnActionExpandListener(). Por exemplo, talvez você queira atualizar a atividade se uma visualização de ação for 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 do menu da barra de ferramentas, conforme descrito em Adicionar e processar ações. Adicione um atributo actionProviderClass e o defina como o nome da classe totalmente qualificado da classe do provedor de ações.

Por exemplo, o código a seguir declara um ShareActionProvider, que é um widget definido na biblioteca do AndroidX que permite que o 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, já que ShareActionProvider fornece os próprios gráficos. Se você estiver usando uma ação personalizada, declare um ícone.

Outros recursos

  • Consulte ShareActionProvider para conferir um exemplo de como adicionar uma ação de compartilhamento à barra de apps superior.
  • Consulte ActionProvider para saber mais sobre como criar um provedor de ações personalizadas.