Konfiguration der Suche

Um die Suche mithilfe des Android-Systems zu implementieren, also um Suchanfragen an eine Aktivität zu senden und Suchvorschläge bereitzustellen, muss Ihre Anwendung eine Suchkonfiguration in Form einer XML-Datei bereitstellen.

Auf dieser Seite wird die Konfigurationsdatei für die Suche in Bezug auf Syntax und Verwendung beschrieben. Weitere Informationen zum Implementieren von Suchfunktionen für Ihre Anwendung finden Sie unter Suchoberfläche erstellen.

Dateispeicherort:

res/xml/filename.xml
Android verwendet den Dateinamen als Ressourcen-ID.

Syntax:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

Elemente:

<searchable>

Definiert alle Suchkonfigurationen, die vom Android-System für die unterstützte Suche verwendet werden.

Attribute:

android:label

Stringressource. (Erforderlich.) Der Name Ihrer Anwendung. Er muss mit dem Namen übereinstimmen, der auf das Attribut android:label des <activity>- oder <application>-Manifestelements angewendet wird. Dieses Label ist nur für den Nutzer sichtbar, wenn Sie android:includeInGlobalSearch auf "true" festlegen. In diesem Fall wird es verwendet, um Ihre Anwendung in den Sucheinstellungen des Systems als suchbares Element zu kennzeichnen.

android:hint

Stringressource. (Empfohlen.) Der Text, der im Suchtextfeld angezeigt wird, wenn kein Text eingegeben wird. Sie geben dem Nutzer einen Hinweis darauf, nach welchem Content gesucht werden kann. Aus Gründen der Einheitlichkeit mit anderen Android-Apps formatieren Sie den String für android:hint als „Suche <content-or-product>“. Beispiel: „Nach Songs und Künstlern suchen“ oder „Auf YouTube suchen“.

android:searchMode

Keyword. Legt zusätzliche Modi fest, die die Darstellung der Suche steuern. In den verfügbaren Modi wird festgelegt, wie der Abfragetext neu geschrieben werden muss, wenn ein benutzerdefinierter Vorschlag hervorgehoben wird. Die folgenden Moduswerte werden akzeptiert:

Antwort	Beschreibung
"queryRewriteFromData"	Verwenden Sie den Wert aus der Spalte SUGGEST_COLUMN_INTENT_DATA, um den Abfragetext neu zu schreiben. Dieser Parameter sollte nur verwendet werden, wenn die Werte in SUGGEST_COLUMN_INTENT_DATA zum Prüfen und Bearbeiten durch Nutzer geeignet sind, z. B. HTTP-URIs.
"queryRewriteFromText"	Verwenden Sie den Wert aus der Spalte SUGGEST_COLUMN_TEXT_1, um den Abfragetext neu zu schreiben.

Weitere Informationen finden Sie in der Dokumentation zum Umschreiben des Abfragetexts unter Benutzerdefinierte Suchvorschläge hinzufügen.

android:searchButtonText

Stringressource. Der Text, der auf der Schaltfläche angezeigt werden soll, mit der die Suche ausgeführt wird. Standardmäßig wird auf der Schaltfläche ein Suchsymbol (Lupe) angezeigt, was sich ideal für die Internationalisierung eignet. Verwende dieses Attribut also nur, um die Schaltfläche zu ändern, es sei denn, es handelt sich um eine Suche, z. B. eine URL-Anfrage in einem Webbrowser.

android:inputType

Keyword. Definiert den Typ der zu verwendenden Eingabemethode, z. B. die Art der Softtastatur. Für die meisten Suchanfragen, bei denen Freitext erwartet wird, ist dieses Attribut nicht erforderlich. Unter inputType finden Sie eine Liste geeigneter Werte für dieses Attribut.

android:imeOptions

Keyword. Stellt zusätzliche Optionen für die Eingabemethode bereit. Bei den meisten Suchanfragen, bei denen Freitext erwartet wird, ist dieses Attribut nicht erforderlich. Der Standard-IME ist actionSearch. Dieser bietet die Schaltfläche „Suchen“ anstelle eines Zeilenumbruchs auf der Softwaretastatur. Eine Liste geeigneter Werte für dieses Attribut finden Sie unter imeOptions.

Attribute für Suchvorschläge

Wenn Sie einen Contentanbieter zum Generieren von Suchvorschlägen definieren, müssen Sie zusätzliche Attribute definieren, die die Kommunikation mit dem Contentanbieter konfigurieren. Für Suchvorschläge benötigen Sie einige der folgenden <searchable>-Attribute:

android:searchSuggestAuthority

String (Erforderlich, um Suchvorschläge bereitzustellen.) Dieser Wert muss mit dem Autorisierungsstring übereinstimmen, der im Attribut android:authorities des <provider>-Elements des Android-Manifests angegeben ist.

android:searchSuggestPath

String Dieser Pfad wird als Teil der Vorschlagsabfrage Uri nach dem Präfix und der Zertifizierungsstelle und vor dem standardmäßigen Vorschlagspfad verwendet. Dies ist nur erforderlich, wenn ein einzelner Contentanbieter verschiedene Arten von Vorschlägen ausgibt, z. B. für unterschiedliche Datentypen, und Sie eine Möglichkeit benötigen, die Vorschlagsabfragen, die Sie erhalten, eindeutig zu unterscheiden.

android:searchSuggestSelection

String Dieser Wert wird als selection-Parameter an die Abfragefunktion übergeben. In der Regel ist dies eine WHERE-Klausel für Ihre Datenbank, die ein einzelnes Fragezeichen als Platzhalter für den vom Nutzer eingegebenen Abfragestring enthalten muss, z. B. "query=?". Sie können jedoch auch einen beliebigen Wert ungleich Null verwenden, um die Auslieferung des Abfragetexts mit dem Parameter selectionArgs auszulösen, und dann den Parameter selection ignorieren.

android:searchSuggestIntentAction

String Die standardmäßige Intent-Aktion, die verwendet wird, wenn ein Nutzer auf einen benutzerdefinierten Suchvorschlag wie "android.intent.action.VIEW" tippt. Wenn dieser Wert nicht durch den ausgewählten Vorschlag in der Spalte SUGGEST_COLUMN_INTENT_ACTION überschrieben wird, wird der Wert im Aktionsfeld von Intent platziert, wenn der Nutzer auf einen Vorschlag tippt.

android:searchSuggestIntentData

String Die standardmäßigen Intent-Daten, die verwendet werden, wenn ein Nutzer auf einen benutzerdefinierten Suchvorschlag tippt. Wenn der Wert nicht durch den ausgewählten Vorschlag überschrieben wird (über die Spalte SUGGEST_COLUMN_INTENT_DATA), wird er im Datenfeld von Intent platziert, wenn der Nutzer auf einen Vorschlag tippt.

android:searchSuggestThreshold

Ganzzahl. Die Mindestanzahl von Zeichen, die erforderlich sind, um eine Vorschlagssuche auszulösen. Dadurch wird nur sichergestellt, dass das System bei Ihrem Contentanbieter keine Anfragen abfragt, die kürzer als der Grenzwert sind. Der Standardwert ist 0.

Weitere Informationen zu den oben genannten Attributen für Suchvorschläge finden Sie in der Dokumentation zum Hinzufügen von benutzerdefinierten Suchvorschlägen und Benutzerdefinierte Suchvorschläge.

Attribute für das Schnellsuchfeld

Damit deine benutzerdefinierten Suchvorschläge im Schnellsuchfeld verfügbar sind, benötigst du einige der folgenden <searchable>-Attribute:

android:includeInGlobalSearch

Boolescher Wert. (Erforderlich zur Bereitstellung von Suchvorschlägen im Schnellsuchfeld.) Legen Sie "true" fest, wenn Ihre Vorschläge in das global zugängliche Schnellsuchfeld aufgenommen werden sollen. Der Nutzer muss Ihre Anwendung jedoch in den Systemsucheinstellungen als durchsuchbares Element aktivieren, damit Ihre Vorschläge im Schnellsuchfeld angezeigt werden.

android:searchSettingsDescription

Stringressource. Bietet eine kurze Beschreibung der Suchvorschläge, die Sie dem Schnellsuchfeld zur Verfügung stellen und die im Eintrag der durchsuchbaren Elemente Ihrer Anwendung angezeigt werden. Ihre Beschreibung muss den Inhalt, der suchbar ist, prägnant beschreiben. Beispiel: „Interpreten, Alben und Titel“ bei einer Musik-App oder „Gespeicherte Notizen“ bei einer Notizblock-App.

android:queryAfterZeroResults

Boolescher Wert. Legen Sie "true" fest, wenn Ihr Contentanbieter für Obermengen von Abfragen aufgerufen werden soll, für die zuvor keine Ergebnisse zurückgegeben wurden. Wenn Ihr Contentanbieter beispielsweise keine Ergebnisse für „bo“ zurückgibt, muss die Abfrage nach „bob“ neu durchgeführt werden. Wenn "false" festgelegt ist, werden Obermengen für eine einzelne Sitzung ignoriert. Mit „bob“ wird keine neue Abfrage ausgelöst. Dies gilt nur für die Lebensdauer des Suchdialogs oder die Lebensdauer der Aktivität bei Verwendung des Such-Widgets. Wenn der Suchdialog oder die Aktivität wieder geöffnet wird, fragt „bo“ noch einmal bei Ihrem Inhaltsanbieter ab. Der Standardwert ist "false".

Attribute für die Sprachsuche

Zum Aktivieren der Sprachsuche benötigen Sie einige der folgenden <searchable>-Attribute:

android:voiceSearchMode

Keyword. (Erforderlich, um Funktionen zur Sprachsuche bereitzustellen.) Aktiviert die Sprachsuche mit einem bestimmten Modus für die Sprachsuche. Möglicherweise wird die Sprachsuche nicht vom Gerät unterstützt. In diesem Fall haben diese Flags keine Auswirkungen. Die folgenden Moduswerte werden akzeptiert:

Antwort	Beschreibung
"showVoiceSearchButton"	Schaltfläche für die Sprachsuche anzeigen, wenn die Sprachsuche auf dem Gerät verfügbar ist Wenn festgelegt, muss entweder "launchWebSearch" oder "launchRecognizer" angegeben werden, getrennt durch ein Pipe-Zeichen (|).
"launchWebSearch"	Über die Schaltfläche für die Sprachsuche gelangen Nutzer direkt zu einer integrierten Sprachsuche im Web. Die meisten Anwendungen verwenden dieses Flag nicht, da es den Nutzer von der Aktivität wegführt, in der die Suche aufgerufen wurde.
"launchRecognizer"	Über die Schaltfläche für die Sprachsuche gelangen Nutzer direkt zu einer integrierten Sprachaufnahme-Aktivität. Bei dieser Aktivität wird der Nutzer zum Sprechen aufgefordert, der gesprochene Text transkribiert und der resultierende Abfragetext an die durchsuchbare Aktivität weitergeleitet, so als ob der Nutzer ihn in die Such-UI eingegeben und auf die Suchschaltfläche getippt hätte.

android:voiceLanguageModel

Keyword. Das Sprachmodell, das vom Spracherkennungssystem verwendet werden muss. Die folgenden Werte sind zulässig:

Antwort	Beschreibung
"free_form"	Verwenden Sie zum Diktieren von Anfragen die Spracherkennung im freien Format. Diese ist hauptsächlich für Englisch optimiert. Das ist die Standardeinstellung.
"web_search"	Verwenden Sie die Erkennung von Suchbegriffen für kürzere, ähnliche Wortgruppen. Diese Funktion ist in mehr Sprachen als "free_form" verfügbar.

Weitere Informationen finden Sie unter EXTRA_LANGUAGE_MODEL.

android:voicePromptText

Stringressource. Eine zusätzliche Nachricht, die im Dialogfeld für die Spracheingabe angezeigt wird.

android:voiceLanguage

String Die zu erwartende gesprochene Sprache, ausgedrückt als Stringwert einer Konstanten in Locale, z. B. "de" für Deutsch oder "fr" für Französisch. Dieser ist nur erforderlich, wenn er vom aktuellen Wert von Locale.getDefault() abweicht.

android:voiceMaxResults

Ganzzahl. Legt die maximale Anzahl der zurückzugebenden Ergebnisse fest, einschließlich des besten Ergebnisses, das immer als primäre Abfrage des ACTION_SEARCH-Intents bereitgestellt wird. Muss 1 oder größer sein. Verwenden Sie EXTRA_RESULTS, um die Ergebnisse des Intents abzurufen. Wenn nicht angegeben, wählt die Erkennung aus, wie viele Ergebnisse zurückgegeben werden sollen.

<actionkey>

Definiert einen Geräteschlüssel und das Verhalten für eine Suchaktion. Eine Suchaktion führt auf Grundlage der aktuellen Suchanfrage oder des fokussierten Vorschlags durch Tippen auf eine Schaltfläche auf dem Gerät ein spezielles Verhalten aus. Die Kontakte-Anwendung bietet beispielsweise eine Suchaktion, mit der der aktuell im Fokus stehende Kontaktvorschlag angerufen werden kann, wenn auf die ANRUF-Schaltfläche getippt wird.

Nicht alle Aktionsschlüssel sind auf jedem Gerät verfügbar und nicht alle Schlüssel können auf diese Weise überschrieben werden. Die Startbildschirmtaste kann beispielsweise nicht überschrieben werden und muss immer zum Startbildschirm zurückkehren. Definieren Sie außerdem keine Aktionsschlüssel für einen Schlüssel, der zum Eingeben einer Suchanfrage erforderlich ist. Dadurch werden die verfügbaren und sinnvollen Aktionstasten auf die Anrufschaltfläche und die Menüschaltfläche beschränkt.

Sie müssen die android:keycode definieren, um den Schlüssel zu definieren, und mindestens eines der anderen drei Attribute, um die Suchaktion zu definieren.

Attribute:

android:keycode

String (Erforderlich.) Ein Schlüsselcode aus KeyEvent, der den Aktionsschlüssel darstellt, auf den Sie reagieren möchten, z. B. "KEYCODE_CALL". Dies wird dem Intent ACTION_SEARCH hinzugefügt, der an Ihre durchsuchbare Aktivität übergeben wird. Verwenden Sie getIntExtra(SearchManager.ACTION_KEY), um den Schlüsselcode zu untersuchen. Für eine Suchaktion werden nicht alle Tasten unterstützt, da viele davon für die Eingabe, Navigation oder Systemfunktionen verwendet werden.

android:queryActionMsg

String Eine Aktionsnachricht, die gesendet wird, wenn die Aktionstaste gedrückt wird, während der Nutzer Abfragetext eingibt. Dies wird dem Intent ACTION_SEARCH hinzugefügt, den das System an Ihre durchsuchbaren Aktivitäten übergibt. Verwenden Sie getStringExtra(SearchManager.ACTION_MSG), um den String zu prüfen.

android:suggestActionMsg

String Eine Aktionsnachricht, die gesendet wird, wenn die Aktionstaste gedrückt wird, während ein Vorschlag im Fokus ist. Diese wird dem Intent hinzugefügt, den das System mithilfe der Aktion, die Sie für den Vorschlag definieren, an Ihre durchsuchbare Aktivität übergibt. Verwenden Sie getStringExtra(SearchManager.ACTION_MSG), um den String zu prüfen. Dieser Aktionsschlüssel darf nur verwendet werden, wenn alle Ihre Vorschläge diese Aktion unterstützen. Wenn nicht alle Vorschläge denselben Aktionsschlüssel verarbeiten können, müssen Sie stattdessen das folgende android:suggestActionMsgColumn-Attribut verwenden.

android:suggestActionMsgColumn

String Der Name der Spalte bei Ihrem Contentanbieter, die die Aktionsnachricht für diese Aktionstaste definiert. Sie wird gesendet, wenn der Nutzer die Aktionstaste drückt, während ein Vorschlag im Fokus ist. Mit diesem Attribut können Sie den Aktionsschlüssel für jeden Vorschlag steuern. Anstatt das Attribut android:suggestActionMsg zum Definieren der Aktionsnachricht für alle Vorschläge zu verwenden, stellt jeder Eintrag bei Ihrem Inhaltsanbieter eine eigene Aktionsnachricht bereit.

Zuerst müssen Sie in Ihrem Contentanbieter für jeden Vorschlag eine Spalte definieren, für die eine Aktionsnachricht bereitgestellt werden soll. Geben Sie dann den Namen der Spalte in diesem Attribut an. Das System prüft den Vorschlags-Cursor und wählt mit dem hier angegebenen String die Spalte für die Aktionsnachricht aus. Anschließend wird der entsprechende String im Cursor ausgewählt. Dieser String wird dem Intent hinzugefügt, den das System an Ihre durchsuchbare Aktivität übergibt, und verwendet die Aktion, die Sie für Vorschläge definieren. Verwenden Sie getStringExtra(SearchManager.ACTION_MSG), um den String zu prüfen. Sind für den ausgewählten Vorschlag keine Daten vorhanden, wird die Aktionstaste ignoriert.

Beispiel:

XML-Datei gespeichert unter res/xml/searchable.xml:

<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>