Aktionsansichten und Aktionsanbieter verwenden

Die Toolbar der AndroidX-Bibliothek bietet Nutzern verschiedene Möglichkeiten, mit deiner App zu interagieren. Unter Aktionen hinzufügen und verarbeiten wird beschrieben, wie eine Aktion definiert wird. Das kann eine Schaltfläche oder ein Menüelement sein. In diesem Dokument wird beschrieben, wie Sie zwei vielseitige Komponenten hinzufügen können:

• Eine Aktionsansicht ist eine Aktion mit umfangreichen Funktionen in der App-Leiste. Bei einer Ansicht für Suchaktionen kann der Nutzer beispielsweise seinen Suchtext in die App-Leiste eingeben, ohne Aktivitäten oder Fragmente ändern zu müssen.
• Ein Aktionsanbieter ist eine Aktion mit eigenem benutzerdefinierten Layout. Die Aktion wird anfangs als Schaltfläche oder Menüelement angezeigt. Wenn der Nutzer auf die Aktion tippt, steuert der Aktionsanbieter das Verhalten der Aktion auf eine von Ihnen festgelegte Weise. Der Anbieter der Aktion kann beispielsweise auf ein Tippen reagieren und ein Menü anzeigen.

AndroidX bietet mehrere spezialisierte Widgets für Aktionsansichten und Aktionsanbieter. Das SearchView-Widget implementiert beispielsweise eine Aktionsansicht zur Eingabe von Suchanfragen. Das Widget ShareActionProvider implementiert einen Aktionsanbieter zum Teilen von Informationen mit anderen Apps. Sie können auch eigene Aktionsansichten und Aktionsanbieter definieren.

Aktionsansicht hinzufügen

Wenn Sie eine Aktionsansicht hinzufügen möchten, erstellen Sie in der Menüressource der Symbolleiste ein <item>-Element, wie unter Aktionen hinzufügen und verarbeiten beschrieben. Fügen Sie dem Element <item> eines der folgenden Attribute hinzu:

• actionViewClass: die Klasse eines Widgets, das die Aktion implementiert.
• actionLayout: eine Layoutressource, die die Komponenten der Aktion beschreibt

Legen Sie das Attribut showAsAction auf "ifRoom|collapseActionView" oder "never|collapseActionView" fest. Das Flag collapseActionView gibt an, wie das Widget angezeigt werden soll, wenn der Nutzer nicht damit interagiert. Wenn sich das Widget in der App-Leiste befindet, wird es in der App als Symbol angezeigt. Wenn sich das Widget im Dreipunkt-Menü befindet, wird es in der App als Menüpunkt angezeigt. Wenn der Nutzer mit der Aktionsansicht interagiert, wird sie maximiert und füllt die App-Leiste aus.

Mit dem folgenden Code wird beispielsweise ein SearchView-Widget zur App-Leiste hinzugefügt:

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

Wenn der Nutzer nicht mit dem Widget interagiert, wird es in der App als durch android:icon angegebenes Symbol angezeigt. Wenn in der App-Leiste kein Platz mehr ist, fügt die App die Aktion dem Dreipunkt-Menü hinzu.

Wenn der Nutzer auf das Symbol oder Menüelement tippt, füllt das Widget die Symbolleiste aus und der Nutzer kann damit interagieren.

Wenn Sie die Aktion konfigurieren müssen, nehmen Sie dies im onCreateOptionsMenu()-Callback der Aktivität vor. Sie können die Objektreferenz der Aktionsansicht durch Aufrufen der Methode getActionView() abrufen. Mit dem folgenden Code wird beispielsweise die Objektreferenz für das SearchView-Widget abgerufen, das im vorherigen Codebeispiel definiert wurde:

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

Auf die Erweiterung der Aktionsansicht reagieren

Wenn das Element <item> der Aktion das Flag collapseActionView hat, zeigt die App die Aktionsansicht als Symbol an, bis der Nutzer mit der Aktionsansicht interagiert. Wenn der Nutzer auf das Symbol tippt, wird mit dem integrierten Handler für onOptionsItemSelected() die Aktionsansicht maximiert. Wenn Ihre abgeleitete Aktivitätsklasse die Methode onOptionsItemSelected() überschreibt, muss die Überschreibungsmethode super.onOptionsItemSelected() aufrufen, damit die übergeordnete Klasse die Aktionsansicht erweitern kann.

Wenn Sie eine Aktion ausführen möchten, wenn die Aktion maximiert oder minimiert wird, können Sie eine Klasse definieren, die MenuItem.OnActionExpandListener implementiert, und ein Mitglied dieser Klasse an setOnActionExpandListener() übergeben. Sie können die Aktivität beispielsweise danach aktualisieren, ob eine Aktionsansicht maximiert oder minimiert wurde. Das folgende Code-Snippet zeigt, wie ein Listener definiert und übergeben wird:

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

Aktionsanbieter hinzufügen

Wenn Sie einen Aktionsanbieter deklarieren möchten, erstellen Sie in der Menüressource der Symbolleiste ein <item>-Element, wie unter Aktionen hinzufügen und verarbeiten beschrieben. Fügen Sie ein actionProviderClass-Attribut hinzu und legen Sie es auf den voll qualifizierten Klassennamen der Klasse des Aktionsanbieters fest.

Mit dem folgenden Code wird beispielsweise ein ShareActionProvider deklariert. Dabei handelt es sich um ein in der AndroidX-Bibliothek definiertes Widget, mit dem Ihre App Daten an andere Apps weitergeben kann:

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

In diesem Fall ist es nicht erforderlich, ein Symbol für das Widget zu deklarieren, da ShareActionProvider eigene Grafiken bereitstellt. Wenn Sie eine benutzerdefinierte Aktion verwenden, deklarieren Sie ein Symbol.

Weitere Informationen

• Unter ShareActionProvider finden Sie ein Beispiel für das Hinzufügen einer Aktion zum Teilen zur oberen App-Leiste.
• Weitere Informationen zum Erstellen eines Anbieters für benutzerdefinierte Aktionen finden Sie unter ActionProvider.