Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Suchvorschläge hinzufügen

Wenn Sie das Android-Suchdialogfeld oder das Such-Widget verwenden, können Sie benutzerdefinierte Suchvorschläge bereitstellen, 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 übereinstimmen, der in das Suchfeld eingegeben wurde, bevor der Nutzer seine Anfrage fertig eingegeben hat. Diese Vorschläge sind wertvoll, weil sie effektiv vorhersagen können, was der Nutzer möchte, und sofortigen Zugriff darauf ermöglichen. Abbildung 1 zeigt ein Beispiel für ein Suchdialogfeld mit benutzerdefinierten Vorschlägen.

Nachdem Sie benutzerdefinierte Vorschläge bereitgestellt haben, können Sie sie auch für das systemweite Schnellsuchefeld verfügbar machen und so den Zugriff auf Ihre Inhalte von außerhalb Ihrer App ermöglichen.

Bevor Sie benutzerdefinierte Vorschläge hinzufügen, müssen Sie den Android-Suchdialog oder ein Such-Widget für die Suche in Ihrer App implementieren. Weitere Informationen finden Sie unter Suchoberfläche erstellen und Contentanbieter.

Grundlagen

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

Wenn der Nutzer einen benutzerdefinierten Vorschlag auswählt, sendet das System ein Intent an Ihre durchsuchbare Aktivität. Im Gegensatz zu einer normalen Suchanfrage, bei der eine Intention mit der Aktion ACTION_SEARCH gesendet wird, können Sie für Ihre benutzerdefinierten Vorschläge stattdessen ACTION_VIEW oder eine andere Intent-Aktion definieren und auch Daten einfügen, die für den ausgewählten Vorschlag relevant sind. Wenn der Nutzer im Wörterbuchbeispiel einen Vorschlag auswählt, kann die App sofort die Definition für dieses Wort öffnen, anstatt das Wörterbuch nach Übereinstimmungen zu durchsuchen.

So geben Sie benutzerdefinierte Vorschläge an:

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

Das Android-System zeigt nicht nur das Suchdialogfeld, sondern auch Ihre Suchvorschläge an. 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 feststellt, dass Ihre Aktivität durchsuchbar ist, und Suchvorschläge anzeigt, läuft Folgendes ab, wenn der Nutzer eine Suchanfrage eingibt:

Das System verwendet den Text der Suchanfrage – also alles, was bisher eingegeben wurde – und führt eine Anfrage an Ihren Inhaltsanbieter aus, der Ihre Vorschläge verwaltet.
Ihr Contentanbieter gibt einen Cursor zurück, der auf alle Vorschläge verweist, die für den Text der Suchanfrage relevant sind.
Das System zeigt die Liste der Vorschläge an, die von Cursor bereitgestellt werden.

Nachdem die benutzerdefinierten Vorschläge angezeigt wurden, kann Folgendes passieren:

Wenn der Nutzer einen weiteren Buchstaben eingibt oder die Suchanfrage auf andere Weise ändert, werden die vorherigen Schritte wiederholt und die Vorschlagsliste entsprechend aktualisiert.
Wenn der Nutzer die Suche ausführt, werden die Vorschläge ignoriert und die Suche wird über den normalen ACTION_SEARCH-Intent an Ihre durchsuchbare Aktivität gesendet.
Wenn der Nutzer einen Vorschlag auswählt, wird ein Intent mit einer benutzerdefinierten Aktion und benutzerdefinierten Daten an Ihre durchsuchbare Aktivität gesendet, damit Ihre App die vorgeschlagenen Inhalte öffnen kann.

Suchkonfiguration ändern

Wenn Sie Unterstützung für benutzerdefinierte Vorschläge hinzufügen möchten, fügen Sie das Attribut android:searchSuggestAuthority dem Element <searchable> in Ihrer durchsuchbaren Konfigurationsdatei 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 nach Art der Intention, die Sie jeder Empfehlung zuweisen, und je nachdem, wie Sie Anfragen an Ihren Contentanbieter formatieren möchten, benötigen Sie möglicherweise zusätzliche Attribute. Die anderen optionalen Attribute werden in den folgenden Abschnitten beschrieben.

Contentanbieter erstellen

Wenn Sie einen Contentanbieter für benutzerdefinierte Vorschläge erstellen möchten, lesen Sie zuerst den Abschnitt Contentanbieter. Ein Inhaltsanbieter für benutzerdefinierte Vorschläge ähnelt jedem anderen Inhaltsanbieter. Für jeden Vorschlag, den Sie machen, muss die entsprechende Zeile in der Cursor jedoch bestimmte Spalten enthalten, die das System versteht und zum Formatieren der Vorschläge verwendet.

Wenn der Nutzer Text in das Suchdialogfeld oder das Such-Widget eingibt, fragt das System Ihren Contentanbieter nach Vorschlägen, indem es query() aufruft, sobald ein Buchstabe eingegeben wird. Bei der Implementierung von query() muss Ihr Contentanbieter Ihre Vorschlagsdaten durchsuchen und einen Cursor zurückgeben, der auf die Zeilen verweist, die als gute Vorschläge gelten.

Details zum Erstellen eines Contentanbieters für benutzerdefinierte Vorschläge finden Sie in den folgenden beiden Abschnitten:

Vorschlagsanfrage bearbeiten: Wie das System Anfragen an Ihren Content-Anbieter sendet und wie Sie diese verarbeiten.
Vorschlagstabelle erstellen: So definieren Sie die Spalten, die das System in der Cursor erwartet, die mit jeder Abfrage zurückgegeben wird.

Vorschlagsanfrage verarbeiten

Wenn das System Vorschläge von Ihrem Content-Anbieter anfordert, wird die query()-Methode Ihres Content-Anbieters aufgerufen. Implementieren Sie diese Methode, um Ihre Vorschlagsdaten zu durchsuchen und eine Cursor zurückzugeben, die auf die Vorschläge verweist, die Sie für relevant halten.

Hier ist eine Zusammenfassung der Parameter, die das System in der angegebenen Reihenfolge an Ihre query()-Methode übergibt:

uri: Immer ein Inhalt Uri, der so formatiert ist:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

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

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

Der Abfragetext am Ende wird nach URI-Codierungsregeln codiert. Möglicherweise müssen Sie ihn also decodieren, bevor Sie eine Suche durchführen.

Der Teil optional.suggest.path ist nur im URI enthalten, wenn Sie einen solchen Pfad in Ihrer durchsuchbaren Konfigurationsdatei mit dem Attribut android:searchSuggestPath festlegen. Das ist nur erforderlich, wenn Sie denselben Contentanbieter für mehrere durchsuchbare Aktivitäten verwenden. Wenn dies der Fall ist, müssen Sie die Quelle der Vorschlagsanfrage eindeutig kennzeichnen.

Hinweis:SUGGEST_URI_PATH_QUERY ist nicht der Literalstring, der im URI angegeben ist, sondern eine Konstante. Verwenden Sie ihn, wenn Sie auf diesen Pfad verweisen müssen.
projection: Immer null.
selection: Der im Attribut android:searchSuggestSelection Ihrer durchsuchbaren Konfigurationsdatei angegebene Wert oder „null“, wenn Sie das Attribut android:searchSuggestSelection nicht deklarieren. 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 Ihrer 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 Ihrer 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 Parameters uri angehängt, einem Uri-Objekt. Verwenden Sie getLastPathSegment(), um den Abfragetext in diesem Fall abzurufen, wie im folgenden Beispiel gezeigt:

Kotlin

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

Java

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

Gibt das letzte Segment von Uri zurück, also den Suchtext, den der Nutzer eingibt.

Abfrage in den Auswahlargumenten abrufen

Anstatt den URI zu verwenden, ist es möglicherweise sinnvoller, wenn Ihre query()-Methode alles erhält, was sie für die Suche benötigt. In diesem Fall sollten die Parameter selection und selectionArgs die entsprechenden Werte enthalten. Fügen Sie in diesem Fall das Attribut android:searchSuggestSelection mit Ihrem SQLite-Auswahlstring zu Ihrer durchsuchbaren Konfiguration hinzu. Fügen Sie in den Auswahlstring ein Fragezeichen (?) als Platzhalter für die tatsächliche 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 verwenden, um eine Volltextsuchanweisung 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 wird der Parameter selection von der Methode query() als "word MATCH ?" und der Parameter selectionArgs als Suchanfrage übergeben. Wenn Sie diese als entsprechende Argumente an eine SQLite-query()-Methode übergeben, werden sie zusammengeführt. Das Fragezeichen wird also durch den Abfragetext ersetzt. Wenn Sie auf diese Weise Vorschlagsanfragen erhalten und dem Abfragetext Platzhalter hinzufügen müssen, hängen Sie sie an den Parameter selectionArgs an oder stellen Sie sie ihm voran, da dieser Wert in Anführungszeichen eingeschlossen und anstelle des Fragezeichens eingefügt wird.

Ein weiteres Attribut im vorherigen Beispiel ist android:searchSuggestIntentAction. Es definiert die Intent-Aktion, die mit jedem Intent gesendet wird, wenn der Nutzer einen Vorschlag auswählt. Dies wird im Abschnitt Absicht für Vorschläge deklarieren näher erläutert.

Tipp:Wenn Sie keine Auswahlklausel im Attribut android:searchSuggestSelection definieren, aber trotzdem den Abfragetext im Parameter selectionArgs erhalten möchten, geben Sie einen Wert ungleich null für das Attribut android:searchSuggestSelection an. Dadurch wird die Abfrage mit selectionArgs übergeben und Sie können den Parameter selection ignorieren. So können Sie die eigentliche Auswahlklausel stattdessen auf einer niedrigeren Ebene definieren, sodass Ihr Contentanbieter sie nicht verarbeiten muss.

Vorschlagstabelle erstellen

Wenn Sie dem System Vorschläge mit einem Cursor 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 benötigten Spalten gespeichert sind, können Sie Ihre Vorschlagsdaten bei jeder Anfrage nach Übereinstimmungen durchsuchen und dann in die erforderliche Tabelle formatieren. Erstellen Sie dazu ein MatrixCursor mit den erforderlichen Spaltennamen und fügen Sie dann mit addRow(Object[]) für jeden Vorschlag eine Zeile hinzu. Geben Sie das Endprodukt über die query()-Methode Ihres Content-Anbieters zurück.

Das System kann mehrere Spalten verarbeiten, aber nur zwei sind erforderlich:

_ID: Eine eindeutige ID für jede Empfehlung. Das System benötigt diese Informationen, um Vorschläge in einem ListView zu präsentieren.
SUGGEST_COLUMN_TEXT_1: Der String, der als Vorschlag präsentiert 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 Ihr Cursor diese Spalte enthält, werden alle Vorschläge in einem zweizeiligen Format angezeigt. 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ärer Text vorhanden ist.
SUGGEST_COLUMN_ICON_1: Ein String für eine Drawable-Ressource, einen Inhalt oder einen Datei-URI. Wenn Ihr Cursor diese Spalte enthält, werden alle Vorschläge im Format „Symbol + Text“ mit dem zeichnungsfähigen Symbol auf der linken Seite angezeigt. Dieser Wert kann „null“ oder „0“ sein, um anzugeben, dass in dieser Zeile kein Symbol vorhanden ist.
SUGGEST_COLUMN_ICON_2: Ein String für eine Drawable-Ressource, einen Inhalt oder einen Datei-URI. Wenn Ihr Cursor diese Spalte enthält, werden alle Vorschläge im Format „Symbol + Text“ mit dem Symbol auf der rechten Seite angezeigt. Kann „null“ oder „0“ sein, um anzugeben, dass in dieser Zeile kein Symbol vorhanden ist.
SUGGEST_COLUMN_INTENT_ACTION: Ein Intent-Aktionsstring. Wenn diese Spalte vorhanden ist und in der angegebenen Zeile einen Wert enthält, wird die hier definierte Aktion verwendet, um die Intention des Vorschlags zu formulieren. Wenn das Element nicht angegeben ist, wird die Aktion aus dem Feld android:searchSuggestIntentAction in Ihrer durchsuchbaren Konfiguration übernommen. Wenn die Aktion für alle Vorschläge dieselbe ist, ist es effizienter, die Aktion mit android:searchSuggestIntentAction anzugeben und diese Spalte wegzulassen.
SUGGEST_COLUMN_INTENT_DATA: Ein Daten-URI-String. Wenn diese Spalte vorhanden ist und in der angegebenen Zeile einen Wert enthält, werden diese Daten verwendet, um die Intention des Vorschlags zu ermitteln. Wenn das Element nicht angegeben ist, werden die Daten aus dem Feld android:searchSuggestIntentData in Ihrer durchsuchbaren Konfiguration übernommen. Wenn keine der beiden Quellen angegeben ist, ist das Datenfeld des Intents null. Wenn Ihre 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 in der angegebenen Zeile einen Wert enthält, werden „/“ und dieser Wert an das Datenfeld im Intent angehängt. Verwenden Sie 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 in einer bestimmten Zeile einen Wert enthält, sind dies die zusätzlichen Daten, die beim Erstellen der Absicht des Vorschlags verwendet werden. Wenn nicht angegeben, ist das zusätzliche Datenfeld des Intents null. Über diese Spalte können Vorschläge zusätzliche Daten bereitstellen, die als Extra im EXTRA_DATA_KEY-Schlüssel des Intents enthalten sind.
SUGGEST_COLUMN_QUERY: Wenn diese Spalte und dieses Element in der angegebenen Zeile vorhanden sind, werden diese Daten verwendet, um die Abfrage des Vorschlags zu erstellen. Sie werden als Extra im QUERY-Schlüssel des Intents eingefügt. Erforderlich, wenn die Aktion des Vorschlags ACTION_SEARCH ist, ansonsten optional.
SUGGEST_COLUMN_SHORTCUT_ID: Wird nur verwendet, wenn Vorschläge für das Schnellstartfeld bereitgestellt werden. In dieser Spalte wird angegeben, ob ein Suchvorschlag als Verknüpfung gespeichert und validiert werden muss. Verknüpfungen werden in der Regel erstellt, wenn der Nutzer auf einen Vorschlag im Schnellsuche-Feld tippt. Falls nicht vorhanden, wird das Ergebnis als Verknüpfung gespeichert und nie aktualisiert. Wenn der Wert auf SUGGEST_NEVER_MAKE_SHORTCUT festgelegt ist, wird das Ergebnis nicht als Verknüpfung gespeichert. Andernfalls wird die Shortcut-ID verwendet, um mit SUGGEST_URI_PATH_SHORTCUT eine aktuelle Empfehlung abzurufen.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Wird nur verwendet, wenn Vorschläge für das Schnellstartfeld bereitgestellt werden. In dieser Spalte wird angegeben, dass anstelle eines Symbols aus SUGGEST_COLUMN_ICON_2 ein Spinner angezeigt werden muss, während die Verknüpfung dieses Vorschlags im Schnellzugriffsfeld 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 einen benutzerdefinierten Intent an Ihre durchsuchbare Aktivität. Sie müssen die Aktion und die Daten für die Intention definieren.

Intent-Aktion deklarieren

Die häufigste Intent-Aktion für einen benutzerdefinierten Vorschlag ist ACTION_VIEW. Sie ist geeignet, wenn Sie etwas öffnen möchten, z. B. die Definition eines Wortes, die Kontaktdaten einer Person oder eine Webseite. Die Intent-Aktion kann jedoch eine beliebige andere Aktion sein und sich für jeden 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:

Verwenden Sie das Attribut android:searchSuggestIntentAction Ihrer 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 Vorschlagstabelle die Spalte SUGGEST_COLUMN_INTENT_ACTION hinzu und geben Sie für jeden Vorschlag die zu verwendende Aktion an, z. B. "android.intent.action.VIEW".

Sie können diese beiden Techniken auch kombinieren. Sie können beispielsweise das Attribut android:searchSuggestIntentAction mit einer Aktion einfügen, die standardmäßig für alle Vorschläge verwendet werden soll. Diese Aktion lässt sich dann für einige Vorschläge überschreiben, indem Sie in der Spalte SUGGEST_COLUMN_INTENT_ACTION eine andere Aktion deklarieren. Wenn Sie in der Spalte SUGGEST_COLUMN_INTENT_ACTION keinen Wert angeben, wird die im Attribut android:searchSuggestIntentAction angegebene Intention verwendet.

Hinweis:Wenn Sie das Attribut android:searchSuggestIntentAction nicht in Ihre durchsuchbare Konfiguration aufnehmen, müssen Sie für jeden Vorschlag einen Wert in die Spalte SUGGEST_COLUMN_INTENT_ACTION aufnehmen, da der Intent sonst fehlschlägt.

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 erkannt werden kann, welcher Vorschlag ausgewählt wurde. Die Daten müssen für jeden Vorschlag eindeutig sein, z. B. die Zeilen-ID für den Vorschlag in Ihrer SQLite-Tabelle. Wenn die Intention empfangen wird, können Sie die angehängten Daten mit getData() oder getDataString() abrufen.

Sie haben zwei Möglichkeiten, die im Intent enthaltenen Daten zu definieren:

Definieren Sie die Daten für jeden Vorschlag in der Spalte SUGGEST_COLUMN_INTENT_DATA Ihrer Vorschlagstabelle.
Geben Sie alle erforderlichen Dateninformationen für jede Intention in der Tabelle mit Vorschlägen an. Fügen Sie dazu die Spalte SUGGEST_COLUMN_INTENT_DATA ein und füllen Sie sie mit eindeutigen Daten für jede Zeile. Die Daten aus dieser Spalte werden dem Intent genau so zugeordnet, wie Sie ihn in dieser Spalte definieren. Anschließend können Sie sie 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 geht das, indem Sie den Spaltennamen SUGGEST_COLUMN_INTENT_DATA als Alias für die Spalte mit der Zeilen-ID verwenden.
Fragmentieren Sie einen Daten-URI in zwei Teile: den Teil, der für alle Vorschläge gleich ist, und den Teil, der für jeden Vorschlag eindeutig ist. Fügen Sie diese Teile in das Attribut android:searchSuggestintentData der durchsuchbaren Konfiguration bzw. in die Spalte SUGGEST_COLUMN_INTENT_DATA_ID Ihrer Vorschlagstabelle ein.
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 Ihrer Vorschlagstabelle ein. Wenn der Nutzer einen Vorschlag auswählt, übernimmt das System den String aus android:searchSuggestIntentData, fügt 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. Sie können dann die Uri mit getData() abrufen.

Weitere Daten hinzufügen

Wenn Sie mehr Informationen mit Ihrem Intent ausdrücken möchten, können Sie eine weitere Tabellenspalte hinzufügen, z. B. SUGGEST_COLUMN_INTENT_EXTRA_DATA, in der zusätzliche Informationen zum Vorschlag gespeichert werden können. Die in dieser Spalte gespeicherten Daten werden in EXTRA_DATA_KEY des Extra-Bundles der Intention eingefügt.

Absicht verarbeiten

Nachdem Sie benutzerdefinierte Suchvorschläge mit benutzerdefinierten Intents bereitgestellt haben, muss Ihre durchsuchbare Aktivität diese Intents verarbeiten, wenn der Nutzer einen Vorschlag auswählt. Das ist zusätzlich zur Verarbeitung der ACTION_SEARCHAbsicht, die bereits durch Ihre durchsuchbare Aktivität erfolgt. Hier sehen Sie ein Beispiel dafür, 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. Dieser URI wird aus dem String android:searchSuggestIntentData und der Spalte SUGGEST_COLUMN_INTENT_DATA_ID synthetisiert. Der URI wird dann an die lokale showResult()-Methode übergeben, die den Contentanbieter nach dem durch den URI angegebenen Element abfragt.

Hinweis:Sie müssen Ihrer Android-Manifestdatei keinen Intent-Filter für die Intent-Aktion hinzufügen, die Sie mit dem Attribut android:searchSuggestIntentAction oder der Spalte SUGGEST_COLUMN_INTENT_ACTION definiert haben. Das System öffnet Ihre durchsuchbare Aktivität nach Namen, um den Intent des Vorschlags zu erfüllen. Die Aktivität muss die akzeptierte Aktion also nicht deklarieren.

Abfragetext neu schreiben

Wenn der Nutzer standardmäßig mit Richtungstasten, z. B. einem Trackball oder Steuerkreuz, durch die Vorschlagsliste navigiert, wird der Abfragetext nicht aktualisiert. Sie können den Suchanfragetext des Nutzers jedoch vorübergehend so umschreiben, dass er mit dem Vorschlag im Fokus übereinstimmt. So kann der Nutzer die vorgeschlagene Anfrage sehen und das Suchfeld auswählen, um die Anfrage zu bearbeiten, bevor er sie als Suchanfrage sendet.

Sie haben folgende Möglichkeiten, den Abfragetext umzuschreiben:

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

Suchvorschläge im Schnellsuche-Feld anzeigen

Nachdem Sie Ihre App so konfiguriert haben, dass sie benutzerdefinierte Suchvorschläge bereitstellt, können Sie diese ganz einfach für das global zugängliche Schnellsuchefeld verfügbar machen. Dazu müssen Sie nur Ihre durchsuchbare Konfiguration so ändern, dass sie android:includeInGlobalSearch mit dem Wert "true" enthält.

Zusätzliche Arbeit ist nur dann erforderlich, wenn Ihr Contentanbieter eine Leseberechtigung verlangt. In diesem Fall müssen Sie ein <path-permission>-Element für den Anbieter hinzufügen, um dem Schnellsuchefeld Lesezugriff auf Ihren Inhaltsanbieter zu gewähren, 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 die Inhalte ein. Das <path-permission>-Element ändert die Einschränkung, indem es Lesezugriff auf Inhalte innerhalb des "/search_suggest_query"-Pfadpräfixes gewährt, wenn die "android.permission.GLOBAL_SEARCH"-Berechtigung vorhanden ist. Dadurch wird der Zugriff auf das Schnellsuchefeld gewährt, damit Ihr Contentanbieter nach Vorschlägen suchen kann.

Wenn Ihr Inhaltsanbieter keine Leseberechtigungen erzwingt, wird der Inhalt standardmäßig von der Schnellsuche gelesen.

Vorschläge auf einem Gerät aktivieren

Standardmäßig sind Apps nicht für die Bereitstellung von Vorschlägen im Schnellsuchefeld aktiviert, auch wenn sie entsprechend konfiguriert sind. Der Nutzer entscheidet, ob Vorschläge aus Ihrer App im Schnellsuchefeld angezeigt werden sollen. Dazu öffnet er Suchbare Elemente unter Einstellungen > Suche und aktiviert Ihre App als suchbares Element.

Jede App, die für das Schnellzugriffsfeld verfügbar ist, hat einen Eintrag auf der Einstellungsseite Durchsuchbare Elemente. Der Eintrag enthält den Namen der App und eine kurze Beschreibung der Inhalte, die über die App durchsucht werden können und für Vorschläge im Schnellzugriffsfeld verfügbar sind. Wenn Sie den Beschreibungstext für Ihre durchsuchbare App definieren möchten, fügen Sie das Attribut android:searchSettingsDescription zu Ihrer durchsuchbaren Konfiguration 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>

Formulieren Sie den String für android:searchSettingsDescription so kurz wie möglich und geben Sie an, welche Inhalte durchsucht werden können. Beispiele: „Künstler, Alben und Titel“ für eine Musik-App oder „Gespeicherte Notizen“ für eine Notizblock-App. Diese Beschreibung ist wichtig, damit der Nutzer weiß, welche Art von Vorschlägen angezeigt werden. Dieses Attribut muss immer angegeben werden, wenn android:includeInGlobalSearch „wahr“ ist.

Da Nutzer das Einstellungsmenü aufrufen müssen, um Suchvorschläge für Ihre App zu aktivieren, sollten Sie sich überlegen, wie Sie ihnen mitteilen, dass die Suche ein wichtiger Aspekt Ihrer App ist. Sie können beispielsweise beim ersten Starten der App durch einen Nutzer eine Notiz einblenden, in der erklärt wird, wie Suchvorschläge für das Schnellsuchefeld aktiviert werden.

Tastenkombinationen für Vorschläge im Schnellsuchefeld verwalten

Vorschläge, die der Nutzer im Schnellsuche-Feld auswählt, können automatisch in Verknüpfungen umgewandelt werden. Das sind Vorschläge, die das System von Ihrem Content-Anbieter kopiert, damit es schnell darauf zugreifen kann, ohne den Content-Anbieter noch einmal abfragen zu müssen.

Standardmäßig ist diese Funktion für alle Vorschläge aktiviert, die über das Schnellsuchefeld abgerufen werden. Wenn sich Ihre Vorschlagsdaten im Laufe der Zeit ändern, können Sie jedoch anfordern, dass die Verknüpfungen aktualisiert werden. Wenn sich Ihre Vorschläge beispielsweise auf dynamische Daten wie den Anwesenheitsstatus eines Kontakts beziehen, fordern Sie an, dass die Vorschlagsverknüpfungen aktualisiert werden, wenn sie dem Nutzer angezeigt werden. Fügen Sie dazu die SUGGEST_COLUMN_SHORTCUT_ID in Ihre Vorschlagstabelle ein. Mit dieser Spalte können Sie das Verhalten der Tastenkombination für jeden Vorschlag auf eine der folgenden Arten konfigurieren:

Das Feld für die Schnellsuche soll den Contentanbieter noch einmal nach einer aktuellen Version der Vorschlagsverknüpfung abfragen.

Geben Sie in der Spalte SUGGEST_COLUMN_SHORTCUT_ID einen Wert an, damit die Empfehlung bei jeder Anzeige der Verknüpfung noch einmal nach einer aktuellen Version abgefragt wird. Die Verknüpfung wird schnell mit den zuletzt verfügbaren Daten angezeigt, bis die Aktualisierungsanfrage zurückgegeben wird. Dann wird der Vorschlag mit den neuen Informationen aktualisiert. Die Aktualisierungsanfrage wird mit dem URI-Pfad SUGGEST_URI_PATH_SHORTCUT an Ihren Inhaltsanbieter gesendet, nicht mit SUGGEST_URI_PATH_QUERY.

Der von Ihnen zurückgegebene Cursor muss einen Vorschlag mit denselben Spalten wie der ursprüngliche Vorschlag enthalten oder leer sein. Im letzteren Fall ist die Tastenkombination nicht mehr gültig. Der Vorschlag wird dann entfernt und die Tastenkombination gelöscht.

Wenn sich ein Vorschlag auf Daten bezieht, deren Aktualisierung länger dauern kann, z. B. bei einer netzwerkbasierten Aktualisierung, können Sie der Vorschlagstabelle auch die Spalte SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING mit dem Wert „true“ hinzufügen. Dann wird für das Symbol auf der rechten Seite ein Fortschritts-Spinner angezeigt, bis die Aktualisierung abgeschlossen ist. Bei jedem anderen Wert als „true“ wird der Fortschritts-Spinner nicht angezeigt.
Verhindern, dass der Vorschlag überhaupt in einen Shortcut 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 einen Shortcut kopiert. Das ist nur erforderlich, wenn Sie auf keinen Fall möchten, dass der zuvor kopierte Vorschlag angezeigt wird. Wenn Sie einen normalen Wert für die Spalte angeben, wird die Vorschlagsverknüpfung nur angezeigt, bis die Aktualisierungsabfrage zurückgegeben wird.
Das Standardverhalten der Tastenkombination soll angewendet werden.

Lassen Sie SUGGEST_COLUMN_SHORTCUT_ID für jeden Vorschlag leer, der sich nicht ändert und als Tastenkombination gespeichert werden kann.

Wenn sich Ihre Vorschläge nie ändern, benötigen Sie die Spalte SUGGEST_COLUMN_SHORTCUT_ID nicht.

Ranking von Vorschlägen im Schnellsuche-Feld

Sobald Sie die Suchvorschläge Ihrer App für das Schnellsuchefeld verfügbar machen, wird durch das Ranking des Schnellsuchefelds bestimmt, wie die Vorschläge dem Nutzer für eine bestimmte Anfrage präsentiert werden. Das hängt davon ab, wie viele andere Apps Ergebnisse für diese Anfrage haben und wie oft der Nutzer Ihre Ergebnisse im Vergleich zu denen anderer Apps auswählt. Es gibt keine Garantie dafür, wie Ihre Vorschläge eingestuft werden oder ob die Vorschläge Ihrer App bei einer bestimmten Anfrage überhaupt angezeigt werden. Im Allgemeinen erhöht die Bereitstellung hochwertiger Ergebnisse die Wahrscheinlichkeit, dass die Vorschläge Ihrer App an einer gut sichtbaren Position angezeigt werden. Apps, die minderwertige Vorschläge liefern, werden eher niedriger eingestuft oder gar nicht angezeigt.

Benutzerdefinierte Suchvorschläge hinzufügen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Grundlagen

Suchkonfiguration ändern

Contentanbieter erstellen

Vorschlagsanfrage verarbeiten

Abfrage im URI abrufen

Kotlin

Java

Abfrage in den Auswahlargumenten abrufen

Vorschlagstabelle erstellen

Intent für Vorschläge deklarieren

Intent-Aktion deklarieren

Intent-Daten deklarieren

Weitere Daten hinzufügen

Absicht verarbeiten

Kotlin

Java

Abfragetext neu schreiben

Suchvorschläge im Schnellsuche-Feld anzeigen

Vorschläge auf einem Gerät aktivieren

Tastenkombinationen für Vorschläge im Schnellsuchefeld verwalten

Ranking von Vorschlägen im Schnellsuche-Feld

Benutzerdefinierte Suchvorschläge hinzufügen