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

O recurso da biblioteca do AndroidX O Toolbar oferece maneiras diferentes de os usuários interagirem com seu app. O artigo 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. Para 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 para 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 de ações controla o comportamento da ação da maneira que você definir. Por exemplo, o provedor de ações pode responder tocar, exibindo um menu.

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

Adicionar uma visualização de ação

Para adicionar uma visualização de ação, crie uma <item> no recurso de menu da barra de ferramentas, como descrito em Adicionar e processar ações. Adicione um dos atributos a seguir à 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, exibe 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 se expande 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 à 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 que o usuário interaja com ele.

Se você precisar configurar a ação, faça isso no onCreateOptionsMenu() o retorno de chamada. Você pode obter a referência de objeto da visualização de ação chamando o getActionView() . Por exemplo, o código a seguir usa a referência de objeto para o 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 de visualização da ação

Se o elemento <item> da ação tiver uma sinalização collapseActionView, o mostra 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 manipulador integrado para onOptionsItemSelected() expande a visualização da ação. Se sua subclasse de atividade substitui a onOptionsItemSelected(), seu método de substituição precisa chamar super.onOptionsItemSelected() para que a superclasse possa expandir a visualização de ação.

Se você quiser fazer algo quando a ação for expandida ou recolhida, será possível definir uma classe que implements MenuItem.OnActionExpandListener, e passar um membro dessa classe para setOnActionExpandListener(). Por exemplo, talvez você queira atualizar a atividade dependendo se uma visualização de ações é expandida ou recolhido. 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 menu da barra de ferramentas conforme descrito em Adicionar e processar ações. Adicione um actionProviderClass e o defina como o nome de classe totalmente qualificado da classe de provedor de ações.

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

Outros recursos

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