Suchoberfläche erstellen

Wenn Sie Ihrer App eine Suchfunktion hinzufügen möchten, können Sie in Android die Benutzeroberfläche entweder 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 der Suchdialog als auch das Widget können die Suchanfrage des Nutzers an eine bestimmte Aktivität in Ihrer App senden. Auf diese Weise kann der Nutzer eine Suche aus jeder Aktivität starten, bei der das Suchdialogfeld oder -Widget verfügbar ist, und das System startet die entsprechende Aktivität, um die Suche durchzuführen und Ergebnisse anzuzeigen.

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

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

In diesem Dokument wird beschrieben, wie du deine App so einrichtest, dass sie eine Suchoberfläche bereitstellt, die vom Android-System zur Übermittlung von Suchanfragen über das Suchdialogfeld oder das Such-Widget unterstützt wird.

Weitere Informationen:

• Material Design-Symbole

Grundlagen

Entscheiden Sie zuerst, ob Sie die Suchoberfläche über das Suchdialogfeld oder das Such-Widget implementieren möchten. Sie bieten die gleichen Suchfunktionen, aber auf leicht unterschiedliche Weise:

• Das Dialogfeld für die Suche ist eine UI-Komponente, die vom Android-System gesteuert wird. Wenn das Dialogfeld vom Nutzer aktiviert wurde, wird es oben in der Aktivität angezeigt.

  Das Android-System steuert alle Ereignisse im Suchdialogfeld. Wenn der Nutzer eine Abfrage sendet, liefert das System diese Abfrage an die Aktivität, die Sie für die Verarbeitung der Suchanfragen angegeben haben. Während der Eingabe können über das Dialogfeld auch Suchvorschläge angezeigt werden.

• Das Such-Widget ist eine Instanz von SearchView, die Sie an einer beliebigen Stelle im Layout platzieren können. Das Such-Widget verhält sich standardmäßig wie ein standardmäßiges EditText-Widget und hat keine Funktion. Du kannst es aber so konfigurieren, dass das Android-System alle Eingabeereignisse verarbeitet, Anfragen an die entsprechende Aktivität liefert und Suchvorschläge ausgibt – genau wie das Suchdialogfeld.

Wenn der Nutzer eine Suche über den Suchdialog oder ein Such-Widget ausführt, erstellt das System eine Intent und speichert die Nutzerabfrage darin. Das System startet dann die Aktivität, die Sie für die Verarbeitung von Suchanfragen deklariert haben, also die „suchbare Aktivität“, und liefert den Intent. Um Ihre App für diese Art der unterstützten Suche einzurichten, benötigen Sie Folgendes:

Eine Suchkonfiguration

Eine XML-Datei, in der einige Einstellungen für das Suchdialogfeld oder -Widget konfiguriert werden. Dazu gehören Einstellungen für Funktionen wie die Sprachsuche, Suchvorschläge und Hinweistext für das Suchfeld.

Eine durchsuchbare Aktivität

Der Activity, der 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 Dialogfeld für die Suche ist standardmäßig ausgeblendet. Es wird oben auf dem Bildschirm angezeigt, wenn du onSearchRequested() aufrufst und der Nutzer auf die Schaltfläche Suchen tippt.

Ein SearchView-Widget

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

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

Suchbare Konfiguration erstellen

Als Erstes 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 den traditionellen Namen searchable.xml und muss im Projektverzeichnis res/xml/ gespeichert werden.

Die Konfigurationsdatei für die Suche muss das Element <searchable> als Stammknoten enthalten und mindestens ein Attribut 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. Er verweist auf eine Stringressource, bei der es sich um den Anwendungsnamen handeln muss. Der Nutzer kann dieses Label erst sehen, wenn Sie Suchvorschläge für das Schnellsuchfeld aktiviert haben. Das Label wird dann in den Systemeinstellungen in der Liste der durchsuchbaren Elemente angezeigt.

Wir empfehlen, immer das Attribut android:hint anzugeben, das einen Hinweisstring im Suchfeld enthält, bevor Nutzer eine Abfrage eingeben, obwohl dies nicht erforderlich ist. Der Hinweis ist wichtig, weil er den Nutzenden Anhaltspunkte darüber gibt, was sie suchen können.

Für das <searchable>-Element sind mehrere andere Attribute zulässig. Die meisten Attribute werden jedoch erst benötigt, wenn Sie Features wie Suchvorschläge und die Sprachsuche hinzufügen. Ausführliche Informationen zur Konfigurationsdatei für die Suche finden Sie im Referenzdokument zur Konfiguration der Suche.

Suchbare Aktivität erstellen

Eine durchsuchbare Aktivität ist die Activity in Ihrer Anwendung, die Suchvorgänge anhand eines Abfragestrings durchführt und die Suchergebnisse präsentiert.

Wenn der Nutzer im Suchdialogfeld oder -Widget eine Suche ausführt, startet das System die durchsuchbare Aktivität und übergibt sie in einem Intent mit der Aktion ACTION_SEARCH. Die durchsuchbare Aktivität ruft die Abfrage aus dem QUERY-Extra des Intents ab, durchsucht dann Ihre Daten und präsentiert die Ergebnisse.

Da Sie das Suchdialogfeld oder -Widget in jede andere Aktivität in Ihrer App einbinden können, muss das System wissen, welche Aktivität Ihre durchsuchbare Aktivität ist, damit die Suchanfrage ordnungsgemäß gesendet werden kann. Deklarieren Sie also zunächst Ihre durchsuchbaren Aktivitäten in der Android-Manifestdatei.

Eine durchsuchbare Aktivität deklarieren

Erstellen Sie ein Activity, das Suchanfragen ausführt und Ergebnisse präsentiert, falls Sie noch keines haben. 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, mit der der Intent ACTION_SEARCH in einem <intent-filter>-Element akzeptiert wird.
2. Geben Sie die Suchkonfiguration an, die in einem <meta-data>-Element verwendet werden soll.

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 sich er auf die Datei res/xml/searchable.xml.

Suche ausfü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. Rufen Sie die Abfrage ab.
2. Daten durchsuchen
3. Präsentieren Sie die Ergebnisse.

Abfrage erhalten

Wenn ein Nutzer eine Suche über den Suchdialog oder das Such-Widget ausführt, startet das System die durchsuchbare Aktivität und sendet dafür einen ACTION_SEARCH-Intent. Dieser Intent enthält die Suchanfrage im zusätzlichen String QUERY. Prüfen Sie diesen Intent zu Beginn der Aktivität und extrahieren Sie den String. So erhalten Sie beispielsweise die Suchanfrage, wenn Ihre durchsuchbaren Aktivitäten beginnen:

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.

In Daten suchen

Das Speichern und Durchsuchen Ihrer Daten hängt von Ihrer Anwendung ab. Es gibt viele Möglichkeiten, Ihre Daten zu speichern und zu durchsuchen. Dieses Dokument zeigt Ihnen nicht, wie das geht. Überlegen Sie, wie Sie Ihre Daten im Hinblick auf Ihre Anforderungen und Ihr Datenformat speichern und durchsuchen möchten. Hier sind einige Tipps, die Sie anwenden können:

• Wenn die Daten in einer SQLite-Datenbank auf dem Gerät gespeichert sind, kann eine Volltextsuche mit FTS3 anstelle einer LIKE-Abfrage durchgeführt werden, um eine zuverlässigere Suche in Textdaten zu ermöglichen und Ergebnisse deutlich schneller zu erhalten. Unter sqlite.org findest du Informationen zu FTS3 und die SQLiteDatabase-Klasse für Informationen zu SQLite unter Android.
• Wenn Ihre Daten online gespeichert werden, kann die wahrgenommene Suchleistung durch die Datenverbindung des Nutzers beeinträchtigt werden. Es kann sinnvoll sein, eine Fortschrittsanzeige einzublenden, bis die Suche zurückkehrt. Unter android.net finden Sie eine Referenz zu Netzwerk-APIs. Unter ProgressBar finden Sie Informationen zum Anzeigen einer Fortschrittsanzeige.

Präsentation der Ergebnisse

Unabhängig davon, wo sich Ihre Daten befinden und wie Sie danach suchen, empfehlen wir, Suchergebnisse mit einem Adapter für Ihre durchsuchbaren Aktivitäten 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 mithilfe von CursorAdapter auf ein RecyclerView anwenden. Wenn Ihre Daten ein anderes Format haben, können Sie die Erweiterung BaseAdapter erstellen.

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

Dialogfeld „Suchen“ verwenden

Im Suchdialogfeld ist oben auf dem Bildschirm ein unverankertes Suchfeld mit dem App-Symbol links verfügbar. Im Suchdialogfeld werden während der Eingabe Suchvorschläge angezeigt. Wenn der Nutzer eine Suche ausführt, sendet das System die Suchanfrage an eine durchsuchbare Aktivität, die die Suche ausführt.

Das Dialogfeld für die Suche ist standardmäßig ausgeblendet, bis der Nutzer es aktiviert. In Ihrer App kann das Suchdialogfeld durch Aufrufen von onSearchRequested() aktiviert werden. Diese Methode funktioniert jedoch erst, wenn Sie das Suchdialogfeld für die Aktivität aktivieren.

Damit über das Suchdialogfeld Suchvorgänge ausgeführt werden können, müssen Sie dem System angeben, welche suchbare Aktivität Suchanfragen aus dem Suchdialogfeld erhalten muss. Im vorherigen Abschnitt zum Erstellen einer suchbaren Aktivität wird beispielsweise eine durchsuchbare Aktivität mit dem Namen SearchableActivity erstellt. Wenn Sie möchten, dass eine separate Aktivität wie eine mit dem Namen OtherActivity das Suchdialogfeld anzeigt und Suchanfragen an SearchableActivity sendet, 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 im <activity>-Element der entsprechenden Aktivität ein <meta-data>-Element hinzu. Das Element <meta-data> muss das Attribut android:value enthalten, das den Klassennamen der suchbaren Aktivität angibt, und das Attribut android:name mit dem Wert "android.app.default_searchable".

Im Folgenden finden Sie beispielsweise die Deklaration für die durchsuchbare Aktivität SearchableActivity und die andere Aktivität OtherActivity, die SearchableActivity verwendet, um Suchvorgänge auszuführen, die über den Suchdialog ausgeführt werden:

<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 suchbare Aktivität für Suchanfragen verwendet werden soll, aktiviert die Aktivität den Suchdialog. Obwohl sich der Nutzer in dieser Aktivität befindet, aktiviert die Methode onSearchRequested() den Suchdialog. Wenn der Nutzer die Suche ausführt, startet das System SearchableActivity und sendet den Intent ACTION_SEARCH.

Wenn der Suchdialog für jede Aktivität in Ihrer App verfügbar sein soll, fügen Sie das vorherige <meta-data>-Element als untergeordnetes Element des <application>-Elements und nicht jedes <activity>-Elements ein. Auf diese Weise übernimmt jede Aktivität den Wert, stellt den Suchdialog bereit und stellt Suchanfragen für dieselbe suchbare Aktivität bereit. Wenn es mehrere durchsuchbare Aktivitäten gibt, können Sie die standardmäßig durchsuchbare Aktivitäten überschreiben, indem Sie innerhalb der einzelnen Aktivitäten eine andere <meta-data>-Deklaration platzieren.

Da das Suchdialogfeld jetzt für Ihre Aktivitäten aktiviert ist, kann Ihre Anwendung Suchanfragen ausführen.

Dialogfeld „Suchen“ aufrufen

Auf einigen Geräten gibt es zwar eine spezielle Suchschaltfläche, aber das Verhalten dieser Schaltfläche kann je nach Gerät variieren. Auf vielen Geräten gibt es diese Schaltfläche gar nicht. Wenn Sie also das Suchdialogfeld verwenden, müssen Sie in Ihrer UI eine Suchschaltfläche angeben, mit der das Suchdialogfeld durch Aufrufen von onSearchRequested() aktiviert wird.

Fügen Sie beispielsweise dem Optionsmenü oder dem UI-Layout, das onSearchRequested() aufruft, eine Suchschaltfläche hinzu.

Sie können auch die Funktion „Zum Suchen eintippen“ aktivieren. Dadurch wird das Suchdialogfeld aktiviert, wenn der Nutzer mit der Eingabe auf der Tastatur beginnt. Die Tastenanschläge werden in den Suchdialog eingefügt. Sie können die Suche über die Tastatur in Ihrer Aktivität aktivieren, indem Sie während der Methode onCreate() Ihrer Aktivität setDefaultKeyMode oder DEFAULT_KEYS_SEARCH_LOCAL aufrufen.

Die Auswirkungen des Suchdialogfelds auf den Aktivitätslebenszyklus

Das Suchdialogfeld ist ein Dialog-Element am oberen Bildschirmrand. Dies verursacht keine Änderungen im Aktivitätsstapel. Wenn das Suchdialogfeld angezeigt wird, werden daher keine Lebenszyklusmethoden wie onPause() aufgerufen. Ihre Aktivität verliert den Eingabefokus, da der Eingabefokus dem Suchdialogfeld zugewiesen wird.

Wenn Sie bei Aktivierung des Suchdialogfelds benachrichtigt werden möchten, überschreiben Sie die Methode onSearchRequested(). Wenn das System diese Methode aufruft, ist das ein Hinweis darauf, dass der Eingabefokus Ihrer Aktivität nicht mehr auf das Suchdialogfeld gesetzt wird, sodass Sie für das Ereignis geeignete Maßnahmen ergreifen können, z. B. ein Spiel pausieren. Wenn Sie keine Suchkontextdaten übergeben, wie in einem anderen Abschnitt dieses Dokuments erläutert, beenden Sie die Methode durch Aufrufen der Implementierung der übergeordneten Klasse:

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 Schaltfläche „Zurück“ abbricht, wird der Suchdialog geschlossen und die Aktivität erhält wieder den Eingabefokus. Sie können festlegen, dass Sie benachrichtigt werden, wenn das Suchdialogfeld geschlossen wird. Verwenden Sie dazu setOnDismissListener(), setOnCancelListener() oder beides. Sie müssen nur das OnDismissListener registrieren, da es jedes Mal aufgerufen wird, wenn der Suchdialog geschlossen wird. Das 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, verschwindet das Dialogfeld für die Suche automatisch.

Wenn die aktuelle Aktivität nicht die durchsuchbare Aktivität ist, werden die normalen Ereignisse im Aktivitätslebenszyklus ausgelöst, wenn der Nutzer eine Suche ausführt. Die aktuelle Aktivität erhält onPause(), wie unter Einführung in Aktivitäten beschrieben. Wenn es sich bei der aktuellen Aktivität jedoch um die durchsuchbare Aktivität handelt, geschieht Folgendes:

• Standardmäßig empfängt die durchsuchbare Aktivität den Intent ACTION_SEARCH mit einem Aufruf von onCreate() und eine neue Instanz der Aktivität wird an den Anfang des Aktivitätsstapels gebracht. 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ück zur vorherigen Instanz der durchsuchbaren Aktivität, anstatt die durchsuchbare Aktivität zu verlassen.
• Wenn Sie android:launchMode auf "singleTop" setzen, empfängt die durchsuchbare Aktivität den Intent ACTION_SEARCH mit einem Aufruf von onNewIntent(Intent) und übergibt den neuen Intent ACTION_SEARCH. So könnten Sie z. B. vorgehen, wenn 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);
      }
  }
  

  Verglichen mit dem Beispielcode im Abschnitt zum Durchführen einer Suche befindet sich der gesamte Code zur Verarbeitung des Suchabsichtsinhalts jetzt in der handleIntent()-Methode, sodass sowohl onCreate() als auch onNewIntent() ihn ausführen können.

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

Das zweite Szenario, in dem der Startmodus "singleTop" verwendet wird, ist normalerweise vorzuziehen, da der Nutzer nach einer Suche unter Umständen weitere Suchanfragen ausführen kann und Sie nicht möchten, dass Ihre Anwendung mehrere Instanzen der suchbaren Aktivität erstellt. Wir empfehlen, die durchsuchbare Aktivität im App-Manifest auf den Startmodus "singleTop" 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 bei jeder Suche die Suchabfrage innerhalb der durchsuchbaren Aktivität verfeinern. Wenn Sie jedoch Ihre Suchkriterien auf der Grundlage der Aktivität, mit der der Nutzer eine Suche durchführt, verfeinern möchten, können Sie zusätzliche Daten in dem 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 ACTION_SEARCH-Intent enthalten ist.

Um diese Art von Daten an Ihre durchsuchbare Aktivität zu übergeben, überschreiben Sie die Methode onSearchRequested() für die Aktivität, über die der Nutzer eine Suche durchführen kann, erstellen Sie ein Bundle mit den zusätzlichen Daten und rufen Sie startSearch() auf, um das Suchdialogfeld zu aktivieren. Beispiele:

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 Sie „true“ zurückgeben, wird das Callback-Ereignis erfolgreich verarbeitet und startSearch() aufgerufen, um das Suchdialogfeld zu aktivieren. Nachdem der Nutzer eine Abfrage gesendet hat, wird diese zusammen mit den von Ihnen hinzugefügten Daten an Ihre durchsuchbare Aktivität übergeben. 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 dieselbe Funktion wie das Suchdialogfeld. Die entsprechende Aktivität wird gestartet, wenn der Nutzer eine Suche ausführt, und kann Suchvorschläge machen und eine Sprachsuche durchführen. Wenn Sie das Such-Widget nicht in der App-Leiste platzieren können, können Sie es stattdessen irgendwo im Aktivitätslayout platzieren.

Such-Widget konfigurieren

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

Sie können einen Verweis auf das SearchableInfo abrufen, indem Sie getSearchableInfo() bei 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 sendet Suchanfragen an Ihre durchsuchbare Aktivität. 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 interessieren könnten:

Eine Schaltfläche zum Senden

Standardmäßig gibt es keine Schaltfläche zum Senden einer Suchanfrage. Der Nutzer muss also die Eingabetaste auf der Tastatur drücken, um eine Suche zu starten. Du kannst die Schaltfläche „Senden“ hinzufügen, indem du setSubmitButtonEnabled(true) aufrufst.

Suchanfragenverfeinerung für Suchvorschläge

Wenn Sie Suchvorschläge aktivieren, erwarten Sie in der Regel, dass Nutzer einen Vorschlag auswählen. Es ist aber auch möglich, dass sie die vorgeschlagene Suchanfrage verfeinern möchten. Du kannst neben jedem Vorschlag eine Schaltfläche hinzufügen, über die der Vorschlag in das Suchfeld eingefügt wird, um den Nutzer zu präzisieren, indem du setQueryRefinementEnabled(true) aufrufst.

Die Möglichkeit zum Ein-/Ausschalten der Sichtbarkeit des Suchfelds

Standardmäßig ist das Such-Widget „Symbol“, d. h. es wird nur durch ein Suchsymbol – eine Lupe – dargestellt. Wenn der Nutzer auf das Symbol tippt, wird das Suchfeld erweitert. Wie im vorherigen Beispiel gezeigt, kannst du das Suchfeld standardmäßig anzeigen lassen, indem du setIconifiedByDefault(false) aufrufst. Du kannst die Darstellung des Such-Widgets auch durch Aufrufen von setIconified() ein-/ausschalten.

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

Widget und Dialogfeld verwenden

Wenn Sie das Such-Widget in die App-Leiste als Aktionsansicht einfügen und aktivieren, dass es in der App-Leiste angezeigt werden kann, wenn genug Platz ist, indem Sie android:showAsAction="ifRoom" festlegen, wird das Such-Widget möglicherweise nicht als Aktionsansicht angezeigt. Stattdessen wird im Dreipunkt-Menü möglicherweise ein Menüpunkt 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 Aktionselementen oder Navigationselementen anzuzeigen, sodass der Menüpunkt stattdessen im Dreipunkt-Menü angezeigt wird. Wenn das Element im Dreipunkt-Menü platziert wird, funktioniert es wie ein gewöhnliches Menüelement. Es wird nicht die Aktionsansicht, also das Such-Widget, angezeigt.

In diesem Fall muss der Menüpunkt, an den Sie das Such-Widget anhängen, den Suchdialog aktivieren, wenn der Nutzer ihn im Dreipunkt-Menü auswählt. Implementieren Sie dazu onOptionsItemSelected() für den Menüpunkt „Suchen“ und öffnen Sie das Suchdialogfeld durch Aufrufen von onSearchRequested().

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 Suchdialog oder -Widget eine Sprachsuche hinzufügen. Dazu fügen Sie der durchsuchbaren Konfiguration das Attribut android:voiceSearchMode hinzu. Dadurch wird eine Schaltfläche für die Sprachsuche hinzugefügt, mit der eine Ansage zur Spracheingabe gestartet wird. Wenn der Nutzer zu sprechen aufhört, wird die transkribierte Suchanfrage an Ihre suchbare 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 zum Aktivieren der Sprachsuche erforderlich. Der zweite Wert, launchRecognizer, gibt an, dass die Schaltfläche für die Sprachsuche eine Erkennung starten muss, die 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 Ergebnisse, die zurückgegeben werden sollen. Weitere Informationen zu den verfügbaren Attributen finden Sie in der Referenz zur Suchkonfiguration.

Suchvorschläge hinzufügen

Sowohl das Suchdialogfeld als auch das Such-Widget können mithilfe des Android-Systems Suchvorschläge bereitstellen, 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 bereitstellen:

Letzte Suchvorschläge

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

Dies sind Suchvorschläge, die Sie aus Ihrer eigenen Datenquelle zur Verfügung stellen, damit Nutzer sofort die richtige Schreibweise oder das gewünschte Element auswählen können. Weitere Informationen finden Sie unter Benutzerdefinierte Suchvorschläge hinzufügen.