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

Ajouter des suggestions de recherche personnalisées

Lorsque vous utilisez la boîte de dialogue de recherche ou le widget Recherche Android, vous pouvez fournir des suggestions de recherche personnalisées créées à partir des données de votre application. Par exemple, si votre application est un dictionnaire, vous pouvez suggérer des mots du dictionnaire correspondant au texte saisi dans le champ de recherche avant que l'utilisateur n'ait terminé de saisir sa requête. Ces suggestions sont précieuses, car elles peuvent prédire efficacement ce que veut l'utilisateur et lui fournir un accès instantané. La figure 1 illustre un exemple de boîte de dialogue de recherche avec des suggestions personnalisées.

Une fois que vous avez fourni des suggestions personnalisées, vous pouvez également les rendre disponibles dans le champ de recherche rapide du système, qui permet d'accéder à votre contenu en dehors de votre application.

Avant d'ajouter des suggestions personnalisées, implémentez la boîte de dialogue de recherche Android ou un widget Recherche pour les recherches dans votre application. Consultez Créer une interface de recherche et Fournisseurs de contenu.

Principes de base

Figure 1 : Capture d'écran d'une boîte de dialogue de recherche avec des suggestions de recherche personnalisées.

Lorsque l'utilisateur sélectionne une suggestion personnalisée, le système envoie un Intent à votre activité d'index de recherche. Contrairement à une requête de recherche normale qui envoie un intent avec l'action ACTION_SEARCH, vous pouvez définir vos suggestions personnalisées pour utiliser ACTION_VIEW (ou toute autre action d'intent) et inclure également les données pertinentes par rapport à la suggestion sélectionnée. Dans l'exemple du dictionnaire, lorsque l'utilisateur sélectionne une suggestion, l'application peut immédiatement ouvrir la définition de ce mot, au lieu de rechercher des correspondances dans le dictionnaire.

Pour fournir des suggestions personnalisées, procédez comme suit:

Mettez en œuvre une activité de recherche de base, comme décrit dans la section Créer une interface de recherche.
Modifiez la configuration interrogeable avec les informations sur le fournisseur de contenu qui fournit des suggestions personnalisées.
Créez une table pour obtenir vos suggestions, par exemple dans un SQLiteDatabase, et mettez-la en forme avec les colonnes requises.
Créez un fournisseur de contenu ayant accès à votre table de suggestions, puis déclarez-le dans votre fichier manifeste.
Déclarez le type de Intent à envoyer lorsque l'utilisateur sélectionne une suggestion, y compris une action personnalisée et des données personnalisées.

Tout comme le système Android affiche la boîte de dialogue de recherche, il affiche également vos suggestions de recherche. Vous avez besoin d'un fournisseur de contenu à partir duquel le système peut récupérer vos suggestions. Pour savoir comment créer un fournisseur de contenu, consultez Fournisseurs de contenu.

Lorsque le système détermine que votre activité peut faire l'objet d'une recherche et fournit des suggestions de recherche, la procédure suivante a lieu lorsque l'utilisateur saisit une requête:

Le système reçoit le texte de la requête de recherche (c'est-à-dire tout ce qui a été saisi jusqu'à présent) et envoie à votre fournisseur de contenu une requête qui gère vos suggestions.
Votre fournisseur de contenu renvoie un Cursor qui pointe vers toutes les suggestions pertinentes par rapport au texte de la requête de recherche.
Le système affiche la liste des suggestions fournies par Cursor.

Une fois les suggestions personnalisées affichées, voici ce qui peut se produire:

Si l'utilisateur saisit une autre lettre ou modifie la requête de quelque manière que ce soit, les étapes précédentes se répètent et la liste de suggestions est mise à jour en conséquence.
Si l'utilisateur effectue la recherche, les suggestions sont ignorées et la recherche est transmise à votre activité consultable à l'aide de l'intent ACTION_SEARCH normal.
Si l'utilisateur sélectionne une suggestion, un intent est envoyé à votre activité consultable, avec une action personnalisée et des données personnalisées permettant à votre application d'ouvrir le contenu suggéré.

Modifier la configuration interrogeable

Pour ajouter la prise en charge des suggestions personnalisées, ajoutez l'attribut android:searchSuggestAuthority à l'élément <searchable> de votre fichier de configuration inclus dans l'index de recherche, comme illustré dans l'exemple suivant:

<?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>

Vous aurez peut-être besoin d'attributs supplémentaires, en fonction du type d'intent que vous joignez à chaque suggestion et de la manière dont vous souhaitez mettre en forme les requêtes à votre fournisseur de contenu. Les autres attributs facultatifs sont abordés dans les sections suivantes.

Créer un fournisseur de contenu

Pour créer un fournisseur de contenu afin d'obtenir des suggestions personnalisées, consultez d'abord la section Fournisseurs de contenu pour découvrir comment créer un fournisseur de contenu. Un fournisseur de contenu pour les suggestions personnalisées est semblable à tout autre fournisseur de contenu. Toutefois, pour chaque suggestion que vous fournissez, la ligne correspondante de Cursor doit inclure des colonnes spécifiques que le système comprend et utilise pour mettre en forme les suggestions.

Lorsque l'utilisateur saisit du texte dans la boîte de dialogue de recherche ou dans le widget de recherche, le système interroge votre fournisseur de contenu pour obtenir des suggestions en appelant query() chaque fois qu'une lettre est saisie. Dans votre implémentation de query(), votre fournisseur de contenu doit rechercher vos données de suggestion et renvoyer un Cursor qui pointe vers les lignes qu'il considère comme de bonnes suggestions.

Les deux sections suivantes expliquent comment créer un fournisseur de contenu pour les suggestions personnalisées:

Gérer la requête de suggestion: Comment le système envoie les requêtes à votre fournisseur de contenu et comment les gérer.
Créer une table de suggestions: Comment définir les colonnes attendues par le système dans le Cursor renvoyé avec chaque requête.

Gérer la requête de suggestion

Lorsque le système demande des suggestions à votre fournisseur de contenu, il appelle la méthode query() de celui-ci. Implémentez cette méthode pour rechercher vos données de suggestion et renvoyer un Cursor pointant vers les suggestions que vous jugez pertinentes.

Voici un récapitulatif des paramètres que le système transmet à la méthode query(), classés dans l'ordre:

uri: Il s'agit toujours d'un Uri de contenu, formaté comme suit :
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Le comportement par défaut consiste pour le système à transmettre cet URI et à y ajouter le texte de la requête:

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

Le texte de la requête situé à la fin est encodé à l'aide de règles d'encodage d'URI. Vous devrez donc peut-être le décoder avant d'effectuer une recherche.

La partie optional.suggest.path n'est incluse dans l'URI que si vous définissez un tel chemin dans votre fichier de configuration inclus dans l'index de recherche avec l'attribut android:searchSuggestPath. Elle n'est nécessaire que si vous utilisez le même fournisseur de contenu pour plusieurs activités interrogeables. Si c'est le cas, faites la distinction entre la source de la requête de suggestion.

Remarque:SUGGEST_URI_PATH_QUERY n'est pas la chaîne littérale fournie dans l'URI, mais une constante. Utilisez-le si vous devez vous référer à ce chemin d'accès.
projection: Toujours nul.
selection: Valeur fournie dans l'attribut android:searchSuggestSelection de votre fichier de configuration inclus dans l'index de recherche, ou valeur nulle si vous ne déclarez pas l'attribut android:searchSuggestSelection. La section suivante aborde ce sujet plus en détail.
selectionArgs: Contient la requête de recherche en tant que premier et unique élément du tableau si vous déclarez l'attribut android:searchSuggestSelection dans la configuration incluse dans l'index de recherche. Si vous ne déclarez pas android:searchSuggestSelection, ce paramètre est nul. La section suivante aborde ce sujet plus en détail.
sortOrder: Toujours nul.

Le système peut vous envoyer le texte de la requête de recherche de deux manières. La méthode par défaut consiste à inclure le texte de la requête en tant que dernier chemin de l'URI de contenu transmis dans le paramètre uri. Toutefois, si vous incluez une valeur de sélection dans l'attribut android:searchSuggestSelection de votre configuration incluse dans l'index de recherche, le texte de la requête est alors transmis en tant que premier élément du tableau de chaînes selectionArgs. Ces deux options sont décrites ci-dessous.

Obtenir la requête dans l'URI

Par défaut, la requête est ajoutée en tant que dernier segment du paramètre uri (un objet Uri). Dans ce cas, pour récupérer le texte de la requête, utilisez getLastPathSegment(), comme illustré dans l'exemple suivant:

Kotlin

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

Java

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

Cette opération renvoie le dernier segment de Uri, qui correspond au texte de requête saisi par l'utilisateur.

Obtenir la requête dans les arguments de sélection

Au lieu d'utiliser l'URI, il peut être plus logique que votre méthode query() reçoive tout ce dont elle a besoin pour effectuer la recherche. Vous pouvez également souhaiter que les paramètres selection et selectionArgs contiennent les valeurs appropriées. Dans ce cas, ajoutez l'attribut android:searchSuggestSelection à votre configuration d'index de recherche avec votre chaîne de sélection SQLite. Dans la chaîne de sélection, insérez un point d'interrogation (?) comme espace réservé pour la requête de recherche réelle. Le système appelle query() avec la chaîne de sélection comme paramètre selection et la requête de recherche comme premier élément du tableau selectionArgs.

Par exemple, voici comment former l'attribut android:searchSuggestSelection pour créer une instruction de recherche en texte intégral:

<?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>

Avec cette configuration, la méthode query() diffuse le paramètre selection en tant que "word MATCH ?" et le paramètre selectionArgs en tant que requête de recherche. Lorsque vous les transmettez à une méthode query() SQLite, leurs arguments respectifs sont synthétisés ensemble. Le point d'interrogation est donc remplacé par le texte de la requête. Si vous recevez des requêtes de suggestion de cette manière et que vous devez ajouter des caractères génériques au texte de la requête, ajoutez-les ou préfixez-les au paramètre selectionArgs, car cette valeur est entre guillemets et insérée à la place du point d'interrogation.

Dans l'exemple précédent, un autre attribut est android:searchSuggestIntentAction, qui définit l'action d'intent envoyée avec chaque intent lorsque l'utilisateur sélectionne une suggestion. Ce point est abordé plus en détail dans la section Déclarer un intent pour les suggestions.

Conseil:Si vous ne souhaitez pas définir de clause de sélection dans l'attribut android:searchSuggestSelection, mais que vous souhaitez tout de même recevoir le texte de la requête dans le paramètre selectionArgs, indiquez une valeur non nulle pour l'attribut android:searchSuggestSelection. Cela déclenche la transmission de la requête dans selectionArgs, et vous pouvez ignorer le paramètre selection. De cette façon, vous pouvez définir la clause de sélection réelle à un niveau inférieur afin que votre fournisseur de contenu n'ait pas à la gérer.

Créer une table de suggestions

Lorsque vous renvoyez des suggestions au système avec un Cursor, le système s'attend à des colonnes spécifiques pour chaque ligne. Que vous stockiez vos données de suggestion dans une base de données SQLite sur l'appareil, dans une base de données sur un serveur Web ou dans un autre format sur l'appareil ou sur le Web, formatez les suggestions sous forme de lignes dans une table et présentez-les avec un élément Cursor.

Remarque:Si vos suggestions de recherche ne sont pas stockées dans un format de table (une table SQLite, par exemple) à l'aide des colonnes requises par le système, vous pouvez rechercher des correspondances dans vos données de suggestion, puis les mettre en forme dans la table nécessaire à chaque requête. Pour ce faire, créez un MatrixCursor à l'aide des noms de colonne requis, puis ajoutez une ligne pour chaque suggestion à l'aide de addRow(Object[]). Renvoyez le produit final à partir de la méthode query() de votre fournisseur de contenu.

Le système peut comprendre plusieurs colonnes, mais seules deux d'entre elles sont requises:

_ID: ID de ligne d'entier unique pour chaque suggestion. Le système l'exige pour présenter des suggestions dans un ListView.
SUGGEST_COLUMN_TEXT_1: Chaîne présentée comme suggestion.

Les colonnes suivantes sont toutes facultatives. La plupart sont abordés plus en détail dans les sections suivantes.

SUGGEST_COLUMN_TEXT_2: Chaîne. Si votre Cursor inclut cette colonne, toutes les suggestions sont fournies sur deux lignes. La chaîne de cette colonne s'affiche sous la forme d'une deuxième ligne de texte plus petite en dessous du texte de suggestion principal. Elle peut être nulle ou vide pour indiquer l'absence de texte secondaire.
SUGGEST_COLUMN_ICON_1: Chaîne de ressource drawable, contenu ou URI de fichier. Si votre Cursor inclut cette colonne, toutes les suggestions sont fournies au format icône plus texte, avec l'icône drawable à gauche. Elle peut être nulle ou nulle pour indiquer qu'il n'y a pas d'icône sur cette ligne.
SUGGEST_COLUMN_ICON_2: Chaîne de ressource drawable, contenu ou URI de fichier. Si votre Cursor inclut cette colonne, toutes les suggestions sont fournies au format icône plus texte, avec l'icône à droite. Sa valeur peut être "null" ou "zéro" pour indiquer qu'il n'y a pas d'icône sur cette ligne.
SUGGEST_COLUMN_INTENT_ACTION: Chaîne d'action d'intent. Si cette colonne existe et contient une valeur à la ligne donnée, l'action définie ici est utilisée lors de la création de l'intent de la suggestion. Si l'élément n'est pas fourni, l'action est effectuée à partir du champ android:searchSuggestIntentAction de votre configuration incluse dans l'index de recherche. Si votre action est la même pour toutes les suggestions, il est plus efficace de la spécifier à l'aide de android:searchSuggestIntentAction et d'omettre cette colonne.
SUGGEST_COLUMN_INTENT_DATA: Chaîne d'URI de données. Si cette colonne existe et contient une valeur à la ligne donnée, ces données sont utilisées lors de la création de l'intent de la suggestion. Si l'élément n'est pas fourni, les données sont issues du champ android:searchSuggestIntentData de votre configuration incluse dans l'index de recherche. Si aucune source n'est fournie, le champ de données de l'intent est nul. Si vos données sont les mêmes pour toutes les suggestions ou peuvent être décrites à l'aide d'une partie constante et d'un ID spécifique, il est plus efficace de les spécifier à l'aide de android:searchSuggestIntentData et d'omettre cette colonne.
SUGGEST_COLUMN_INTENT_DATA_ID: Chaîne de chemin d'URI. Si cette colonne existe et contient une valeur à la ligne donnée, "/" et cette valeur sont ajoutés au champ de données de l'intent. N'utilisez cette option que si le champ de données spécifié par l'attribut android:searchSuggestIntentData dans la configuration consultable est déjà défini sur une chaîne de base appropriée.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Données arbitraires. Si cette colonne existe et contient une valeur sur une ligne donnée, il s'agit des données supplémentaires utilisées lors de la création de l'intent de la suggestion. S'il n'est pas fourni, le champ de données supplémentaires de l'intent est nul. Cette colonne permet aux suggestions de fournir des données supplémentaires qui sont incluses en tant que telles dans la clé EXTRA_DATA_KEY de l'intent.
SUGGEST_COLUMN_QUERY: Si cette colonne existe et que cet élément existe à la ligne donnée, il s'agit des données utilisées lors de la création de la requête de la suggestion, incluses en tant qu'extra dans la clé QUERY de l'intent. Elle est obligatoire si l'action de la suggestion est ACTION_SEARCH. Sinon, elle est facultative.
SUGGEST_COLUMN_SHORTCUT_ID: Utilisé uniquement lorsque vous fournissez des suggestions pour le champ de recherche rapide. Cette colonne indique si une suggestion de recherche doit être stockée en tant que raccourci et si elle doit être validée. Des raccourcis sont généralement créés lorsque l'utilisateur appuie sur une suggestion du champ de recherche rapide. S'il est manquant, le résultat est stocké en tant que raccourci et n'est jamais actualisé. S'il est défini sur SUGGEST_NEVER_MAKE_SHORTCUT, le résultat n'est pas stocké en tant que raccourci. Sinon, l'ID de raccourci est utilisé pour rechercher une suggestion à jour à l'aide de SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Utilisé uniquement lorsque vous fournissez des suggestions pour le champ de recherche rapide. Cette colonne indique qu'une icône de chargement doit s'afficher à la place d'une icône de SUGGEST_COLUMN_ICON_2 pendant que le raccourci de cette suggestion est actualisé dans le champ de recherche rapide.

La plupart de ces colonnes sont abordées plus en détail dans les sections suivantes.

Déclarer un intent pour obtenir des suggestions

Lorsque l'utilisateur sélectionne une suggestion dans la liste qui apparaît sous la boîte de dialogue ou le widget de recherche, le système envoie un Intent personnalisé à votre activité d'index de recherche. Vous devez définir l'action et les données associées à l'intent.

Déclarer l'action d'intent

L'action d'intent la plus courante pour une suggestion personnalisée est ACTION_VIEW. Elle est appropriée lorsque vous souhaitez ouvrir un élément, comme la définition d'un mot, les coordonnées d'une personne ou une page Web. Cependant, l'action d'intent peut être n'importe quelle autre action et peut être différente pour chaque suggestion.

Selon que vous souhaitez que toutes les suggestions utilisent la même action d'intent ou non, vous pouvez définir cette action de deux manières:

Utilisez l'attribut android:searchSuggestIntentAction de votre fichier de configuration inclus dans l'index de recherche afin de définir l'action pour toutes les suggestions, comme illustré dans l'exemple suivant :

<?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>

Utilisez la colonne SUGGEST_COLUMN_INTENT_ACTION pour définir l'action pour chaque suggestion. Pour ce faire, ajoutez la colonne SUGGEST_COLUMN_INTENT_ACTION à votre table de suggestions et, pour chaque suggestion, placez-y l'action à utiliser, par exemple "android.intent.action.VIEW".

Vous pouvez également combiner ces deux techniques. Par exemple, vous pouvez inclure l'attribut android:searchSuggestIntentAction avec une action à utiliser avec toutes les suggestions par défaut, puis remplacer cette action pour certaines suggestions en déclarant une autre action dans la colonne SUGGEST_COLUMN_INTENT_ACTION. Si vous n'incluez pas de valeur dans la colonne SUGGEST_COLUMN_INTENT_ACTION, l'intent fourni dans l'attribut android:searchSuggestIntentAction est utilisé.

Remarque:Si vous n'incluez pas l'attribut android:searchSuggestIntentAction dans la configuration incluse dans l'index de recherche, vous devez inclure une valeur dans la colonne SUGGEST_COLUMN_INTENT_ACTION pour chaque suggestion, sinon l'intent échouera.

Déclarer des données d'intent

Lorsque l'utilisateur sélectionne une suggestion, votre activité interrogeable reçoit l'intent avec l'action que vous avez définie (comme indiqué dans la section précédente), mais l'intent doit également transporter des données pour votre activité afin d'identifier la suggestion sélectionnée. Plus précisément, les données doivent être uniques pour chaque suggestion, comme l'ID de ligne de la suggestion dans votre table SQLite. Lorsque l'intent est reçu, vous pouvez récupérer les données associées avec getData() ou getDataString().

Vous pouvez définir les données incluses avec l'intent de deux manières:

Définissez les données pour chaque suggestion dans la colonne SUGGEST_COLUMN_INTENT_DATA de votre table de suggestions.
Fournissez toutes les informations de données nécessaires pour chaque intent dans le tableau des suggestions en incluant la colonne SUGGEST_COLUMN_INTENT_DATA, puis en y ajoutant des données uniques pour chaque ligne. Les données de cette colonne sont associées à l'intent exactement comme vous les avez définis dans cette colonne. Vous pouvez ensuite le récupérer à l'aide de getData() ou de getDataString().

Conseil: Il est généralement plus facile d'utiliser l'ID de ligne de la table comme données d'intent, car il est toujours unique. Pour ce faire, le moyen le plus simple consiste à utiliser le nom de colonne SUGGEST_COLUMN_INTENT_DATA comme alias pour la colonne d'ID de ligne.
Fragmentez un URI de données en deux parties: la partie commune à toutes les suggestions et la partie propre à chacune d'elles. Placez ces parties dans l'attribut android:searchSuggestintentData de la configuration interrogeable et dans la colonne SUGGEST_COLUMN_INTENT_DATA_ID de votre table de suggestions, respectivement.
L'exemple suivant montre comment déclarer la partie de l'URI commune à toutes les suggestions dans l'attribut android:searchSuggestIntentData de votre configuration incluse dans l'index de recherche:
```
  <?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>
  
```
Incluez le chemin d'accès final de chaque suggestion (la partie unique) dans la colonne SUGGEST_COLUMN_INTENT_DATA_ID de votre table de suggestions. Lorsque l'utilisateur sélectionne une suggestion, le système extrait la chaîne de android:searchSuggestIntentData, ajoute une barre oblique (/), puis ajoute la valeur correspondante de la colonne SUGGEST_COLUMN_INTENT_DATA_ID pour former un URI de contenu complet. Vous pouvez ensuite récupérer Uri avec getData().

Ajouter d'autres données

Si vous devez exprimer plus d'informations avec votre intent, vous pouvez ajouter une autre colonne de table, telle que SUGGEST_COLUMN_INTENT_EXTRA_DATA, qui peut stocker des informations supplémentaires sur la suggestion. Les données enregistrées dans cette colonne sont placées dans le EXTRA_DATA_KEY du bundle supplémentaire de l'intent.

Gérer l'intent

Après avoir fourni des suggestions de recherche personnalisées avec des intents personnalisés, votre activité de recherche doit les gérer lorsque l'utilisateur sélectionne une suggestion. Cela s'ajoute à la gestion de l'intent ACTION_SEARCH, ce que fait déjà votre activité dans l'index de recherche. Voici un exemple de gestion des intents lors du rappel onCreate() de votre activité:

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);
}

Dans cet exemple, l'action d'intent est ACTION_VIEW, et les données contiennent un URI complet pointant vers l'élément suggéré, tel que synthétisé par la chaîne android:searchSuggestIntentData et la colonne SUGGEST_COLUMN_INTENT_DATA_ID. L'URI est ensuite transmis à la méthode showResult() locale qui interroge le fournisseur de contenu pour obtenir l'élément spécifié par l'URI.

Remarque:Vous n'avez pas besoin d'ajouter de filtre d'intent à votre fichier manifeste Android pour l'action d'intent que vous avez définie avec l'attribut android:searchSuggestIntentAction ou la colonne SUGGEST_COLUMN_INTENT_ACTION. Le système ouvre votre activité consultable par nom pour transmettre l'intent de la suggestion. L'activité n'a donc pas besoin de déclarer l'action acceptée.

Réécrire le texte de la requête

Par défaut, si l'utilisateur parcourt la liste de suggestions à l'aide de commandes directionnelles, telles qu'un trackball ou un pavé directionnel, le texte de la requête n'est pas mis à jour. Toutefois, vous pouvez réécrire temporairement le texte de la requête de l'utilisateur tel qu'il apparaît dans la zone de texte avec une requête correspondant à la suggestion sélectionnée. Cela permet à l'utilisateur de voir la requête suggérée. Il peut sélectionner le champ de recherche et modifier la requête avant de la diffuser en tant que recherche.

Vous pouvez réécrire le texte de la requête comme suit:

Ajoutez l'attribut android:searchMode à votre configuration incluse dans l'index de recherche avec la valeur "queryRewriteFromText". Dans ce cas, le contenu de la colonne SUGGEST_COLUMN_TEXT_1 de la suggestion est utilisé pour réécrire le texte de la requête.
Ajoutez l'attribut android:searchMode à votre configuration incluse dans l'index de recherche avec la valeur "queryRewriteFromData". Dans ce cas, le contenu de la colonne SUGGEST_COLUMN_INTENT_DATA de la suggestion est utilisé pour réécrire le texte de la requête. N'utilisez cette méthode qu'avec des URI ou d'autres formats de données destinés à être visibles par l'utilisateur, tels que des URL HTTP. N'utilisez pas de schémas d'URI internes pour réécrire la requête de cette manière.
Fournissez une chaîne de texte de requête unique dans la colonne SUGGEST_COLUMN_QUERY de votre table de suggestions. Si cette colonne est présente et contient une valeur pour la suggestion actuelle, elle permet de réécrire le texte de la requête et de remplacer l'une des implémentations précédentes.

Afficher les suggestions de recherche dans le champ de recherche rapide

Une fois que vous avez configuré votre application pour fournir des suggestions de recherche personnalisées, les rendre disponibles pour le champ de recherche rapide accessible dans le monde entier est aussi simple que de modifier votre configuration de recherche pour inclure android:includeInGlobalSearch avec la valeur "true".

Le seul scénario dans lequel un travail supplémentaire est nécessaire est lorsque votre fournisseur de contenu demande une autorisation de lecture. Dans ce cas, vous devez ajouter un élément <path-permission> pour que le fournisseur accorde un accès en lecture au champ de recherche rapide à votre fournisseur de contenu, comme illustré dans l'exemple suivant:

<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>

Dans cet exemple, le fournisseur limite l'accès en lecture et en écriture au contenu. L'élément <path-permission> modifie la restriction en accordant un accès en lecture au contenu situé à l'intérieur du préfixe de chemin "/search_suggest_query" lorsque l'autorisation "android.permission.GLOBAL_SEARCH" existe. Permet d'accéder au champ de recherche rapide afin qu'il puisse interroger votre fournisseur de contenu pour obtenir des suggestions.

Si votre fournisseur de contenu n'applique pas d'autorisations de lecture, le champ de recherche rapide le lit par défaut.

Activer les suggestions sur un appareil

Par défaut, les applications ne sont pas autorisées à fournir des suggestions dans le champ de recherche rapide, même si elles sont configurées pour le faire. L'utilisateur choisit d'inclure ou non les suggestions de votre application dans le champ de recherche rapide en ouvrant la section Éléments inclus dans l'index de recherche (située dans Paramètres > Recherche) et en activant votre application comme élément de recherche.

Chaque application disponible pour le champ de recherche rapide possède une entrée sur la page de paramètres Sources. Cette entrée comprend le nom de l'application, ainsi qu'une brève description du contenu pouvant faire l'objet d'une recherche dans l'application et mis à disposition pour les suggestions dans le champ de recherche rapide. Pour définir le texte de description de votre application incluse dans l'index de recherche, ajoutez l'attribut android:searchSettingsDescription à votre configuration incluse dans l'index de recherche, comme illustré dans l'exemple suivant:

<?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>

Faites en sorte que la chaîne pour android:searchSettingsDescription soit aussi concise que possible et indiquez le contenu inclus dans l'index de recherche. Par exemple, "Artistes, albums et pistes" pour une application de musique ou "Notes enregistrées" pour une application de bloc-notes. Il est important de fournir cette description afin que l'utilisateur sache quel type de suggestions est fournie. Incluez toujours cet attribut lorsque android:includeInGlobalSearch est "true".

Étant donné que l'utilisateur doit accéder au menu des paramètres pour activer les suggestions de recherche pour votre application, si la recherche est un aspect important de votre application, réfléchissez à la manière de les transmettre à vos utilisateurs. Par exemple, la première fois qu'un utilisateur lance l'application, vous pouvez ajouter une note expliquant comment activer les suggestions de recherche pour le champ de recherche rapide.

Gérer les raccourcis de suggestions du champ de recherche rapide

Les suggestions que l'utilisateur sélectionne dans le champ de recherche rapide peuvent être automatiquement transformées en raccourcis. Il s'agit de suggestions que le système copie à partir de votre fournisseur de contenu afin de pouvoir y accéder rapidement sans avoir à l'interroger à nouveau.

Par défaut, cette option est activée pour toutes les suggestions récupérées par le champ de recherche rapide. Toutefois, si vos données de suggestion changent au fil du temps, vous pouvez demander l'actualisation des raccourcis. Par exemple, si vos suggestions font référence à des données dynamiques, telles que l'état de présence d'un contact, demandez que les raccourcis de suggestions soient actualisés lorsqu'ils sont présentés à l'utilisateur. Pour ce faire, incluez SUGGEST_COLUMN_SHORTCUT_ID dans votre table de suggestions. Vous pouvez utiliser cette colonne pour configurer le comportement des raccourcis pour chaque suggestion de l'une des manières suivantes:

Configurez le champ de recherche rapide pour qu'il réinterroge votre fournisseur de contenu pour obtenir une version actualisée du raccourci de suggestion.

Indiquez une valeur dans la colonne SUGGEST_COLUMN_SHORTCUT_ID pour que la suggestion soit à nouveau interrogée pour obtenir une nouvelle version chaque fois que le raccourci est affiché. Le raccourci s'affiche rapidement avec les données les plus récentes jusqu'à ce que la requête d'actualisation soit renvoyée. La suggestion est alors actualisée avec les nouvelles informations. La requête d'actualisation est envoyée à votre fournisseur de contenu avec un chemin d'URI de SUGGEST_URI_PATH_SHORTCUT (au lieu de SUGGEST_URI_PATH_QUERY).

Faites en sorte que le Cursor que vous renvoyez contienne une suggestion utilisant les mêmes colonnes que la suggestion d'origine ou soit vide, indiquant que le raccourci n'est plus valide. Dans ce cas, la suggestion disparaît et le raccourci est supprimé.

Si une suggestion fait référence à des données dont l'actualisation peut prendre plus de temps, comme une actualisation basée sur le réseau, vous pouvez également ajouter la colonne SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING à votre table de suggestions avec la valeur "true" afin d'afficher une icône de chargement pour l'icône de droite jusqu'à la fin de l'actualisation. Toute valeur autre que "true" n'affiche pas l'icône de chargement de progression.
vous empêchez totalement de copier la suggestion dans un raccourci.

Indiquez la valeur SUGGEST_NEVER_MAKE_SHORTCUT dans la colonne SUGGEST_COLUMN_SHORTCUT_ID. Dans ce cas, la suggestion n'est jamais copiée dans un raccourci. Cela n'est nécessaire que si vous ne souhaitez absolument pas que la suggestion précédemment copiée s'affiche. Si vous fournissez une valeur normale pour la colonne, le raccourci de suggestion n'apparaît que jusqu'au retour de la requête d'actualisation.
Laissez le comportement par défaut des raccourcis s'appliquer.

Laissez le champ SUGGEST_COLUMN_SHORTCUT_ID vide pour chaque suggestion qui ne change pas et qui peut être enregistrée en tant que raccourci.

Si aucune de vos suggestions ne change, la colonne SUGGEST_COLUMN_SHORTCUT_ID n'est pas nécessaire.

À propos du classement des suggestions dans le champ de recherche rapide

Une fois que vous avez mis les suggestions de recherche de votre application à disposition du champ de recherche rapide, le classement du champ de recherche rapide détermine la façon dont les suggestions sont présentées à l'utilisateur pour une requête particulière. Cela peut dépendre du nombre d'autres applications ayant des résultats pour cette requête et de la fréquence à laquelle l'utilisateur sélectionne vos résultats par rapport à ceux d'autres applications. Nous n'avons aucune garantie quant au classement de vos suggestions ni à l'affichage des suggestions de votre application pour une requête donnée. En général, fournir des résultats de qualité augmente la probabilité que les suggestions de votre application soient présentées à un emplacement bien visible. Les applications qui fournissent des suggestions de mauvaise qualité sont plus susceptibles d'être moins bien classées ou de ne pas s'afficher.