Suchoberfläche erstellen

Compose ausprobieren

Jetpack Compose ist das empfohlene UI-Toolkit für Android. Hier erfahren Sie, wie Sie eine Suchfunktion in Compose hinzufügen.

Suchleiste →

Wenn Sie Ihrer App eine Suchfunktion hinzufügen möchten, können Sie die Benutzeroberfläche mit einem Suchdialogfeld, das oben im Aktivitätsfenster angezeigt wird, oder mit einem Such-Widget implementieren, das Sie in Ihr Layout einfügen können. Sowohl das Suchdialogfeld als auch das Widget können die Suchanfrage des Nutzers an eine bestimmte Aktivität in Ihrer App senden. So kann der Nutzer eine Suche über jede Aktivität starten, in der das Suchdialogfeld oder das Widget verfügbar ist. Das System startet dann die entsprechende Aktivität, um die Suche auszuführen und die Ergebnisse zu präsentieren.

Weitere Funktionen, die für das Suchdialogfeld und das Widget verfügbar sind:

• Sprachsuche
• Suchvorschläge basierend auf den letzten Suchanfragen
• Suchvorschläge, die mit tatsächlichen Ergebnissen in Ihren App-Daten übereinstimmen

In diesem Dokument wird beschrieben, wie Sie Ihre App so einrichten, dass sie eine Suchoberfläche bietet, die vom Android-System unterstützt wird, um Suchanfragen über den Suchdialog oder das Such-Widget zu übermitteln.

Weitere Informationen:

• Material Design-Symbole

Grundlagen

Bevor Sie beginnen, müssen Sie entscheiden, ob Sie die Suchoberfläche über das Suchdialogfeld oder das Such-Widget implementieren möchten. Sie bieten dieselben Suchfunktionen, aber auf leicht unterschiedliche Weise:

• Das Suchdialogfeld ist eine UI-Komponente, die vom Android-System gesteuert wird. Wenn der Nutzer die Funktion aktiviert, wird das Suchdialogfeld oben in der Aktivität angezeigt.

  Das Android-System steuert alle Ereignisse im Suchdialogfeld. Wenn der Nutzer eine Anfrage sendet, leitet das System die Anfrage an die Aktivität weiter, die Sie für die Verarbeitung von Suchanfragen angegeben haben. Im Dialogfeld können auch Suchvorschläge angezeigt werden, während der Nutzer tippt.

• Das Such-Widget ist eine Instanz von SearchView, die Sie an einer beliebigen Stelle in Ihrem Layout platzieren können. Standardmäßig verhält sich das Such-Widget wie ein normales EditText-Widget und führt keine Aktionen aus. Sie können es jedoch so konfigurieren, dass das Android-System alle Eingabeereignisse verarbeitet, Anfragen an die entsprechende Aktivität weiterleitet und Suchvorschläge bereitstellt – genau wie im Suchdialogfeld.

Wenn der Nutzer eine Suche über das Suchdialogfeld oder ein Such-Widget ausführt, erstellt das System ein Intent und speichert die Nutzeranfrage darin. Das System startet dann die Aktivität, die Sie für die Verarbeitung von Suchanfragen deklarieren – die „durchsuchbare Aktivität“ – und übergibt ihr den Intent. Um Ihre App für diese Art von unterstützter Suche einzurichten, benötigen Sie Folgendes:

Eine Suchkonfiguration

Eine XML-Datei, in der einige Einstellungen für das Suchdialogfeld oder das Such-Widget konfiguriert werden. Sie enthält Einstellungen für Funktionen wie die Sprachsuche, Suchvorschläge und Hinweistext für das Suchfeld.

Eine suchbare Aktivität

Die Activity, die die Suchanfrage empfängt, Ihre Daten durchsucht und die Suchergebnisse anzeigt.

Eine Suchoberfläche, die von einem der folgenden Anbieter bereitgestellt wird:

Das Suchdialogfeld

Das Suchdialogfeld ist standardmäßig ausgeblendet. Er wird oben auf dem Bildschirm angezeigt, wenn Sie onSearchRequested() aufrufen, nachdem der Nutzer auf Ihre Schaltfläche Suchen getippt hat.

Ein SearchView-Widget

Mit dem Such-Widget können Sie das Suchfeld an einer beliebigen Stelle in Ihrer Aktivität platzieren, z. B. als Aktionsansicht in der App-Leiste.

Im Rest dieses Dokuments erfahren Sie, wie Sie die Suchkonfiguration und die durchsuchbare Aktivität erstellen und eine Suchoberfläche mit dem Suchdialogfeld oder dem Such-Widget implementieren.

Suchkonfiguration erstellen

Zuerst benötigen Sie eine XML-Datei, die als Suchkonfiguration bezeichnet wird. Damit werden bestimmte UI-Aspekte des Suchdialogfelds oder ‑Widgets konfiguriert und das Verhalten von Funktionen wie Vorschlägen und der Sprachsuche definiert. Diese Datei hat traditionell den Namen searchable.xml und muss im Projektverzeichnis res/xml/ gespeichert werden.

Die Suchkonfigurationsdatei muss das Element <searchable> als Stammknoten enthalten und ein oder mehrere Attribute angeben, wie im folgenden Beispiel gezeigt:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint" >
</searchable>

Das Attribut android:label ist das einzige erforderliche Attribut. Sie verweist auf eine String-Ressource, die den App-Namen enthalten muss. Dieses Label ist für den Nutzer erst sichtbar, wenn Sie Suchvorschläge für das Schnellsuchfeld aktivieren. Dann ist es in den Systemeinstellungen in der Liste der durchsuchbaren Elemente sichtbar.

Obwohl es nicht erforderlich ist, empfehlen wir, immer das Attribut android:hint anzugeben. Es enthält einen Hinweisstring, der im Suchfeld angezeigt wird, bevor Nutzer eine Suchanfrage eingeben. Der Hinweis ist wichtig, weil er Nutzern wichtige Informationen dazu gibt, wonach sie suchen können.

Das <searchable>-Element akzeptiert mehrere andere Attribute. Die meisten Attribute sind jedoch erst erforderlich, wenn Sie Funktionen wie Suchvorschläge und Sprachsuche hinzufügen. Ausführliche Informationen zur Suchkonfigurationsdatei finden Sie im Referenzdokument Suchkonfiguration.

Durchsuchbare Aktivität erstellen

Eine durchsuchbare Aktivität ist die Activity in Ihrer App, die auf Grundlage eines Suchstrings Suchvorgänge ausführt und die Suchergebnisse präsentiert.

Wenn der Nutzer eine Suche im Suchdialogfeld oder ‑widget ausführt, startet das System Ihre durchsuchbare Aktivität und übergibt ihr die Suchanfrage in einem Intent mit der Aktion ACTION_SEARCH. Bei der durchsuchbaren Aktivität wird die Anfrage aus dem Extra QUERY des Intents abgerufen, dann werden Ihre Daten durchsucht und die Ergebnisse präsentiert.

Da Sie das Suchdialogfeld oder das Such-Widget in jede andere Aktivität in Ihrer App einfügen können, muss das System wissen, welche Aktivität Ihre durchsuchbare Aktivität ist, damit die Suchanfrage richtig übermittelt werden kann. Deklarieren Sie Ihre durchsuchbare Aktivität zuerst in der Android-Manifestdatei.

Suchbare Aktivität deklarieren

Wenn Sie noch keine haben, erstellen Sie eine Activity, die Suchanfragen ausführt und Ergebnisse präsentiert. Sie müssen die Suchfunktion noch nicht implementieren. Erstellen Sie einfach eine Aktivität, die Sie im Manifest deklarieren können. Führen Sie im <activity>-Element des Manifests die folgenden Schritte aus:

1. Deklarieren Sie die Aktivität, um den ACTION_SEARCH-Intent in einem <intent-filter>-Element zu akzeptieren.
2. Geben Sie die zu verwendende Suchkonfiguration in einem <meta-data>-Element an.

Dies wird im folgenden Beispiel veranschaulicht:

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

Das <meta-data>-Element muss das Attribut android:name mit dem Wert "android.app.searchable" und das Attribut android:resource mit einem Verweis auf die durchsuchbare Konfigurationsdatei enthalten. Im vorherigen Beispiel bezieht es sich auf die Datei res/xml/searchable.xml.

Suche durchführen

Nachdem Sie Ihre durchsuchbare Aktivität im Manifest deklariert haben, gehen Sie so vor, um eine Suche in Ihrer durchsuchbaren Aktivität durchzuführen:

1. Anfrage erhalten:
2. Daten durchsuchen
3. Ergebnisse präsentieren:

Abfrage erhalten

Wenn ein Nutzer eine Suche über das Suchfeld oder das Widget ausführt, startet das System Ihre durchsuchbare Aktivität und sendet ihr einen ACTION_SEARCH-Intent. Dieser Intent enthält die Suchanfrage im String-Extra QUERY. Prüfen Sie beim Start der Aktivität, ob dieser Intent vorhanden ist, und extrahieren Sie den String. So können Sie beispielsweise die Suchanfrage abrufen, wenn Ihre durchsuchbare Aktivität beginnt:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

Der String QUERY ist immer im Intent ACTION_SEARCH enthalten. Im vorherigen Beispiel wird die Abfrage abgerufen und an eine lokale doMySearch()-Methode übergeben, in der der eigentliche Suchvorgang ausgeführt wird.

Daten durchsuchen

Das Speichern und Suchen von Daten ist für jede App unterschiedlich. Es gibt viele Möglichkeiten, Daten zu speichern und zu durchsuchen. In diesem Dokument wird nicht beschrieben, wie das funktioniert. Überlegen Sie, wie Sie Ihre Daten entsprechend Ihren Anforderungen und Ihrem Datenformat speichern und durchsuchen. Hier sind einige Tipps, die Sie möglicherweise anwenden können:

• Wenn Ihre Daten in einer SQLite-Datenbank auf dem Gerät gespeichert sind, kann eine Volltextsuche mit FTS3 anstelle einer LIKE-Abfrage eine robustere Suche in Textdaten ermöglichen und Ergebnisse deutlich schneller liefern. Informationen zu FTS3 finden Sie unter sqlite.org. Informationen zu SQLite unter Android finden Sie in der SQLiteDatabase-Klasse.
• Wenn Ihre Daten online gespeichert sind, kann die wahrgenommene Suchleistung durch die Datenverbindung des Nutzers beeinträchtigt werden. Möglicherweise möchten Sie eine Fortschrittsanzeige einblenden, bis die Suchergebnisse zurückgegeben werden. Eine Referenz für Netzwerk-APIs finden Sie unter android.net. Informationen zum Anzeigen einer Fortschrittsanzeige finden Sie unter ProgressBar.

Ergebnisse präsentieren

Unabhängig davon, wo sich Ihre Daten befinden und wie Sie sie durchsuchen, empfehlen wir, Suchergebnisse für Ihre durchsuchbare Aktivität mit einem Adapter zurückzugeben. So können Sie alle Suchergebnisse in einem RecyclerView präsentieren. Wenn Ihre Daten aus einer SQLite-Datenbankabfrage stammen, können Sie die Ergebnisse mit einem CursorAdapter auf ein RecyclerView anwenden. Wenn Ihre Daten in einem anderen Format vorliegen, können Sie eine Erweiterung von BaseAdapter erstellen.

Ein Adapter bindet jedes Element aus einem Datensatz in ein View-Objekt ein. Wenn Adapter auf ein RecyclerView angewendet wird, werden alle Daten als einzelne Ansicht in die Liste eingefügt. Adapter ist nur eine Schnittstelle. Daher sind Implementierungen wie CursorAdapter zum Binden von Daten aus einem Cursor erforderlich. Wenn keine der vorhandenen Implementierungen für Ihre Daten funktioniert, können Sie Ihre eigene Implementierung aus BaseAdapter erstellen.

Suchdialogfeld verwenden

Im Suchdialogfeld wird oben auf dem Bildschirm ein schwebendes Suchfeld mit dem App-Symbol auf der linken Seite angezeigt. Im Suchdialogfeld können Suchvorschläge angezeigt werden, während der Nutzer tippt. Wenn der Nutzer eine Suche ausführt, sendet das System die Suchanfrage an eine durchsuchbare Aktivität, die die Suche ausführt.

Standardmäßig ist das Suchfeld immer ausgeblendet, bis der Nutzer es aktiviert. Ihre App kann das Suchdialogfeld durch Aufrufen von onSearchRequested() aktivieren. Diese Methode funktioniert jedoch erst, wenn Sie das Suchdialogfeld für die Aktivität aktivieren.

Damit im Suchdialogfeld Suchanfragen ausgeführt werden können, müssen Sie dem System mitteilen, welche durchsuchbare Aktivität Suchanfragen aus dem Suchdialogfeld empfangen soll. Im vorherigen Abschnitt zum Erstellen einer durchsuchbaren Aktivität wird beispielsweise eine durchsuchbare Aktivität namens SearchableActivity erstellt. Wenn Sie möchten, dass in einer separaten Aktivität, z. B. mit dem Namen OtherActivity, das Suchdialogfeld angezeigt und Suchanfragen an SearchableActivity gesendet werden, deklarieren Sie im Manifest, dass SearchableActivity die durchsuchbare Aktivität ist, die für das Suchdialogfeld in OtherActivity verwendet werden soll.

Wenn Sie die durchsuchbare Aktivität für das Suchdialogfeld einer Aktivität deklarieren möchten, fügen Sie ein <meta-data>-Element in das <activity>-Element der jeweiligen Aktivität ein. Das <meta-data>-Element muss das Attribut android:value enthalten, das den Klassennamen der durchsuchbaren Aktivität angibt, sowie das Attribut android:name mit dem Wert "android.app.default_searchable".

Hier ist beispielsweise die Deklaration für eine durchsuchbare Aktivität (SearchableActivity) und eine andere Aktivität (OtherActivity), die SearchableActivity verwendet, um Suchvorgänge aus dem zugehörigen Suchdialogfeld auszuführen:

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

Da OtherActivity jetzt ein <meta-data>-Element enthält, mit dem deklariert wird, welche durchsuchbare Aktivität für Suchvorgänge verwendet werden soll, wird durch die Aktivität das Suchdialogfeld aktiviert. Obwohl sich der Nutzer in dieser Aktivität befindet, wird durch die Methode onSearchRequested() das Suchdialogfeld aktiviert. Wenn der Nutzer die Suche ausführt, startet das System SearchableActivity und liefert den Intent ACTION_SEARCH.

Wenn Sie möchten, dass in jeder Aktivität in Ihrer App das Suchdialogfeld angezeigt wird, fügen Sie das oben genannte <meta-data>-Element als untergeordnetes Element des <application>-Elements anstelle jedes <activity> ein. So erbt jede Aktivität den Wert, stellt das Suchdialogfeld bereit und leitet Suchanfragen an dieselbe durchsuchbare Aktivität weiter. Wenn Sie mehrere durchsuchbare Aktivitäten haben, können Sie die standardmäßige durchsuchbare Aktivität überschreiben, indem Sie eine andere <meta-data>-Deklaration in einzelne Aktivitäten einfügen.

Da das Suchdialogfeld jetzt für Ihre Aktivitäten aktiviert ist, kann Ihre App Suchvorgänge ausführen.

Suchdialogfeld aufrufen

Einige Geräte haben zwar eine spezielle Suchtaste, aber das Verhalten der Taste kann je nach Gerät variieren. Viele Geräte haben auch gar keine Suchtaste. Wenn Sie das Suchdialogfeld verwenden, müssen Sie in Ihrer Benutzeroberfläche eine Schaltfläche zum Starten der Suche bereitstellen, mit der das Suchdialogfeld durch Aufrufen von onSearchRequested() aktiviert wird.

Fügen Sie beispielsweise eine Schaltfläche zum Suchen in Ihrem Optionsmenü oder UI-Layout hinzu, die onSearchRequested() aufruft.

Sie können auch die Funktion „Zum Suchen tippen“ aktivieren, die das Suchdialogfeld aufruft, wenn der Nutzer auf der Tastatur zu tippen beginnt. Die Tasteneingaben werden in das Suchfeld eingefügt. Sie können die Suche per Texteingabe in Ihrer Aktivität aktivieren, indem Sie während der onCreate()-Methode Ihrer Aktivität setDefaultKeyMode oder DEFAULT_KEYS_SEARCH_LOCAL aufrufen.

Auswirkungen des Suchdialogfelds auf den Aktivitätslebenszyklus

Das Suchdialogfeld ist ein Dialog, das oben auf dem Bildschirm angezeigt wird. Dadurch ändert sich der Aktivitätsstack nicht. Wenn das Suchdialogfeld angezeigt wird, werden keine Lebenszyklusmethoden wie onPause() aufgerufen. Ihre Aktivität verliert den Eingabefokus, da der Eingabefokus dem Suchdialogfeld zugewiesen wird.

Wenn Sie benachrichtigt werden möchten, wenn das Suchdialogfeld aktiviert wird, überschreiben Sie die Methode onSearchRequested(). Wenn das System diese Methode aufruft, verliert deine Aktivität den Eingabefokus an das Suchdialogfeld. Du kannst dann alle für das Ereignis geeigneten Aktionen ausführen, z. B. ein Spiel pausieren. Sofern Sie nicht Daten zum Suchkontext übergeben (siehe anderen Abschnitt in diesem Dokument), beenden Sie die Methode, indem Sie die Superclass-Implementierung aufrufen:

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

Wenn der Nutzer die Suche durch Tippen auf die Zurück-Schaltfläche abbricht, wird das Suchdialogfeld geschlossen und die Aktivität erhält den Eingabefokus zurück. Sie können sich registrieren, um benachrichtigt zu werden, wenn das Suchdialogfeld mit setOnDismissListener(), setOnCancelListener() oder beidem geschlossen wird. Sie müssen nur OnDismissListener registrieren, da es jedes Mal aufgerufen wird, wenn das Suchdialogfeld geschlossen wird. OnCancelListener bezieht sich nur auf Ereignisse, bei denen der Nutzer das Suchdialogfeld explizit schließt. Es wird also nicht aufgerufen, wenn eine Suche ausgeführt wird. Wenn die Suche ausgeführt wird, wird das Suchdialogfeld automatisch geschlossen.

Wenn die aktuelle Aktivität nicht die durchsuchbare Aktivität ist, werden die normalen Ereignisse des Aktivitätslebenszyklus ausgelöst, wenn der Nutzer eine Suche ausführt. Die aktuelle Aktivität empfängt onPause(), wie unter Einführung in Aktivitäten beschrieben. Wenn die aktuelle Aktivität jedoch die durchsuchbare Aktivität ist, passiert eines von zwei Dingen:

• Standardmäßig empfängt die durchsuchbare Aktivität den ACTION_SEARCH-Intent mit einem Aufruf von onCreate() und eine neue Instanz der Aktivität wird an den Anfang des Aktivitätsstacks verschoben. Es gibt jetzt zwei Instanzen Ihrer durchsuchbaren Aktivität im Aktivitätsstapel. Wenn Sie also auf die Schaltfläche „Zurück“ tippen, gelangen Sie zur vorherigen Instanz der durchsuchbaren Aktivität und nicht aus der durchsuchbaren Aktivität heraus.
• Wenn Sie android:launchMode auf "singleTop" festlegen, empfängt die durchsuchbare Aktivität den Intent ACTION_SEARCH mit einem Aufruf von onNewIntent(Intent), wobei der neue Intent ACTION_SEARCH übergeben wird. Hier ist ein Beispiel dafür, wie Sie diesen Fall behandeln können, in dem der Startmodus der durchsuchbaren Aktivität "singleTop" ist:

  Kotlin

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.search)
      handleIntent(intent)
  }
  
  override fun onNewIntent(intent: Intent) {
      super.onNewIntent(intent)
      setIntent(intent)
      handleIntent(intent)
  }
  
  private fun handleIntent(intent: Intent) {
      if (Intent.ACTION_SEARCH == intent.action) {
          intent.getStringExtra(SearchManager.QUERY)?.also { query ->
              doMySearch(query)
          }
      }
  }

  Java

  @Override
  public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.search);
      handleIntent(getIntent());
  }
  
  @Override
  protected void onNewIntent(Intent intent) {
      super.onNewIntent(intent);
      setIntent(intent);
      handleIntent(intent);
  }
  
  private void handleIntent(Intent intent) {
      if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        doMySearch(query);
      }
  }

  Im Vergleich zum Beispielcode im Abschnitt Suche durchführen befindet sich der gesamte Code zur Verarbeitung der Suchintention jetzt in der Methode handleIntent(), sodass er sowohl von onCreate() als auch von onNewIntent() ausgeführt werden kann.

  Wenn das System onNewIntent(Intent) aufruft, wird die Aktivität nicht neu gestartet. Die Methode getIntent() gibt also denselben Intent zurück, der mit onCreate() empfangen wird. Deshalb müssen Sie setIntent(Intent) in onNewIntent(Intent) aufrufen, damit die von der Aktivität gespeicherte Intention aktualisiert wird, falls Sie getIntent() in Zukunft aufrufen.

Das zweite Szenario mit dem Startmodus "singleTop" ist in der Regel vorzuziehen, da der Nutzer nach einer Suche möglicherweise weitere Suchanfragen ausführt und Sie nicht möchten, dass Ihre App mehrere Instanzen der durchsuchbaren Aktivität erstellt. Wir empfehlen, für die durchsuchbare Aktivität im App-Manifest den "singleTop"-Startmodus festzulegen, wie im folgenden Beispiel gezeigt:

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

Suchkontextdaten übergeben

In einigen Fällen können Sie die Suchanfrage für jede Suche in der durchsuchbaren Aktivität anpassen. Wenn Sie Ihre Suchkriterien jedoch basierend auf der Aktivität verfeinern möchten, über die der Nutzer eine Suche ausführt, können Sie zusätzliche Daten im Intent angeben, den das System an Ihre durchsuchbare Aktivität sendet. Sie können die zusätzlichen Daten im APP_DATA Bundle übergeben, der im Intent ACTION_SEARCH enthalten ist.

Wenn Sie diese Art von Daten an Ihre durchsuchbare Aktivität übergeben möchten, überschreiben Sie die Methode onSearchRequested() für die Aktivität, über die der Nutzer eine Suche ausführen kann, erstellen Sie ein Bundle mit den zusätzlichen Daten und rufen Sie startSearch() auf, um den Suchdialog zu aktivieren. Beispiel:

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

Wenn „true“ zurückgegeben wird, bedeutet das, dass Sie dieses Callback-Ereignis erfolgreich verarbeitet und startSearch() aufgerufen haben, um das Suchdialogfeld zu aktivieren. Nachdem der Nutzer eine Anfrage gesendet hat, wird sie zusammen mit den von Ihnen hinzugefügten Daten an Ihre durchsuchbaren Aktivitäten übermittelt. Sie können die zusätzlichen Daten aus dem APP_DATA Bundle extrahieren, um die Suche zu verfeinern, wie im folgenden Beispiel gezeigt:

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

Such-Widget verwenden

Abbildung 1: Das SearchView-Widget als Aktionsansicht in der App-Leiste.

Das Such-Widget bietet dieselben Funktionen wie das Suchdialogfeld. Sie startet die entsprechende Aktivität, wenn der Nutzer eine Suche ausführt, und kann Suchvorschläge liefern und die Sprachsuche ausführen. Wenn Sie das Such-Widget nicht in die App-Leiste einfügen können, können Sie es stattdessen an einer beliebigen Stelle im Layout Ihrer Aktivität platzieren.

Such-Widget konfigurieren

Nachdem Sie eine Suchkonfiguration und eine durchsuchbare Aktivität erstellt haben, aktivieren Sie die unterstützte Suche für jede SearchView, indem Sie setSearchableInfo() aufrufen und das SearchableInfo-Objekt übergeben, das Ihre durchsuchbare Konfiguration darstellt.

Sie können einen Verweis auf SearchableInfo abrufen, indem Sie getSearchableInfo() für SearchManager aufrufen.

Wenn Sie beispielsweise ein SearchView als Aktionsansicht in der App-Leiste verwenden, aktivieren Sie das Widget während des onCreateOptionsMenu()-Callbacks, wie im folgenden Beispiel gezeigt:

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

Das Such-Widget ist jetzt konfiguriert und das System leitet Suchanfragen an Ihre durchsuchbare Aktivität weiter. Sie können auch Suchvorschläge für das Such-Widget aktivieren.

Weitere Informationen zu Aktionsansichten in der App-Leiste finden Sie unter Aktionsansichten und Aktionsanbieter verwenden.

Weitere Funktionen des Such-Widgets

Das SearchView-Widget bietet einige zusätzliche Funktionen, die Sie möglicherweise nutzen möchten:

Schaltfläche „Senden“

Standardmäßig gibt es keine Schaltfläche zum Senden einer Suchanfrage. Der Nutzer muss also die Return-Taste auf der Tastatur drücken, um eine Suche zu starten. Sie können eine Schaltfläche zum Senden hinzufügen, indem Sie setSubmitButtonEnabled(true) aufrufen.

Abfrageverfeinerung für Suchvorschläge

Wenn Sie Suchvorschläge aktivieren, erwarten Sie in der Regel, dass Nutzer einen Vorschlag auswählen. Sie möchten die vorgeschlagene Suchanfrage aber möglicherweise auch verfeinern. Sie können neben jedem Vorschlag eine Schaltfläche hinzufügen, mit der der Vorschlag in das Suchfeld eingefügt wird, damit der Nutzer ihn verfeinern kann. Rufen Sie dazu setQueryRefinementEnabled(true) auf.

Möglichkeit, die Sichtbarkeit des Suchfelds zu aktivieren/deaktivieren

Standardmäßig ist das Such-Widget „symbolisiert“, d. h., es wird nur durch ein Suchsymbol – eine Lupe – dargestellt. Es wird maximiert, um das Suchfeld anzuzeigen, wenn der Nutzer auf das Symbol tippt. Wie im vorherigen Beispiel gezeigt, können Sie das Suchfeld standardmäßig einblenden, indem Sie setIconifiedByDefault(false) aufrufen. Sie können das Erscheinungsbild des Such-Widgets auch durch Aufrufen von setIconified() ändern.

Es gibt mehrere andere APIs in der Klasse SearchView, mit denen Sie das Such-Widget anpassen können. Die meisten werden jedoch nur verwendet, wenn Sie alle Nutzereingaben selbst verarbeiten, anstatt das Android-System zum Senden von Suchanfragen und Anzeigen von Suchvorschlägen zu verwenden.

Sowohl das Widget als auch den Dialog verwenden

Wenn Sie das Such-Widget als Action View in die App-Leiste einfügen und festlegen, dass es in der App-Leiste angezeigt werden soll, wenn Platz ist – indem Sie android:showAsAction="ifRoom" festlegen –, wird das Such-Widget möglicherweise nicht als Action View angezeigt. Stattdessen wird möglicherweise ein Menüpunkt im Überlaufmenü angezeigt. Wenn Ihre App beispielsweise auf einem kleineren Bildschirm ausgeführt wird, ist in der App-Leiste möglicherweise nicht genügend Platz, um das Such-Widget zusammen mit anderen Aktions- oder Navigationselementen anzuzeigen. In diesem Fall wird das Menüelement stattdessen im Überlaufmenü angezeigt. Wenn das Element im Dreipunkt-Menü platziert wird, funktioniert es wie ein normales Menüelement und zeigt nicht die Aktionsansicht (das Such-Widget) an.

Um diese Situation zu bewältigen, muss der Menüpunkt, an den Sie das Such-Widget anhängen, den Suchdialog aktivieren, wenn der Nutzer ihn im Überlaufmenü auswählt. Implementieren Sie dazu onOptionsItemSelected(), um das Menüelement „Suchen“ zu verarbeiten und das Suchdialogfeld durch Aufrufen von onSearchRequested() zu öffnen.

Weitere Informationen zur Funktionsweise von Elementen in der App-Leiste und zum Umgang mit dieser Situation finden Sie unter App-Leiste hinzufügen.

Sprachsuche hinzufügen

Sie können Ihrem Suchdialogfeld oder ‑widget die Sprachsuche hinzufügen, indem Sie Ihrer durchsuchbaren Konfiguration das Attribut android:voiceSearchMode hinzufügen. Dadurch wird eine Schaltfläche für die Sprachsuche hinzugefügt, über die ein Sprachprompt gestartet wird. Wenn der Nutzer mit dem Sprechen fertig ist, wird die transkribierte Suchanfrage an die durchsuchbare Aktivität gesendet.

Dies wird im folgenden Beispiel veranschaulicht:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

Der Wert showVoiceSearchButton ist erforderlich, um die Sprachsuche zu aktivieren. Der zweite Wert, launchRecognizer, gibt an, dass die Schaltfläche für die Sprachsuche einen Recognizer starten muss, der den transkribierten Text an die durchsuchbare Aktivität zurückgibt.

Sie können zusätzliche Attribute angeben, um das Verhalten der Sprachsuche festzulegen, z. B. die erwartete Sprache und die maximale Anzahl der zurückzugebenden Ergebnisse. Weitere Informationen zu den verfügbaren Attributen finden Sie in der Referenz zur Suchkonfiguration.

Suchvorschläge hinzufügen

Sowohl das Suchfeld als auch das Such-Widget können mithilfe des Android-Systems Suchvorschläge anzeigen, während der Nutzer tippt. Das System verwaltet die Liste der Vorschläge und verarbeitet das Ereignis, wenn der Nutzer einen Vorschlag auswählt.

Sie können zwei Arten von Suchvorschlägen angeben:

Suchvorschläge anhand der letzten Suchanfragen

Diese Vorschläge sind Wörter, die der Nutzer zuvor als Suchanfragen in Ihrer App verwendet hat. Weitere Informationen finden Sie unter Benutzerdefinierte Suchvorschläge hinzufügen.

Benutzerdefinierte Suchvorschläge

Das sind Suchvorschläge, die Sie aus Ihrer eigenen Datenquelle bereitstellen, damit Nutzer sofort die richtige Schreibweise oder das richtige Element auswählen können, nach dem sie suchen. Weitere Informationen finden Sie unter Benutzerdefinierte Suchvorschläge hinzufügen.