Rechercher une configuration

Pour implémenter la recherche à l'aide du système Android, c'est-à-dire pour envoyer des requêtes de recherche à une activité et fournir des suggestions de recherche, votre application doit fournir une configuration de recherche sous la forme d'un fichier XML.

Cette page décrit le fichier de configuration de recherche en termes de syntaxe et d'utilisation. Pour en savoir plus sur la mise en œuvre des fonctionnalités de recherche pour votre application, consultez la page Créer une interface de recherche.

Emplacement du fichier :
res/xml/filename.xml
Android utilise le nom de fichier comme ID de ressource.
Syntaxe :
<?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>
Éléments :
<searchable>
Définit toutes les configurations de recherche utilisées par le système Android pour fournir une recherche assistée.

Attributs:

android:label
Ressource de chaîne. (Obligatoire) Nom de votre application. Il doit être identique au nom appliqué à l'attribut android:label de l'élément de votre fichier manifeste <activity> ou <application>. Ce libellé n'est visible que par l'utilisateur lorsque vous définissez android:includeInGlobalSearch sur "true". Dans ce cas, il permet d'identifier votre application en tant qu'élément inclus dans l'index de recherche dans les paramètres de recherche du système.
android:hint
Ressource de chaîne. (Recommandé) Texte à afficher dans le champ de recherche lorsqu'aucun texte n'est saisi. Elle indique à l'utilisateur quel contenu peut faire l'objet d'une recherche. Pour assurer la cohérence avec les autres applications Android, mettez en forme la chaîne android:hint sous la forme "Rechercher <content-or-product>". Par exemple, "Rechercher des chansons et des artistes" ou "Rechercher sur YouTube".
android:searchMode
Mot clé. Définit des modes supplémentaires qui contrôlent la présentation de la recherche. Les modes disponibles définissent la manière dont le texte de la requête doit être réécrit lorsqu'une suggestion personnalisée est sélectionnée. Les valeurs de mode suivantes sont acceptées:
ValeurDescription
"queryRewriteFromData" Utilisez la valeur de la colonne SUGGEST_COLUMN_INTENT_DATA pour réécrire le texte de la requête. Cette méthode ne doit être utilisée que lorsque les valeurs de SUGGEST_COLUMN_INTENT_DATA conviennent à l'inspection et à la modification par les utilisateurs, comme les URI HTTP.
"queryRewriteFromText" Utilisez la valeur de la colonne SUGGEST_COLUMN_TEXT_1 pour réécrire le texte de la requête.

Pour en savoir plus, consultez la section Ajouter des suggestions de recherche personnalisées pour savoir comment réécrire le texte de la requête.

android:searchButtonText
Ressource de chaîne. Texte à afficher sur le bouton qui exécute la recherche. Par défaut, le bouton affiche une icône de recherche (une loupe), ce qui est idéal pour l'internationalisation. N'utilisez donc pas cet attribut pour modifier le bouton, sauf si le comportement est différent d'une recherche, par exemple une requête d'URL dans un navigateur Web.
android:inputType
Mot clé. Définit le type de mode de saisie à utiliser, par exemple le type de clavier virtuel. Vous n'avez pas besoin de cet attribut pour la plupart des recherches nécessitant du texte libre. Consultez inputType pour obtenir la liste des valeurs appropriées pour cet attribut.
android:imeOptions
Mot clé. Fournit des options supplémentaires pour la méthode d'importation. Pour la plupart des recherches dans lesquelles le texte au format libre est attendu, vous n'avez pas besoin de cet attribut. L'IME par défaut est actionSearch, qui fournit le bouton de recherche au lieu d'un retour chariot dans le clavier virtuel. Consultez imeOptions pour obtenir la liste des valeurs appropriées pour cet attribut.

Attributs de suggestion de recherche

Si vous définissez un fournisseur de contenu pour générer des suggestions de recherche, vous devez définir des attributs supplémentaires qui configurent les communications avec le fournisseur de contenu. Lorsque vous fournissez des suggestions de recherche, vous avez besoin de certains des attributs <searchable> suivants:


android:searchSuggestAuthority
Chaîne. (Obligatoire pour fournir des suggestions de recherche.) Cette valeur doit correspondre à la chaîne d'autorité fournie dans l'attribut android:authorities de l'élément <provider> du fichier manifeste Android.
android:searchSuggestPath
Chaîne. Ce chemin d'accès est utilisé dans le cadre de la requête de suggestions Uri, après le préfixe et l'autorité, et avant le chemin d'accès aux suggestions standard. Cela n'est nécessaire que si un seul fournisseur de contenu émet différents types de suggestions (par exemple, pour différents types de données) et que vous avez besoin d'un moyen de faire la distinction entre les requêtes de suggestions lorsque vous les recevez.
android:searchSuggestSelection
Chaîne. Cette valeur est transmise à votre fonction de requête en tant que paramètre selection. Il s'agit généralement d'une clause WHERE pour votre base de données. Elle doit contenir un seul point d'interrogation comme espace réservé pour la chaîne de requête réelle saisie par l'utilisateur (par exemple, "query=?"). Toutefois, vous pouvez également utiliser n'importe quelle valeur non nulle pour déclencher la diffusion du texte de la requête à l'aide du paramètre selectionArgs, puis ignorer le paramètre selection.
android:searchSuggestIntentAction
Chaîne. Action d'intent par défaut à utiliser lorsqu'un utilisateur appuie sur une suggestion de recherche personnalisée, telle que "android.intent.action.VIEW". Si cette valeur n'est pas remplacée par la suggestion sélectionnée à l'aide de la colonne SUGGEST_COLUMN_INTENT_ACTION, elle est placée dans le champ d'action de Intent lorsque l'utilisateur appuie sur une suggestion.
android:searchSuggestIntentData
Chaîne. Données d'intent par défaut à utiliser lorsqu'un utilisateur appuie sur une suggestion de recherche personnalisée. Si elle n'est pas remplacée par la suggestion sélectionnée (via la colonne SUGGEST_COLUMN_INTENT_DATA), cette valeur est placée dans le champ de données de Intent lorsque l'utilisateur appuie sur une suggestion.
android:searchSuggestThreshold
Nombre entier. Nombre minimal de caractères requis pour déclencher une recherche de suggestions. Cela garantit seulement que le système n'interroge pas votre fournisseur de contenu pour rechercher des éléments inférieurs au seuil. La valeur par défaut est 0.

Pour en savoir plus sur les attributs ci-dessus pour les suggestions de recherche, consultez la documentation sur l'ajout de suggestions de recherche personnalisées et l'ajout de suggestions personnalisées.

Attributs du champ de recherche rapide

Pour que vos suggestions de recherche personnalisées soient disponibles dans le champ de recherche rapide, vous devez disposer de certains des attributs <searchable> suivants:


android:includeInGlobalSearch
Booléen. (Obligatoire pour fournir des suggestions de recherche dans le champ de recherche rapide.) Définissez la valeur sur "true" si vous souhaitez que vos suggestions soient incluses dans le champ de recherche rapide, accessible dans le monde entier. L'utilisateur doit tout de même activer votre application en tant qu'élément inclus dans l'index de recherche dans les paramètres de recherche du système pour que vos suggestions s'affichent dans le champ de recherche rapide.
android:searchSettingsDescription
Ressource de chaîne. Fournit une brève description des suggestions de recherche que vous fournissez au champ de recherche rapide. Elles s'affichent dans l'entrée interrogeable de votre application. Votre description doit décrire de manière concise le contenu dans lequel il est possible d'effectuer des recherches. Par exemple, "Artistes, albums et pistes" pour une application musicale ou "Notes enregistrées" pour une application de bloc-notes.
android:queryAfterZeroResults
Booléen. Définissez la valeur sur "true" si vous souhaitez que votre fournisseur de contenu soit appelé pour les sur-ensembles de requêtes qui n'ont précédemment renvoyé aucun résultat. Par exemple, si votre fournisseur de contenu ne renvoie aucun résultat pour "bo", il doit faire l'objet d'une nouvelle requête pour "bob". Si la valeur est "false", les sur-ensembles sont ignorés pour une seule session. "bob" n'appelle pas de nouvelle requête. Ce paramètre n'est actif que pendant la durée de vie de la boîte de dialogue de recherche ou de l'activité lorsque vous utilisez le widget Recherche. Lorsque la boîte de dialogue ou l'activité de recherche sont rouvertes, "bo" interroge à nouveau votre fournisseur de contenu. La valeur par défaut est "false".

Attributs de la recherche vocale

Pour activer la recherche vocale, vous devez disposer de certains des attributs <searchable> suivants:


android:voiceSearchMode
Mot clé. (Obligatoire pour fournir des fonctionnalités de recherche vocale.) Active la recherche vocale, avec un mode spécifique pour la recherche vocale. La recherche vocale peut ne pas être fournie par l'appareil, auquel cas ces indicateurs n'ont aucun effet. Les valeurs de mode suivantes sont acceptées:
ValeurDescription
"showVoiceSearchButton" Afficher un bouton de recherche vocale, si celle-ci est disponible sur l'appareil. S'il est défini, "launchWebSearch" ou "launchRecognizer" doit également être défini, en les séparant par une barre verticale (|).
"launchWebSearch" Le bouton de recherche vocale redirige directement l'utilisateur vers une activité de recherche vocale intégrée sur le Web. La plupart des applications n'utilisent pas cet indicateur, car il éloigne l'utilisateur de l'activité pour laquelle la recherche a été appelée.
"launchRecognizer" Le bouton de recherche vocale redirige directement l'utilisateur vers une activité d'enregistrement vocal intégrée. Cette activité invite l'utilisateur à parler, transcrit le texte énoncé et transmet le texte de requête résultant à l'activité interrogeable, comme s'il l'avait saisi dans l'interface de recherche et appuyait sur le bouton de recherche.
android:voiceLanguageModel
Mot clé. Modèle de langage que le système de reconnaissance vocale doit utiliser. Les valeurs suivantes sont acceptées:
ValeurDescription
"free_form" Utilisez la reconnaissance vocale de format libre pour dicter des requêtes. Cette fonctionnalité est principalement optimisée pour l'anglais. Il s'agit de l'option par défaut.
"web_search" Utilisez la reconnaissance des termes de recherche sur le Web pour des expressions de recherche plus courtes. Cette fonctionnalité est disponible dans plus de langues que "free_form".

Pour en savoir plus, consultez EXTRA_LANGUAGE_MODEL.

android:voicePromptText
Ressource de chaîne. Message supplémentaire à afficher dans la boîte de dialogue de saisie vocale.
android:voiceLanguage
Chaîne. Langue parlée à attendre, exprimée sous la forme de la valeur de chaîne d'une constante dans Locale, telle que "de" pour l'allemand ou "fr" pour le français. Cela n'est nécessaire que si elle est différente de la valeur actuelle de Locale.getDefault().
android:voiceMaxResults
Nombre entier. Définit le nombre maximal de résultats à renvoyer, y compris le "meilleur" résultat, qui est toujours fourni en tant que requête principale de l'intent ACTION_SEARCH. Doit être supérieur ou égal à 1. Utilisez EXTRA_RESULTS pour obtenir les résultats de l'intent. S'il n'est pas fourni, l'outil de reconnaissance choisit le nombre de résultats à renvoyer.
<actionkey>
Définit une clé d'appareil et un comportement pour une action de recherche. Une action de recherche fournit un comportement spécial lorsque l'utilisateur appuie sur un bouton de l'appareil, en fonction de la requête actuelle ou de la suggestion sélectionnée. Par exemple, l'application Contacts fournit une action de recherche pour lancer un appel téléphonique vers la suggestion de contact sélectionnée lorsque l'utilisateur appuie sur le bouton APPEL.

Les clés d'action ne sont pas toutes disponibles sur tous les appareils, et il n'est pas possible de toutes les remplacer de cette manière. Par exemple, la touche "Accueil" ne peut pas être remplacée et doit toujours revenir à l'écran d'accueil. Veillez également à ne pas définir de touche d'action pour une touche nécessaire à la saisie d'une requête de recherche. Cela limite les touches d'action disponibles et raisonnables au bouton d'appel et au bouton de menu.

Vous devez définir la clé (android:keycode) et au moins l'un des trois autres attributs pour définir l'action de recherche.

Attributs:

android:keycode
Chaîne. (Obligatoire) Un code de touche de KeyEvent qui représente la touche d'action à laquelle vous souhaitez répondre (par exemple, "KEYCODE_CALL"). Cet élément est ajouté à l'intent ACTION_SEARCH transmis à votre activité interrogeable. Pour examiner le code de touche, utilisez getIntExtra(SearchManager.ACTION_KEY). Toutes les touches ne sont pas compatibles avec une action de recherche, car beaucoup d'entre elles sont utilisées pour la saisie, la navigation ou les fonctions système.
android:queryActionMsg
Chaîne. Message d'action à envoyer si l'utilisateur appuie sur la touche d'action pendant que l'utilisateur saisit le texte de la requête. Il est ajouté à l'intent ACTION_SEARCH que le système transmet à votre activité interrogeable. Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG).
android:suggestActionMsg
Chaîne. Message d'action à envoyer si l'utilisateur appuie sur la touche d'action alors qu'une suggestion est active. Cet élément est ajouté à l'intent que le système transmet à votre activité interrogeable (à l'aide de l'action que vous définissez pour la suggestion). Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG). Vous ne devez l'utiliser que si toutes vos suggestions sont compatibles avec cette touche d'action. Si toutes les suggestions ne peuvent pas gérer la même clé d'action, vous devez utiliser l'attribut android:suggestActionMsgColumn suivant à la place.
android:suggestActionMsgColumn
Chaîne. Nom de la colonne de votre fournisseur de contenu qui définit le message d'action pour cette touche d'action, à envoyer si l'utilisateur appuie sur la touche d'action lorsqu'une suggestion est active. Cet attribut vous permet de contrôler la clé d'action suggestion par suggestion. En effet, au lieu d'utiliser l'attribut android:suggestActionMsg pour définir le message d'action pour toutes les suggestions, chaque entrée de votre fournisseur de contenu fournit son propre message d'action.

Tout d'abord, vous devez définir une colonne dans votre fournisseur de contenu pour chaque suggestion afin de fournir un message d'action, puis indiquer le nom de cette colonne dans cet attribut. Le système examine le curseur de vos suggestions à l'aide de la chaîne fournie ici pour sélectionner la colonne du message d'action, puis sélectionne la chaîne du message d'action à partir du curseur. Cette chaîne est ajoutée à l'intent que le système transmet à votre activité interrogeable, à l'aide de l'action que vous définissez pour les suggestions. Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG). Si les données n'existent pas pour la suggestion sélectionnée, la clé d'action est ignorée.

Exemple :
Fichier XML enregistré sous 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>