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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Testar o Compose

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

Barra de apps →

O Toolbar da biblioteca AndroidX oferece diferentes maneiras de 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. 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 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 na ação, o provedor de ações controla o comportamento da ação da 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 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 as 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 exibir o widget quando o usuário não está interagindo com ele. Se o widget estiver na barra de apps, o app vai exibir o widget como um ícone. Se o widget estiver no menu flutuante, o app vai mostrar o widget 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 exibir o widget 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.

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.

Se você precisar configurar a ação, faça isso no callback onCreateOptionsMenu() da sua atividade. É possível extrair 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:

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)
}

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

Se você quer fazer algo quando a ação é expandida ou recolhida, pode definir uma classe que implementa MenuItem.OnActionExpandListener e transmitir um membro dessa classe para setOnActionExpandListener(). Por exemplo, talvez você queira atualizar a atividade com base em se uma visualização de ação está expandida ou recolhida. O snippet de código a seguir mostra como definir e transmitir um listener:

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
}

@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 como o nome de classe totalmente qualificado da classe do provedor de ações.

Por exemplo, o código a seguir declara um ShareActionProvider, 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 conferir 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 personalizado.