Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Suchvorschläge hinzufügen

Wenn Sie das Android-Suchdialogfeld oder Such-Widget verwenden, können Sie benutzerdefinierte Suchvorschläge anbieten, die aus Daten in Ihrer App erstellt werden. Wenn Ihre App beispielsweise ein Wörterbuch ist, können Sie Wörter aus dem Wörterbuch vorschlagen, die mit dem Text in das Suchfeld übereinstimmen, bevor der Nutzer seine Anfrage eingegeben hat. Diese Vorschläge sind wertvoll, da sie effektiv vorhersagen können, was der Nutzer möchte, und sofortigen Zugriff darauf ermöglichen. Abbildung 1 zeigt ein Beispiel für einen Suchdialog mit benutzerdefinierten Vorschlägen.

Nachdem Sie benutzerdefinierte Vorschläge angegeben haben, können Sie diese auch im systemweiten Schnellsuchfeld verfügbar machen, um von außerhalb Ihrer App Zugriff auf Ihre Inhalte zu erhalten.

Bevor Sie benutzerdefinierte Vorschläge hinzufügen, implementieren Sie das Android-Suchdialogfeld oder ein Such-Widget für Suchen in Ihrer App. Weitere Informationen finden Sie unter Suchoberfläche erstellen und Contentanbieter.

Grundlagen

Abbildung 1: Screenshot eines Suchdialogs mit benutzerdefinierten Suchvorschlägen.

Wenn der Nutzer einen benutzerdefinierten Vorschlag auswählt, sendet das System eine Intent an Ihre suchbare Aktivität. Im Gegensatz zu einer normalen Suchanfrage, bei der ein Intent mit der Aktion ACTION_SEARCH gesendet wird, können Sie stattdessen benutzerdefinierte Vorschläge zur Verwendung von ACTION_VIEW oder einer anderen Intent-Aktion definieren und Daten einschließen, die für den ausgewählten Vorschlag relevant sind. Wenn der Nutzer im Wörterbuchbeispiel einen Vorschlag auswählt, kann die Anwendung sofort die Definition für dieses Wort öffnen, anstatt im Wörterbuch nach Übereinstimmungen zu suchen.

So stellen Sie benutzerdefinierte Vorschläge bereit:

Implementieren Sie eine einfache suchbare Aktivität, wie unter Suchoberfläche erstellen beschrieben.
Ändern Sie die durchsuchbare Konfiguration mit Informationen über den Contentanbieter, der benutzerdefinierte Vorschläge bereitstellt.
Erstellen Sie eine Tabelle (z. B. in einem SQLiteDatabase) für Ihre Vorschläge und formatieren Sie die Tabelle mit den erforderlichen Spalten.
Erstellen Sie einen Contentanbieter, der Zugriff auf Ihre Vorschlagstabelle hat, und deklarieren Sie diesen in Ihrem Manifest.
Deklarieren Sie den Typ von Intent, der gesendet werden soll, wenn der Nutzer einen Vorschlag auswählt, einschließlich einer benutzerdefinierten Aktion und benutzerdefinierter Daten.

So wie das Android-System das Suchdialogfeld anzeigt, werden auch hier Suchvorschläge angezeigt. Sie benötigen einen Contentanbieter, von dem das System Ihre Vorschläge abrufen kann. Informationen zum Erstellen eines Contentanbieters finden Sie unter Contentanbieter.

Wenn das System erkennt, dass Ihre Aktivität suchbar ist, und Suchvorschläge ausgibt, wird der folgende Vorgang ausgeführt, wenn der Nutzer eine Abfrage eingibt:

Das System führt anhand des eingegebenen Texts eine Abfrage an Ihren Contentanbieter durch, der Ihre Vorschläge verwaltet.
Dein Contentanbieter gibt ein Cursor zurück, das auf alle Vorschläge verweist, die für den Text der Suchanfrage relevant sind.
Das System zeigt die Liste der Vorschläge von Cursor an.

Sobald die benutzerdefinierten Vorschläge angezeigt werden, kann Folgendes passieren:

Gibt der Nutzer einen anderen Buchstaben ein oder ändert er die Abfrage, werden die vorherigen Schritte wiederholt und die Vorschlagsliste wird entsprechend aktualisiert.
Wenn der Nutzer die Suche ausführt, werden die Vorschläge ignoriert und die Suche wird mit dem normalen ACTION_SEARCH-Intent an deine durchsuchbare Aktivität übergeben.
Wenn der Nutzer einen Vorschlag auswählt, wird ein Intent mit einer benutzerdefinierten Aktion und benutzerdefinierten Daten an deine durchsuchbare Aktivität gesendet, damit deine App die vorgeschlagenen Inhalte öffnen kann.

Konfiguration für durchsuchbare Elemente ändern

Damit benutzerdefinierte Vorschläge unterstützt werden, fügen Sie dem <searchable>-Element in Ihrer durchsuchbaren Konfigurationsdatei das Attribut android:searchSuggestAuthority hinzu, 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Je nachdem, welche Art von Intent Sie an jeden Vorschlag anhängen und wie Sie Abfragen an Ihren Contentanbieter formatieren möchten, benötigen Sie möglicherweise zusätzliche Attribute. Die anderen optionalen Attribute werden in den folgenden Abschnitten erläutert.

Contentanbieter erstellen

Informationen zum Erstellen eines Contentanbieters für benutzerdefinierte Vorschläge finden Sie unter Contentanbieter. Ein Inhaltsanbieter für benutzerdefinierte Vorschläge ähnelt jedem anderen Inhaltsanbieter. Allerdings muss für jeden Vorschlag, den Sie angeben, die entsprechende Zeile in Cursor bestimmte Spalten enthalten, die das System versteht und zur Formatierung der Vorschläge verwendet.

Wenn der Nutzer Text in den Suchdialog oder das Such-Widget eingibt, fragt das System Ihren Contentanbieter nach Vorschlägen ab. Dabei wird bei jeder Eingabe eines Buchstabens query() aufgerufen. Bei der Implementierung von query() muss Ihr Contentanbieter Ihre Vorschlagsdaten durchsuchen und einen Cursor zurückgeben, der auf die Zeilen verweist, die er für gute Vorschläge bestimmt.

Details zum Erstellen eines Contentanbieters für benutzerdefinierte Vorschläge werden in den folgenden beiden Abschnitten erläutert:

Vorschlagsabfrage verarbeiten: Wie das System Anfragen an Ihren Contentanbieter sendet und wie diese verarbeitet werden.
Tabelle mit Vorschlägen erstellen: Die Spalten definieren, die das System in dem bei jeder Abfrage zurückgegebenen Cursor erwartet.

Vorschlagsabfrage verarbeiten

Wenn das System Vorschläge von Ihrem Contentanbieter anfordert, wird die Methode query() Ihres Contentanbieters aufgerufen. Implementieren Sie diese Methode, um in den Vorschlagsdaten zu suchen und ein Cursor-Objekt zurückzugeben, das auf die Vorschläge verweist, die Sie für relevant halten.

Hier finden Sie eine Zusammenfassung der Parameter, die das System an die Methode query() übergibt, sortiert in der angegebenen Reihenfolge:

uri: Immer ein Uri-Inhalt im folgenden Format:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Standardmäßig übergibt das System diesen URI und hängt den Abfragetext daran an:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Der Abfragetext am Ende wird mithilfe von URI-Codierungsregeln codiert. Daher müssen Sie ihn möglicherweise vor der Suche decodieren.

Der Teil optional.suggest.path ist nur dann im URI enthalten, wenn Sie einen solchen Pfad in der durchsuchbaren Konfigurationsdatei mit dem Attribut android:searchSuggestPath festlegen. Dies ist nur erforderlich, wenn Sie denselben Contentanbieter für mehrere suchbare Aktivitäten verwenden. Machen Sie in diesem Fall die Quelle der Vorschlagsabfrage eindeutig.

Hinweis: SUGGEST_URI_PATH_QUERY ist nicht der Literalstring im URI, sondern eine Konstante. Verwenden Sie es, wenn Sie auf diesen Pfad verweisen müssen.
projection: Immer null.
selection: Der Wert im Attribut android:searchSuggestSelection der durchsuchbaren Konfigurationsdatei oder „null“, wenn das Attribut android:searchSuggestSelection nicht deklariert wird Im folgenden Abschnitt wird dies näher erläutert.
selectionArgs: Enthält die Suchanfrage als erstes und einziges Element des Arrays, wenn Sie das Attribut android:searchSuggestSelection in der durchsuchbaren Konfiguration deklarieren. Wenn Sie android:searchSuggestSelection nicht deklarieren, ist dieser Parameter null. Im folgenden Abschnitt wird dies näher erläutert.
sortOrder: Immer null.

Das System kann Ihnen den Text der Suchanfrage auf zwei Arten senden. Standardmäßig wird der Abfragetext als letzter Pfad des Inhalts-URI eingefügt, der im Parameter uri übergeben wird. Wenn Sie jedoch einen Auswahlwert in das Attribut android:searchSuggestSelection der durchsuchbaren Konfiguration aufnehmen, wird der Abfragetext stattdessen als erstes Element des String-Arrays selectionArgs übergeben. Diese beiden Optionen werden im Folgenden beschrieben.

Abfrage im URI abrufen

Standardmäßig wird die Abfrage als letztes Segment des uri-Parameters angehängt – einem Uri-Objekt. Verwenden Sie in diesem Fall getLastPathSegment(), um den Abfragetext abzurufen, wie im folgenden Beispiel gezeigt:

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

String query = uri.getLastPathSegment().toLowerCase();

Dadurch wird das letzte Segment von Uri zurückgegeben. Das ist der Abfragetext, den der Nutzer eingibt.

Abfrage in den Auswahlargumenten abrufen

Unter Umständen ist es sinnvoller, wenn die Methode query() alle erforderlichen Werte für die Suche erhält, statt den URI zu verwenden. Außerdem sollten die Parameter selection und selectionArgs die entsprechenden Werte enthalten. Fügen Sie in diesem Fall das Attribut android:searchSuggestSelection der suchbaren Konfiguration mit Ihrem SQLite-Auswahlstring hinzu. Fügen Sie im Auswahlstring ein Fragezeichen (?) als Platzhalter für die eigentliche Suchanfrage ein. Das System ruft query() mit dem Auswahlstring als selection-Parameter und der Suchanfrage als erstes Element im selectionArgs-Array auf.

So können Sie beispielsweise das Attribut android:searchSuggestSelection bilden, um eine Volltextanweisung für die Suche zu erstellen:

<?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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Bei dieser Konfiguration liefert die Methode query() den Parameter selection als "word MATCH ?" und den Parameter selectionArgs als Suchanfrage. Wenn Sie diese als ihre jeweiligen Argumente an die SQLite-Methode query() übergeben, werden sie zusammen synthetisiert. Das Fragezeichen wird also durch den Abfragetext ersetzt. Wenn Sie Vorschlagsabfragen auf diese Weise erhalten und dem Abfragetext Platzhalter hinzufügen müssen, hängen Sie diese an oder stellen Sie sie dem Parameter selectionArgs voran, da dieser Wert in Anführungszeichen gesetzt und anstelle des Fragezeichens eingefügt wird.

Ein weiteres Attribut im vorherigen Beispiel ist android:searchSuggestIntentAction. Damit wird die Intent-Aktion definiert, die mit jedem Intent gesendet wird, wenn der Nutzer einen Vorschlag auswählt. Dies wird im Abschnitt Intent für Vorschläge erklären ausführlicher erläutert.

Tipp:Wenn Sie keine Auswahlklausel im Attribut android:searchSuggestSelection definieren, aber den Abfragetext im Parameter selectionArgs erhalten möchten, geben Sie für das Attribut android:searchSuggestSelection einen Wert ungleich Null an. Dadurch wird die Abfrage von selectionArgs ausgelöst, sodass Sie den selection-Parameter ignorieren können. Auf diese Weise können Sie die eigentliche Auswahlklausel stattdessen auf einer niedrigeren Ebene definieren, sodass Ihr Contentanbieter sie nicht verarbeiten muss.

Tabelle mit Vorschlägen erstellen

Wenn Sie mit einem Cursor Vorschläge an das System zurückgeben, erwartet das System bestimmte Spalten in jeder Zeile. Unabhängig davon, ob Sie Ihre Vorschlagsdaten in einer SQLite-Datenbank auf dem Gerät, in einer Datenbank auf einem Webserver oder in einem anderen Format auf dem Gerät oder im Web speichern, formatieren Sie die Vorschläge als Zeilen in einer Tabelle und präsentieren Sie sie mit einem Cursor.

Hinweis:Wenn Ihre Suchvorschläge nicht in einem Tabellenformat wie einer SQLite-Tabelle mit den vom System erforderlichen Spalten gespeichert sind, können Sie die Vorschlagsdaten nach Übereinstimmungen durchsuchen und sie dann bei jeder Anfrage in die erforderliche Tabelle formatieren. Erstellen Sie dazu ein MatrixCursor mit den erforderlichen Spaltennamen und fügen Sie dann mit addRow(Object[]) eine Zeile für jeden Vorschlag hinzu. Gib das Endprodukt über die Methode query() deines Contentanbieters zurück.

Das System versteht mehrere Spalten, von denen sind jedoch nur zwei erforderlich:

_ID: Eine eindeutige Zeilen-ID für Ganzzahlen für jeden Vorschlag. Das System benötigt dies, um Vorschläge in einem ListView zu präsentieren.
SUGGEST_COLUMN_TEXT_1: Der String, der als Vorschlag angezeigt wird.

Die folgenden Spalten sind alle optional. Die meisten werden in den folgenden Abschnitten näher erläutert.

SUGGEST_COLUMN_TEXT_2: Ein String. Wenn Ihre Cursor diese Spalte enthält, werden alle Vorschläge in einem zweizeiligen Format bereitgestellt. Der String in dieser Spalte wird als zweite, kleinere Textzeile unter dem primären Vorschlagstext angezeigt. Er kann null oder leer sein, um anzugeben, dass kein Sekundärtext vorhanden ist.
SUGGEST_COLUMN_ICON_1: Ein Drawable-String für eine Ressource, einen Inhalt oder eine Datei-URI. Wenn dein Cursor diese Spalte enthält, werden alle Vorschläge im Symbol-Plus-Text-Format mit dem Drawable-Symbol auf der linken Seite bereitgestellt. Dieser kann null oder null sein, um anzuzeigen, dass in dieser Zeile kein Symbol vorhanden ist.
SUGGEST_COLUMN_ICON_2: Ein Drawable-String für eine Ressource, einen Inhalt oder eine Datei-URI. Wenn Ihre Cursor diese Spalte enthält, werden alle Vorschläge im Symbol-Plus-Text-Format mit dem Symbol auf der rechten Seite bereitgestellt. Dieser kann null oder null sein, um anzuzeigen, dass in dieser Zeile kein Symbol vorhanden ist.
SUGGEST_COLUMN_INTENT_ACTION: Ein Intent-Aktionsstring. Wenn diese Spalte vorhanden ist und einen Wert in der angegebenen Zeile enthält, wird die hier definierte Aktion beim Erstellen des Vorschlags-Intents verwendet. Wenn das Element nicht angegeben ist, wird die Aktion aus dem Feld android:searchSuggestIntentAction in der durchsuchbaren Konfiguration ausgeführt. Wenn Ihre Aktion für alle Vorschläge gleich ist, ist es effizienter, sie mit android:searchSuggestIntentAction anzugeben und diese Spalte wegzulassen.
SUGGEST_COLUMN_INTENT_DATA: Ein Daten-URI-String. Wenn diese Spalte vorhanden ist und einen Wert in der angegebenen Zeile enthält, werden diese Daten verwendet, um den Intent für den Vorschlag zu bilden. Wenn das Element nicht angegeben ist, werden die Daten aus dem Feld android:searchSuggestIntentData in der durchsuchbaren Konfiguration entnommen. Wenn keine der Quellen angegeben ist, enthält das Datenfeld des Intents den Wert null. Wenn die Daten für alle Vorschläge gleich sind oder mit einem konstanten Teil und einer bestimmten ID beschrieben werden können, ist es effizienter, sie mit android:searchSuggestIntentData anzugeben und diese Spalte wegzulassen.
SUGGEST_COLUMN_INTENT_DATA_ID: Ein URI-Pfadstring. Wenn diese Spalte vorhanden ist und einen Wert in der angegebenen Zeile enthält, wird „/“ und dieser Wert an das Datenfeld im Intent angehängt. Verwende diese Option nur, wenn das durch das Attribut android:searchSuggestIntentData in der durchsuchbaren Konfiguration angegebene Datenfeld bereits auf einen geeigneten Basisstring festgelegt ist.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Beliebige Daten. Wenn diese Spalte vorhanden ist und einen Wert in einer bestimmten Zeile enthält, sind dies die zusätzlichen Daten, die zum Erstellen des Vorschlags-Intents verwendet werden. Wenn nicht angegeben, ist das zusätzliche Datenfeld des Intents null. In dieser Spalte können Vorschläge zusätzliche Daten enthalten, die als zusätzliche Daten im Schlüssel EXTRA_DATA_KEY des Intents enthalten sind.
SUGGEST_COLUMN_QUERY: Wenn diese Spalte vorhanden ist und dieses Element in der angegebenen Zeile vorhanden ist, sind dies die Daten, die zum Erstellen der Abfrage für den Vorschlag verwendet werden. Sie sind als Extras im Schlüssel QUERY des Intents enthalten. Dies ist erforderlich, wenn die Aktion des Vorschlags ACTION_SEARCH lautet, ansonsten optional.
SUGGEST_COLUMN_SHORTCUT_ID: Wird nur verwendet, wenn Vorschläge für das Schnellsuchfeld angezeigt werden. In dieser Spalte wird angegeben, ob ein Suchvorschlag als Verknüpfung gespeichert und ob er validiert werden muss. Kurzbefehle werden normalerweise erstellt, wenn der Nutzer auf einen Vorschlag im Schnellsuchfeld tippt. Wenn es fehlt, wird das Ergebnis als Verknüpfung gespeichert und nie aktualisiert. Wenn SUGGEST_NEVER_MAKE_SHORTCUT festgelegt ist, wird das Ergebnis nicht als Verknüpfung gespeichert. Andernfalls wird die Verknüpfungs-ID verwendet, um mit SUGGEST_URI_PATH_SHORTCUT nach einem aktuellen Vorschlag zu suchen.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Wird nur verwendet, wenn Vorschläge für das Schnellsuchfeld angezeigt werden. In dieser Spalte wird angegeben, dass anstelle eines Symbols von SUGGEST_COLUMN_ICON_2 ein rotierendes Ladesymbol angezeigt werden muss, während die Verknüpfung für diesen Vorschlag im Schnellsuchfeld aktualisiert wird.

Die meisten dieser Spalten werden in den folgenden Abschnitten näher erläutert.

Intent für Vorschläge deklarieren

Wenn der Nutzer einen Vorschlag aus der Liste auswählt, die unter dem Suchdialogfeld oder -Widget angezeigt wird, sendet das System eine benutzerdefinierte Intent an Ihre suchbare Aktivität. Sie müssen die Aktion und die Daten für den Intent definieren.

Intent-Aktion deklarieren

Die häufigste Intent-Aktion für einen benutzerdefinierten Vorschlag ist ACTION_VIEW. Sie eignet sich, wenn Sie etwas öffnen möchten, z. B. die Definition eines Wortes, die Kontaktdaten einer Person oder eine Webseite. Die Intent-Aktion kann jedoch jede andere Aktion sein und sich je nach Vorschlag unterscheiden.

Je nachdem, ob für alle Vorschläge dieselbe Intent-Aktion verwendet werden soll, können Sie die Aktion auf zwei Arten definieren:

Verwende das Attribut android:searchSuggestIntentAction der durchsuchbaren Konfigurationsdatei, um die Aktion für alle Vorschläge zu definieren, 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW" >
</searchable>

In der Spalte SUGGEST_COLUMN_INTENT_ACTION können Sie die Aktion für einzelne Vorschläge definieren. Fügen Sie dazu der Tabelle mit Vorschlägen die Spalte SUGGEST_COLUMN_INTENT_ACTION hinzu und fügen Sie ihr für jeden Vorschlag die zu verwendende Aktion hinzu, z. B. "android.intent.action.VIEW".

Diese beiden Verfahren lassen sich auch kombinieren. Sie können beispielsweise das Attribut android:searchSuggestIntentAction in eine Aktion aufnehmen, die standardmäßig mit allen Vorschlägen verwendet werden soll, und diese Aktion dann für einige Vorschläge überschreiben, indem Sie in der Spalte SUGGEST_COLUMN_INTENT_ACTION eine andere Aktion deklarieren. Wenn Sie keinen Wert in die Spalte SUGGEST_COLUMN_INTENT_ACTION einfügen, wird der Intent verwendet, der im Attribut android:searchSuggestIntentAction angegeben ist.

Hinweis:Wenn du das Attribut android:searchSuggestIntentAction nicht in die durchsuchbare Konfiguration aufnimmst, muss du für jeden Vorschlag einen Wert in die Spalte SUGGEST_COLUMN_INTENT_ACTION einfügen. Andernfalls schlägt der Intent fehl.

Intent-Daten deklarieren

Wenn der Nutzer einen Vorschlag auswählt, empfängt Ihre durchsuchbare Aktivität den Intent mit der von Ihnen definierten Aktion (wie im vorherigen Abschnitt beschrieben). Der Intent muss jedoch auch Daten für Ihre Aktivität enthalten, damit der ausgewählte Vorschlag identifiziert werden kann. Insbesondere müssen die Daten für jeden Vorschlag eindeutig sein, z. B. die Zeilen-ID für den Vorschlag in Ihrer SQLite-Tabelle. Wenn der Intent empfangen wird, können Sie die angehängten Daten mit getData() oder getDataString() abrufen.

Sie können die im Intent enthaltenen Daten auf zwei Arten definieren:

Definieren Sie die Daten für jeden Vorschlag in der Spalte SUGGEST_COLUMN_INTENT_DATA der Vorschlagstabelle.
Geben Sie in der Vorschlagstabelle für jeden Intent alle erforderlichen Dateninformationen an. Fügen Sie dazu die Spalte SUGGEST_COLUMN_INTENT_DATA ein und füllen Sie diese dann mit eindeutigen Daten für jede Zeile. Die Daten aus dieser Spalte werden genau so mit dem Intent verknüpft, wie Sie sie in dieser Spalte definieren. Sie können ihn dann mit getData() oder getDataString() abrufen.

Tipp: In der Regel ist es einfacher, die Zeilen-ID der Tabelle als Intent-Daten zu verwenden, da sie immer eindeutig ist. Am einfachsten ist es, den Spaltennamen SUGGEST_COLUMN_INTENT_DATA als Alias für die Zeilen-ID-Spalte zu verwenden.
Teilen Sie einen Daten-URI in zwei Teile auf: den für alle Vorschläge gemeinsamen Teil und den eindeutigen Teil für jeden Vorschlag. Füge diese Teile dem Attribut android:searchSuggestintentData der durchsuchbaren Konfiguration bzw. der Spalte SUGGEST_COLUMN_INTENT_DATA_ID der Vorschlagstabelle hinzu.
Das folgende Beispiel zeigt, wie Sie den Teil des URI deklarieren, der für alle Vorschläge im Attribut android:searchSuggestIntentData Ihrer durchsuchbaren Konfiguration gleich ist:
```
  <?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"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW"
      android:searchSuggestIntentData="content://com.example/datatable" >
  </searchable>
  
```
Fügen Sie den endgültigen Pfad für jeden Vorschlag – den eindeutigen Teil – in die Spalte SUGGEST_COLUMN_INTENT_DATA_ID der Tabelle mit Vorschlägen ein. Wenn der Nutzer einen Vorschlag auswählt, übernimmt das System den String aus android:searchSuggestIntentData, hängt einen Schrägstrich (/) an und fügt dann den entsprechenden Wert aus der Spalte SUGGEST_COLUMN_INTENT_DATA_ID hinzu, um einen vollständigen Inhalts-URI zu bilden. Anschließend können Sie den Uri mit getData() abrufen.

Weitere Daten hinzufügen

Wenn Sie weitere Informationen angeben möchten, können Sie eine weitere Tabellenspalte wie SUGGEST_COLUMN_INTENT_EXTRA_DATA hinzufügen, in der zusätzliche Informationen zum Vorschlag gespeichert werden können. Die in dieser Spalte gespeicherten Daten werden im EXTRA_DATA_KEY des zusätzlichen Bundles des Intents platziert.

Intent verarbeiten

Nachdem Sie benutzerdefinierte Suchvorschläge mit benutzerdefinierten Intents bereitgestellt haben, müssen Ihre durchsuchbaren Aktivitäten diese Intents verarbeiten, wenn der Nutzer einen Vorschlag auswählt. Dies gilt zusätzlich zur Verarbeitung des Intents ACTION_SEARCH, der im Rahmen Ihrer durchsuchbaren Aktivitäten bereits ausgeführt wird. Hier ein Beispiel, wie Sie die Intents während des onCreate()-Callbacks Ihrer Aktivität verarbeiten können:

Kotlin

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Java

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

In diesem Beispiel ist die Intent-Aktion ACTION_VIEW und die Daten enthalten einen vollständigen URI, der auf das vorgeschlagene Element verweist, wie der String android:searchSuggestIntentData und die Spalte SUGGEST_COLUMN_INTENT_DATA_ID synthetisiert haben. Der URI wird dann an die lokale Methode showResult() übergeben, die den Contentanbieter nach dem durch den URI angegebenen Element abfragt.

Hinweis:Du musst deiner Android-Manifestdatei keinen Intent-Filter für die Intent-Aktion hinzufügen, die du mit dem Attribut android:searchSuggestIntentAction oder der Spalte SUGGEST_COLUMN_INTENT_ACTION definiert hast. Das System öffnet die durchsuchbare Aktivität mit dem Namen, um den Intent des Vorschlags zu übermitteln. Daher muss für die Aktivität die akzeptierte Aktion nicht deklariert werden.

Abfragetext neu schreiben

Wenn der Nutzer mit Richtungssteuerungen wie einem Trackball oder einem Steuerkreuz durch die Vorschlagsliste navigiert, wird der Abfragetext standardmäßig nicht aktualisiert. Sie können den Abfragetext des Nutzers jedoch vorübergehend so umschreiben, wie er im Textfeld erscheint, und zwar mit einer Abfrage, die dem Vorschlag im Fokus entspricht. So kann der Nutzer die vorgeschlagene Suchanfrage sehen und das Suchfeld auswählen und die Abfrage bearbeiten, bevor er sie als Suche weiterleitet.

So können Sie den Abfragetext neu schreiben:

Fügen Sie der durchsuchbaren Konfiguration das Attribut android:searchMode mit dem Wert "queryRewriteFromText" hinzu. In diesem Fall wird der Inhalt aus der Spalte SUGGEST_COLUMN_TEXT_1 des Vorschlags verwendet, um den Abfragetext neu zu schreiben.
Fügen Sie der durchsuchbaren Konfiguration das Attribut android:searchMode mit dem Wert "queryRewriteFromData" hinzu. In diesem Fall wird der Inhalt aus der Spalte SUGGEST_COLUMN_INTENT_DATA des Vorschlags verwendet, um den Abfragetext neu zu schreiben. Verwenden Sie dieses Flag nur bei URIs oder anderen Datenformaten, die für Nutzer sichtbar sein sollen, z. B. HTTP-URLs. Verwenden Sie keine internen URI-Schemata, um die Abfrage auf diese Weise umzuschreiben.
Geben Sie in der Spalte SUGGEST_COLUMN_QUERY Ihrer Tabelle mit Vorschlägen einen eindeutigen Abfragetextstring an. Wenn diese Spalte vorhanden ist und einen Wert für den aktuellen Vorschlag enthält, wird sie verwendet, um den Abfragetext neu zu schreiben und eine der vorherigen Implementierungen zu überschreiben.

Suchvorschläge im Schnellsuchfeld anzeigen

Nachdem Sie Ihre Anwendung für die Bereitstellung benutzerdefinierter Suchvorschläge konfiguriert haben, können Sie diese im global zugänglichen Schnellsuchfeld ganz einfach verfügbar machen. Dazu müssen Sie lediglich die durchsuchbare Konfiguration so ändern, dass android:includeInGlobalSearch mit dem Wert "true" enthalten ist.

Zusätzliche Arbeit ist nur dann erforderlich, wenn Ihr Contentanbieter eine Leseberechtigung anfordert. In diesem Fall müssen Sie ein <path-permission>-Element hinzufügen, damit der Anbieter Ihrem Inhaltsanbieter Lesezugriff für das Schnellsuchfeld gewährt, wie im folgenden Beispiel gezeigt:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

In diesem Beispiel schränkt der Anbieter den Lese- und Schreibzugriff auf den Inhalt ein. Das Element <path-permission> ergänzt die Einschränkung, indem es Lesezugriff auf Inhalte im Pfadpräfix "/search_suggest_query" gewährt, wenn die Berechtigung "android.permission.GLOBAL_SEARCH" vorhanden ist. Dadurch wird der Zugriff auf das Schnellsuchfeld gewährt, damit es bei Ihrem Contentanbieter Vorschläge abfragen kann.

Wenn Ihr Inhaltsanbieter keine Leseberechtigungen erzwingt, liest das Schnellsuchfeld ihn standardmäßig.

Vorschläge auf einem Gerät aktivieren

Standardmäßig sind Apps nicht für die Bereitstellung von Vorschlägen im Schnellsuchfeld aktiviert, selbst wenn sie entsprechend konfiguriert sind. Der Nutzer entscheidet, ob Vorschläge aus Ihrer App in das Schnellsuchfeld aufgenommen werden sollen, indem er unter Einstellungen > Suche die Option Durchsuchbare Elemente öffnet und Ihre App als durchsuchbares Element aktiviert.

Jede App, die für das Schnellsuchfeld verfügbar ist, hat einen Eintrag auf der Einstellungsseite Durchsuchbare Elemente. Der Eintrag enthält den Namen der Anwendung und eine kurze Beschreibung dessen, welche Inhalte in der Anwendung suchbar sind und für Vorschläge im Schnellsuchfeld zur Verfügung gestellt werden. Um den Beschreibungstext für die durchsuchbare Anwendung zu definieren, füge der durchsuchbaren Konfiguration das Attribut android:searchSettingsDescription hinzu, 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

Der String für android:searchSettingsDescription sollte so prägnant wie möglich sein und den Inhalt angeben, der suchbar ist. Beispiele: „Künstler, Alben und Titel“ für eine Musik-App oder „Gespeicherte Notizen“ für eine Notizblock-App. Diese Beschreibung ist wichtig, damit Nutzer wissen, welche Art von Vorschlägen zur Verfügung stehen. Geben Sie dieses Attribut immer an, wenn android:includeInGlobalSearch wahr ist.

Da der Nutzer das Einstellungsmenü aufrufen muss, um Suchvorschläge für Ihre App zu aktivieren, sollten Sie überlegen, wie Sie die Suche an Ihre Nutzer weitergeben können, wenn die Suche ein wichtiger Aspekt Ihrer App ist. Sie können beispielsweise beim ersten Start der App einen Hinweis angeben, in dem erklärt wird, wie Suchvorschläge für das Schnellsuchfeld aktiviert werden.

Tastenkombinationen für Vorschläge im Schnellsuchfeld verwalten

Vorschläge, die der Nutzer im Schnellsuchfeld auswählt, können automatisch in Verknüpfungen umgewandelt werden. Dies sind Vorschläge, die das System von Ihrem Contentanbieter kopiert, damit es schnell auf den Vorschlag zugreifen kann, ohne den Contentanbieter noch einmal abfragen zu müssen.

Diese Option ist standardmäßig für alle Vorschläge aktiviert, die über das Schnellsuchfeld abgerufen werden. Wenn sich Ihre Vorschlagsdaten jedoch im Laufe der Zeit ändern, können Sie eine Aktualisierung der Tastenkombinationen anfordern. Wenn sich Ihre Vorschläge beispielsweise auf dynamische Daten wie den Anwesenheitsstatus eines Kontakts beziehen, fordern Sie an, dass die Vorschläge aktualisiert werden, wenn sie dem Nutzer angezeigt werden. Fügen Sie dazu SUGGEST_COLUMN_SHORTCUT_ID in die Vorschlagstabelle ein. Mithilfe dieser Spalte können Sie das Verhalten von Kurzbefehlen für jeden Vorschlag auf eine der folgenden Arten konfigurieren:

Lassen Sie das Schnellsuchfeld bei Ihrem Inhaltsanbieter noch einmal nach einer neuen Version der Verknüpfung für Vorschläge fragen.

Geben Sie in der Spalte SUGGEST_COLUMN_SHORTCUT_ID einen Wert für den Vorschlag ein, der jedes Mal, wenn die Verknüpfung angezeigt wird, für eine neue Version abgefragt werden soll. Die Verknüpfung wird schnell mit den zuletzt verfügbaren Daten angezeigt, bis die Aktualisierungsabfrage zurückgegeben wird. Dann wird der Vorschlag mit den neuen Informationen aktualisiert. Die Aktualisierungsabfrage wird mit dem URI-Pfad SUGGEST_URI_PATH_SHORTCUT statt SUGGEST_URI_PATH_QUERY an Ihren Contentanbieter gesendet.

Die zurückgegebene Cursor muss einen Vorschlag enthalten, der dieselben Spalten wie der ursprüngliche Vorschlag verwendet, oder leer sein. Dies weist darauf hin, dass die Verknüpfung nicht mehr gültig ist. In diesem Fall verschwindet der Vorschlag und die Verknüpfung wird entfernt.

Wenn sich ein Vorschlag auf Daten bezieht, deren Aktualisierung länger dauert, z. B. eine netzwerkbasierte Aktualisierung, können Sie der Vorschlagstabelle auch die Spalte SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING mit dem Wert „true“ hinzufügen. Damit wird für das rechte Symbol ein rotierendes Fortschrittssymbol angezeigt, bis die Aktualisierung abgeschlossen ist. Bei einem anderen Wert als „true“ wird das rotierende Ladesymbol nicht angezeigt.
Verhindert, dass der Vorschlag in eine Verknüpfung kopiert wird.

Geben Sie in der Spalte SUGGEST_COLUMN_SHORTCUT_ID den Wert SUGGEST_NEVER_MAKE_SHORTCUT an. In diesem Fall wird der Vorschlag nie in eine Verknüpfung kopiert. Dies ist nur erforderlich, wenn der zuvor kopierte Vorschlag nicht angezeigt werden soll. Wenn Sie einen normalen Wert für die Spalte angeben, wird die Vorschlagsverknüpfung nur angezeigt, bis die Aktualisierungsabfrage zurückgegeben wird.
Standardverhalten für Tastenkombinationen anwenden.

Lassen Sie SUGGEST_COLUMN_SHORTCUT_ID für jeden Vorschlag, der nicht geändert wird und als Verknüpfung gespeichert werden kann, leer.

Wenn sich keiner Ihrer Vorschläge ändert, benötigen Sie die Spalte SUGGEST_COLUMN_SHORTCUT_ID nicht.

Rangfolge von Vorschlägen im Schnellsuchfeld

Nachdem Sie die Suchvorschläge Ihrer App im Schnellsuchfeld verfügbar gemacht haben, bestimmt die Rangfolge des Schnellsuchfelds, wie die Vorschläge dem Nutzer bei einer bestimmten Suchanfrage angezeigt werden. Dies kann davon abhängen, wie viele andere Anwendungen Ergebnisse für diese Abfrage haben und wie oft der Nutzer Ihre Ergebnisse im Vergleich zu denen aus anderen Anwendungen auswählt. Es gibt keine Garantie dafür, welches Ranking Ihre Vorschläge einstufen oder ob sie bei einer bestimmten Abfrage überhaupt angezeigt werden. Im Allgemeinen erhöht sich durch die Bereitstellung hochwertiger Ergebnisse die Wahrscheinlichkeit, dass die Vorschläge Ihrer App an einer hervorgehobenen Position angezeigt werden. Außerdem erhalten Apps, die Vorschläge von geringer Qualität liefern, eher ein niedrigeres Ranking oder werden nicht angezeigt.