Cette page a été traduite par l'API Cloud Translation.

Configuration de la recherche

Pour implémenter la recherche avec l'aide du système Android, c'est-à-dire pour fournir des résultats de recherche des requêtes à une activité et fournir des suggestions de recherche (votre application doit fournir une requête de configuration 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 plus sur la mise en œuvre des fonctionnalités de recherche pour votre application, consultez Créez 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 faciliter la recherche.

Attributs:

android:label

Ressource de chaîne. (Obligatoire) Nom de votre application. Il doit être identique à nom appliqué à l'attribut android:label de votre <activity> ou <application> dans le fichier manifeste. Ce libellé n'est visible par l'utilisateur que lorsque vous définissez De android:includeInGlobalSearch à "true", auquel cas, ce libellé est utilisé pour 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 texte de recherche lorsque aucun texte n'est saisi. Elles indiquent à l'utilisateur les contenus pouvant être recherchés. Pour plus de cohérence avec d'autres applications Android, mettez en forme la chaîne android:hint comme suit : <content-or-product>". 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. Disponible Les modes définissent la manière dont le texte de la requête doit être réécrit lorsqu'une suggestion personnalisée reçoit le focus. Les valeurs de mode suivantes sont acceptées:

Valeur	Description
`"queryRewriteFromData"`	Utilisez la valeur du paramètre `SUGGEST_COLUMN_INTENT_DATA` pour réécrire le texte de la requête. Il ne doit être utilisé que lorsque les valeurs dans les `SUGGEST_COLUMN_INTENT_DATA` sont adaptées à l'inspection et à la modification des données par les utilisateurs ; tels que les URI HTTP.
`"queryRewriteFromText"`	Utilisez la valeur du paramètre `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 Ajoutez des suggestions de recherche personnalisées.

android:searchButtonText

Ressource de chaîne. Texte à afficher dans le bouton qui exécute la recherche. Par par défaut, le bouton affiche une icône de recherche (loupe), ce qui est idéal pour l'internationalisation. N'utilisez donc pas cet attribut pour modifier le bouton, à moins que le comportement autre chose qu'une recherche, comme une demande d'URL dans un navigateur Web.

android:inputType

Mot clé. Définit le type de méthode de saisie à utiliser, par exemple le type de logiciel clavier. Pour la plupart des recherches, pour lesquelles du texte libre est attendu, cet attribut n'est pas nécessaire. Consultez inputType pour obtenir une liste de les valeurs appropriées pour cet attribut.

android:imeOptions

Mot clé. Fournit des options supplémentaires pour le mode de saisie. Pour la plupart des recherches, dans du texte libre attendu, vous n'avez pas besoin de cet attribut. L'IME par défaut est actionSearch, qui fournit l'attribut "recherche" au lieu d'un retour chariot dans clavier virtuel. Voir imeOptions afin d'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 attributs supplémentaires qui configurent les communications avec le fournisseur de contenu. Lorsque vous fournissez des suggestions, vous avez besoin de certains des attributs <searchable> suivants:

android:searchSuggestAuthority: Chaîne. (Obligatoire pour fournir des suggestions de recherche.) Cette valeur doit correspondre au chaîne d'autorité fournie dans le android:authorities de l'élément <provider> du fichier manifeste Android.
android:searchSuggestPath: Chaîne. Ce chemin d'accès est utilisé comme une partie des suggestions requête Uri, après le préfixe et et avant le parcours standard des suggestions. Cette étape n'est obligatoire que si vous disposez un seul fournisseur de contenu émet plusieurs types de suggestions, par exemple pour différentes les types de données, et vous avez besoin d'une solution pour faire la distinction entre les suggestions de requêtes de l'IA générative.
android:searchSuggestSelection: Chaîne. Cette valeur est transmise 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. Il doit contenir un seul point d'interrogation en tant qu'espace réservé pour le paramètre 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 de la méthode selectionArgs, puis ignorez 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 ("android.intent.action.VIEW", par exemple) ; Si cette valeur n'est pas remplacée par la suggestion sélectionnée à l'aide de la propriété SUGGEST_COLUMN_INTENT_ACTION la valeur est placée dans le champ "action" de la 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 la suggestion sélectionnée n'est pas remplacée, via la propriété SUGGEST_COLUMN_INTENT_DATA colonne : cette valeur est placée dans le champ de données de la Intent lorsque l'utilisateur appuie sur une suggestion.
android:searchSuggestThreshold: Nombre entier. Le nombre minimum de caractères requis pour déclencher la recherche de suggestions. Cela garantit uniquement que le système n'interroge pas fournisseur de contenu pour tout ce qui est inférieur 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 pour ajouter des suggestions de recherche personnalisées et ajout de suggestions personnalisées.

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

android:includeInGlobalSearch: Booléen. (Obligatoire pour fournir des suggestions de recherche dans le champ champ de recherche rapide.) Définissez cette option sur "true" si vous souhaitez que vos suggestions soient dans le champ de recherche rapide accessible mondialement. L'utilisateur doit toujours activer votre application en tant qu'élément interrogeable dans les paramètres de recherche du système avant 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, qui s'affiche dans le champ de recherche de votre application. Votre description doit décrire de manière concise le contenu qui peut être recherché. Pour Exemple : "Artistes, albums et titres" pour une application musicale, ou "Notes enregistrées" pendant l’application bloc-notes.
android:queryAfterZeroResults: Booléen. Définissez ce paramètre sur "true" si vous souhaitez que votre fournisseur de contenu soit appelé pour les sur-ensembles de requêtes qui n'avaient renvoyé aucun résultat auparavant. Par exemple, si Votre fournisseur de contenu ne renvoie aucun résultat pour "bo". La requête doit être envoyée pour "bob". Si défini sur "false", les sur-ensembles sont ignorés pour une seule session ("bob") n'invoque pas de nouvelle requête. Cela n'est valable que pendant la durée de la boîte de dialogue de recherche ou la durée de vie l'activité lorsque vous utilisez le widget Recherche. Lorsque la boîte de dialogue de recherche ou l'activité est rouverte, "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 Les 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. 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"`	Afficher un bouton de recherche vocale, si cette fonctionnalité est disponible sur l'appareil. Si défini, alors `"launchWebSearch"` ou `"launchRecognizer"` doit également être défini, séparés par une barre verticale (`\|`).
`"launchWebSearch"`	Le bouton de la recherche vocale redirige directement l'utilisateur à une activité de recherche vocale intégrée sur le Web. La plupart des applications n'utilisent pas cet indicateur, cela éloigne l'utilisateur de l'activité dans laquelle la recherche a été appelée.
`"launchRecognizer"`	Le bouton de la recherche vocale prend directement l'utilisateur à une activité d'enregistrement vocal intégrée. Cette activité invite l'utilisateur à parler, transcrit le texte parlé et transmet le résultat le texte de requête à l'activité de recherche, comme si l'utilisateur le saisissait dans et appuyé sur le bouton de recherche.

android:voiceLanguageModel

Mot clé. Le modèle de langage doit être utilisé par le système de reconnaissance vocale. Les valeurs suivantes sont acceptées:

Valeur	Description
`"free_form"`	Utilisez la reconnaissance vocale au format libre pour dicter vos requêtes. Il s'agit principalement optimisé pour l'anglais. Il s'agit de l'option par défaut.
`"web_search"`	Utilisez la reconnaissance par terme de recherche sur le Web pour des expressions plus courtes, semblables à celles d'une recherche. C'est disponible dans plus de langues que `"free_form"`.

Voir EXTRA_LANGUAGE_MODEL pour plus des informations.

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 la forme de la valeur de chaîne de une constante dans Locale, comme "de" pour l'allemand ou "fr" pour le français. Cette étape n'est nécessaire que s'il s'agit de valeurs différentes à partir de la valeur actuelle de Locale.getDefault().

android:voiceMaxResults

Nombre entier. Définit le nombre maximal de résultats à renvoyer. y compris les "meilleurs" Résultat, qui est toujours fourni en tant que ACTION_SEARCH la requête principale de l'intent. Doit être supérieur ou égal à 1. Utilisez EXTRA_RESULTS pour obtenir les résultats de l'intent. Si aucune valeur n'est fournie, le programme 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 d'un simple geste sur un bouton de l'appareil, en fonction de la requête en cours ou de l'élément sélectionné suggestion. Par exemple, l'application Contacts propose une action de recherche pour lancer la recherche appel à la suggestion de contact actuellement sélectionnée lorsque l'utilisateur appuie sur le bouton APPEL.

Les touches d'action ne sont pas toutes disponibles sur tous les appareils, et toutes les clés ne peuvent pas être remplacées dans ce de la même façon. Par exemple, la colonne "Accueil" clé ne peut pas être remplacée et doit toujours revenir à la page d'accueil l'écran. Veillez également à ne pas définir de touche d'action pour une touche nécessaire à la saisie d'une requête de recherche. requête. Cela permet de limiter les touches d'action disponibles et raisonnables au bouton d'appel et au menu .

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

Attributs:

android:keycode: Chaîne. (Obligatoire) Un code clé de KeyEvent, qui représente la touche d'action à laquelle vous souhaitez répondre (par exemple, "KEYCODE_CALL") ; Ce est ajouté ACTION_SEARCH qui est transmis à votre activité de recherche. Pour examiner le code clé, utilisez getIntExtra(SearchManager.ACTION_KEY) Toutes les clés ne sont pas compatibles avec une action de recherche, car beaucoup d'entre elles sont utilisées pour la saisie, navigation ou fonctions système.
android:queryActionMsg: Chaîne. Un message d'action à envoyer si vous appuyez sur la touche d'action pendant que la l'utilisateur saisit le texte de la requête. Il est ajouté ACTION_SEARCH que le système transmet à votre activité de recherche. Pour examiner la chaîne, utilisez getStringExtra(SearchManager.ACTION_MSG)
android:suggestActionMsg: Chaîne. Un message d'action à envoyer si l'utilisateur appuie sur la touche d'action pendant qu'un la suggestion est au premier plan. Il est ajouté à 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 le , utilisez getStringExtra(SearchManager.ACTION_MSG) N'utilisez cette touche que si toutes vos suggestions prennent en charge cette touche d'action. Si ce n'est pas le cas peuvent gérer la même touche d'action, vous devez utiliser à la place android:suggestActionMsgColumn.
android:suggestActionMsgColumn: Chaîne. Nom de la colonne de votre fournisseur de contenu qui définit la message d'action pour cette touche d'action, qui doit être envoyé si l'utilisateur appuie sur cette touche lorsqu'une suggestion est active. Cet attribut vous permet de contrôler la touche d'action d'une suggestion par suggestion. En effet, au lieu d'utiliser L'attribut android:suggestActionMsg permet de définir le message d'action pour tous des suggestions, chaque entrée de votre fournisseur de contenu renvoie un message d'action spécifique.
Tout d'abord, vous devez définir une colonne dans votre fournisseur de contenu pour chaque suggestion à fournir. un message d'action, puis indiquez le nom de cette colonne dans cet attribut. Le système examine votre curseur de suggestion et utilise la chaîne fournie ici pour sélectionner votre action message, puis sélectionne la chaîne du message d'action à partir du curseur. Cette chaîne est ajouté à l'intent que le système transmet à votre activité de recherche, à l'aide de l'action pour obtenir des 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 touche 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>

Configuration de la recherche

Attributs des suggestions de recherche

Attributs du champ de recherche rapide

Attributs de la recherche vocale