Utilizzare le visualizzazioni e i fornitori di azioni

La libreria di AndroidX Toolbar offre agli utenti diversi modi per interagire con la tua app. Aggiungere e gestire azioni descrive come definire un'azione, ad esempio un pulsante o una voce di menu. Questo documento descrive come aggiungere due componenti versatili:

• Una visualizzazione di azione è un'azione che fornisce funzionalità avanzate nella barra dell'app. Ad esempio, una visualizzazione delle azioni di ricerca consente all'utente di digitare il testo di ricerca nella barra dell'app senza dover modificare attività o frammenti.
• Un fornitore di azioni è un'azione con un proprio layout personalizzato. L'azione appare inizialmente come un pulsante o una voce di menu; quando l'utente tocca l'azione, il fornitore dell'azione controlla il comportamento dell'azione come definito da te. Ad esempio, il fornitore di azioni potrebbe rispondere a un tocco mostrando un menu.

AndroidX fornisce diversi widget specializzati di Action View e Action Provider. Ad esempio, il widget SearchView implementa una visualizzazione azioni per l'inserimento delle query di ricerca. Il widget ShareActionProvider implementa un fornitore di azioni per condividere informazioni con altre app. Puoi anche definire visualizzazioni e fornitori di azioni personalizzate.

Aggiungi una visualizzazione azione

Per aggiungere una visualizzazione azioni, crea un elemento <item> nella risorsa menu della barra degli strumenti, come descritto in Aggiungere e gestire azioni. Aggiungi uno dei seguenti attributi all'elemento <item>:

• actionViewClass: la classe di un widget che implementa l'azione
• actionLayout: una risorsa di layout che descrive i componenti dell'azione

Imposta l'attributo showAsAction su "ifRoom|collapseActionView" o "never|collapseActionView". Il flag collapseActionView indica come visualizzare il widget quando l'utente non interagisce con esso. Se il widget si trova sulla barra, l'app lo mostra come icona. Se il widget si trova nel menu extra, l'app visualizza il widget come voce di menu. Quando l'utente interagisce con la visualizzazione azione, questa si espande fino a riempire la barra dell'app.

Ad esempio, il seguente codice aggiunge un widget SearchView alla barra delle 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" />

Se l'utente non interagisce con il widget, l'app mostra il widget come icona specificata da android:icon. Se non c'è spazio nella barra dell'app, l'app aggiunge l'azione al menu extra.

Quando l'utente tocca l'icona o la voce di menu, il widget si espande fino a riempire la barra degli strumenti, consentendo all'utente di interagire con essi.

Se devi configurare l'azione, fallo nel callback onCreateOptionsMenu() dell'attività. Puoi ottenere il riferimento all'oggetto della visualizzazione azione chiamando il metodo getActionView(). Ad esempio, il seguente codice ottiene il riferimento all'oggetto per il widget SearchView definito nell'esempio di codice precedente:

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

Rispondere all'espansione della visualizzazione delle azioni

Se l'elemento <item> dell'azione ha un flag collapseActionView, l'app mostra la visualizzazione azione sotto forma di icona finché l'utente non interagisce con quest'ultima. Quando l'utente tocca l'icona, il gestore integrato per onOptionsItemSelected() espande la visualizzazione delle azioni. Se la sottoclasse di attività esegue l'override del metodo onOptionsItemSelected(), il metodo di override deve richiamare super.onOptionsItemSelected() in modo che la superclasse possa espandere la visualizzazione delle azioni.

Se vuoi eseguire un'azione quando l'azione viene espansa o compressa, puoi definire una classe che implementa MenuItem.OnActionExpandListener e trasmettere un membro di quella classe a setOnActionExpandListener(). Ad esempio, potresti voler aggiornare l'attività a seconda che la visualizzazione dell'azione venga espansa o compressa. Il seguente snippet di codice mostra come definire e trasmettere un 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;
}

Aggiungi un provider di azioni

Per dichiarare un provider di azioni, crea un elemento <item> nella risorsa menu della barra degli strumenti, come descritto in Aggiungere e gestire azioni. Aggiungi un attributo actionProviderClass e impostalo sul nome completo della classe del provider di azioni.

Ad esempio, il codice seguente dichiara un ShareActionProvider, ovvero un widget definito nella libreria AndroidX che consente alla tua app di condividere dati con altre app:

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

In questo caso, non è necessario dichiarare un'icona per il widget, poiché ShareActionProvider fornisce le proprie immagini. Se usi un'azione personalizzata, dichiara un'icona.

Risorse aggiuntive

• Consulta ShareActionProvider per un esempio di aggiunta di un'azione di condivisione alla barra superiore dell'app.
• Consulta ActionProvider per ulteriori informazioni sulla creazione di un provider di azioni personalizzate.