Configuration de la recherche

Essayer Compose

Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment ajouter une fonctionnalité de recherche dans Compose.

Barre de recherche →

Pour implémenter la recherche avec l'aide du système Android (c'est-à-dire pour fournir 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 la recherche en termes de syntaxe et d'utilisation. Pour savoir comment implémenter des fonctionnalités de recherche pour votre application, consultez 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 fichier manifeste <activity> ou <application>. Ce libellé n'est visible par l'utilisateur que lorsque vous définissez android:includeInGlobalSearch sur "true". Dans ce cas, il est utilisé pour identifier votre application comme élément pouvant être recherché dans les paramètres de recherche du système.

android:hint

Ressource de chaîne. (recommandé). Texte à afficher dans le champ de texte de recherche lorsqu'aucun texte n'est saisi. Il donne à l'utilisateur un indice sur le contenu qui peut être recherché. Pour assurer la cohérence avec les autres applications Android, mettez en forme la chaîne pour android:hint comme suit : "Rechercher <contenu-ou-produit>". Par exemple, "Rechercher des titres 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 :

Valeur	Description
"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 peuvent être inspectées et modifiées par l'utilisateur, 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 documentation sur la réécriture du texte de la requête dans Ajouter des suggestions de recherche personnalisées.

android:searchButtonText

Ressource de chaîne. Texte à afficher dans 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 demande d'URL dans un navigateur Web).

android:inputType

Mot clé. Définit le type de méthode de saisie à utiliser, comme le type de clavier logiciel. Pour la plupart des recherches, dans lesquelles un texte en saisie libre est attendu, vous n'avez pas besoin de cet attribut. 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 de saisie. Pour la plupart des recherches dans lesquelles du texte libre est attendu, vous n'avez pas besoin de cet attribut. L'IME par défaut est actionSearch, qui fournit le bouton "Rechercher" au lieu d'un retour à la ligne dans le clavier logiciel. Consultez imeOptions pour obtenir la liste des valeurs appropriées pour cet attribut.

Attributs des suggestions 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é comme partie de la requête de suggestions Uri, après le préfixe et l'autorité, et avant le chemin d'accès aux suggestions standards. Cette opération n'est requise que si vous avez un seul fournisseur de contenu qui émet différents types de suggestions (par exemple, pour différents types de données) et que vous avez besoin d'un moyen de lever l'ambiguïté des 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, qui 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 l'envoi 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, comme "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'intention 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 nécessaires pour déclencher une recherche de suggestions. Cela garantit uniquement que le système n'interroge pas votre fournisseur de contenu pour une durée inférieure 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 la zone de recherche rapide, vous devez disposer de certains des attributs <searchable> suivants :

android:includeInGlobalSearch

Booléen. (Obligatoire pour fournir des suggestions de recherche dans la zone de recherche rapide.) Définissez la valeur sur "true" si vous souhaitez que vos suggestions soient incluses dans la zone de recherche rapide accessible dans le monde entier. L'utilisateur doit toujours activer votre application en tant qu'élément pouvant être recherché dans les paramètres de recherche du système pour que vos suggestions s'affichent dans la barre de recherche express.

android:searchSettingsDescription

Ressource de chaîne. Fournit une brève description des suggestions de recherche que vous fournissez à la zone de recherche rapide, qui s'affiche dans l'entrée des éléments pouvant faire l'objet d'une recherche pour votre application. Votre description doit décrire de manière concise le contenu qui peut être recherché. Par exemple, "Artistes, albums et titres" 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 supersets de requêtes qui renvoyaient auparavant zéro résultat. Par exemple, si votre fournisseur de contenu renvoie zéro résultat pour "bo", une nouvelle requête doit être envoyée pour "bob". Si la valeur est définie sur "false", les ensembles de données plus larges sont ignorés pour une seule session. "bob" n'appelle pas de nouvelle requête. Cela ne dure que pendant la durée de vie de la boîte de dialogue de recherche ou de l'activité lors de l'utilisation du widget de recherche. Lorsque la boîte de dialogue ou l'activité de recherche est rouverte, "bo" interroge à nouveau votre fournisseur de contenu. La valeur par défaut est "false".

Attributs de recherche vocale

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

android:voiceSearchMode

Mot clé. (Nécessaire pour fournir des fonctionnalités de recherche vocale.) Active la recherche vocale, avec un mode spécifique pour la recherche vocale. Il est possible que la recherche vocale ne soit pas fournie par l'appareil, auquel cas ces indicateurs n'ont aucun effet. Les valeurs de mode suivantes sont acceptées :

Valeur	Description
"showVoiceSearchButton"	Affichez un bouton de recherche vocale si la recherche vocale est disponible sur l'appareil. Si cette valeur est définie, "launchWebSearch" ou "launchRecognizer" doivent également être définis, séparés par le caractère barre verticale (|).
"launchWebSearch"	Le bouton de recherche vocale redirige l'utilisateur directement vers une activité de recherche vocale sur le Web intégrée. La plupart des applications n'utilisent pas cet indicateur, car il éloigne l'utilisateur de l'activité dans laquelle la recherche a été appelée.
"launchRecognizer"	Le bouton de recherche vocale redirige l'utilisateur directement vers une activité d'enregistrement vocal intégrée. Cette activité invite l'utilisateur à parler, transcrit le texte prononcé et transmet le texte de la requête résultant à l'activité de recherche, comme si l'utilisateur l'avait saisi dans l'interface utilisateur de recherche et appuyé sur le bouton de recherche.

android:voiceLanguageModel

Mot clé. Modèle linguistique qui doit être utilisé par le système de reconnaissance vocale. Les valeurs suivantes sont acceptées :

Valeur	Description
"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 Web pour les expressions plus courtes, de type recherche. Cette option 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 attendue, exprimée sous forme de valeur de chaîne d'une constante dans Locale, telle que "de" pour l'allemand ou "fr" pour le français. Cette valeur 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 comme requête principale de l'intention ACTION_SEARCH. Doit être égal ou supérieur à 1. Utilisez EXTRA_RESULTS pour obtenir les résultats de l'intention. Si aucune valeur n'est fournie, le module de reconnaissance choisit le nombre de résultats à renvoyer.

<actionkey>

Définit une touche et un comportement d'appareil 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 à la suggestion de contact actuellement sélectionnée lorsque l'utilisateur appuie sur le bouton APPEL.

Toutes les touches d'action ne sont pas disponibles sur tous les appareils, et toutes les touches ne peuvent pas être remplacées de cette manière. Par exemple, la touche "Accueil" ne peut pas être remplacée et doit toujours renvoyer à 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 android:keycode pour définir la clé et au moins l'un des trois autres attributs pour définir l'action de recherche.

Attributs :

android:keycode

Chaîne. (Obligatoire) Code clé de KeyEvent qui représente la touche d'action à laquelle vous souhaitez répondre (par exemple, "KEYCODE_CALL"). Cette valeur est ajoutée à l'intention ACTION_SEARCH qui est transmise à votre activité pouvant faire l'objet d'une recherche. Pour examiner le code clé, 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 la touche d'action est enfoncée pendant que l'utilisateur saisit le texte de la requête. Cette valeur est ajoutée à l'intent ACTION_SEARCH que le système transmet à votre activité pouvant faire l'objet d'une recherche. Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

Chaîne. Message d'action à envoyer si la touche d'action est enfoncée lorsqu'une suggestion est sélectionnée. Cette valeur est ajoutée à l'intent que le système transmet à votre activité de recherche, à l'aide de l'action que vous définissez pour la suggestion. Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG). Cette action ne doit être utilisée que si toutes vos suggestions la prennent en charge. Si toutes les suggestions ne peuvent pas gérer la même clé d'action, vous devez utiliser l'attribut android:suggestActionMsgColumn suivant.

android:suggestActionMsgColumn

Chaîne. Nom de la colonne de votre fournisseur de contenu qui définit le message d'action pour cette clé d'action, à envoyer si l'utilisateur appuie sur la clé d'action lorsqu'une suggestion est sélectionnée. Cet attribut vous permet de contrôler la touche d'action pour chaque 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 pour laquelle vous souhaitez fournir un message d'action, puis indiquer le nom de cette colonne dans cet attribut. Le système examine le curseur de suggestion, en utilisant la chaîne fournie ici pour sélectionner la colonne de message d'action, puis sélectionne la chaîne de message d'action à partir du curseur. Cette chaîne est ajoutée à l'intent que le système transmet à votre activité de recherche, à 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>