Cómo usar vistas y proveedores de acciones

El Toolbar de la biblioteca de AndroidX proporciona diferentes maneras para que los usuarios interactúen con tu app. En Cómo agregar y controlar acciones, se describe cómo definir una acción, que puede ser un botón o un elemento de menú. En este documento, se describe cómo agregar dos componentes versátiles:

  • Una vista de acción es una acción que proporciona una funcionalidad enriquecida dentro de la barra de la app. Por ejemplo, una vista de acción de búsqueda le permite al usuario escribir su texto de búsqueda en la barra de la app sin tener que cambiar actividades ni fragmentos.
  • Un proveedor de acciones es una acción con su propio diseño personalizado. Inicialmente, la acción aparece como un botón o un elemento de menú. Cuando el usuario presiona la acción, el proveedor de acciones controla el comportamiento de la acción de la manera que tú definas. Por ejemplo, el proveedor de acciones puede responder a un toque mostrando un menú.

AndroidX proporciona varias vistas de acción especializadas y widgets de proveedor de acciones. Por ejemplo, el widget SearchView implementa una vista de acción para ingresar búsquedas. El widget ShareActionProvider implementa un proveedor de acciones para compartir información con otras apps. También puedes definir tus propias vistas y proveedores de acciones.

Cómo agregar una vista de acción

Para agregar una vista de acción, crea un elemento <item> en el recurso de menú de la barra de herramientas, como se describe en Cómo agregar y controlar acciones. Agrega uno de los siguientes atributos al elemento <item>:

  • actionViewClass: Es la clase de un widget que implementa la acción.
  • actionLayout: Es un recurso de diseño que describe los componentes de la acción.

Establece el atributo showAsAction en "ifRoom|collapseActionView" o "never|collapseActionView". La marca collapseActionView indica cómo mostrar el widget cuando el usuario no está interactuando con él. Si el widget está en la barra de la app, la app lo muestra como un ícono. Si el widget está en el menú ampliado, la app lo muestra como un elemento de menú. Cuando el usuario interactúa con la vista de acción, esta se expande para llenar la barra de la app.

Por ejemplo, en el siguiente código, se agrega un widget SearchView a la barra de la app:

<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" />

Si el usuario no está interactuando con el widget, la app muestra el widget como el ícono especificado por android:icon. Si no hay espacio en la barra de la app, esta agrega la acción al Menú ampliado.

Imagen que muestra una barra de búsqueda con íconos iniciales y finales.
Figura 1: Barra de búsqueda con íconos al principio y al final

Cuando el usuario presiona el ícono o elemento de menú, el widget se expande para llenar la barra de herramientas, lo que le permite al usuario interactuar con él.

Imagen que muestra una vista de búsqueda abierta una vez que se enfoca la barra de búsqueda.
Figura 2: Se abrirá la vista de búsqueda una vez que se enfoque la barra de búsqueda.

Si necesitas configurar la acción, hazlo en la devolución de llamada onCreateOptionsMenu() de tu actividad. Para obtener la referencia de objeto de la vista de acción, llama al método getActionView(). Por ejemplo, en el siguiente código, se obtiene la referencia de objeto para el widget SearchView definido en el ejemplo 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);
}

Cómo responder a la expansión de la vista de acción

Si el elemento <item> de la acción tiene una marca collapseActionView, la app muestra la vista de acción como un ícono hasta que el usuario interactúa con la vista de acción. Cuando el usuario presiona el ícono, el controlador integrado de onOptionsItemSelected() expande la vista de acción. Si la subclase de tu actividad anula el método onOptionsItemSelected(), el método de anulación debe llamar a super.onOptionsItemSelected() para que la superclase pueda expandir la vista de acción.

Si quieres realizar una acción cuando se expande o se contrae la acción, puedes definir una clase que implemente MenuItem.OnActionExpandListener y pasar un miembro de esa clase a setOnActionExpandListener(). Por ejemplo, es posible que desees actualizar la actividad según si una vista de acción se expande o se contrae. En el siguiente fragmento de código, se muestra cómo definir y pasar un objeto de escucha:

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

Cómo agregar un proveedor de acciones

Para declarar un proveedor de acciones, crea un elemento <item> en el recurso de menú de la barra de herramientas, como se describe en Cómo agregar y controlar acciones. Agrega un atributo actionProviderClass y configúralo con el nombre de clase completamente calificado para la clase de proveedor de acciones.

Por ejemplo, en el siguiente código, se declara un ShareActionProvider, que es un widget definido en la biblioteca de AndroidX que permite que tu app comparta datos con otras apps:

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

En este caso, no es necesario declarar un ícono para el widget, ya que ShareActionProvider proporciona sus propios gráficos. Si usas una acción personalizada, declara un ícono.

Recursos adicionales

  • Consulta ShareActionProvider para ver un ejemplo de cómo agregar una acción de compartir a la barra superior de la app.
  • Consulta ActionProvider para obtener más información sobre la creación de un proveedor de acciones personalizado.