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 ou le widget de 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 qui correspondent au texte saisi dans le champ de recherche avant que l'utilisateur ait terminé de saisir sa requête. Ces suggestions sont précieuses, car elles peuvent prédire efficacement ce que l'utilisateur souhaite et lui y donner accès instantanément. La figure 1 montre 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 la barre de recherche rapide à l'échelle du système, ce 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 de 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é pouvant faire l'objet d'une 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 des données pertinentes pour 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 :

Implémentez une activité de recherche de base, comme décrit dans Créer une interface de recherche.
Modifiez la configuration de recherche avec des informations sur le fournisseur de contenu qui fournit des suggestions personnalisées.
Créez un tableau, par exemple dans un SQLiteDatabase, pour vos suggestions et mettez-le en forme avec les colonnes requises.
Créez un fournisseur de contenu qui a accès à votre tableau de suggestions et déclarez le fournisseur dans votre fichier manifeste.
Déclarez le type de Intent à envoyer lorsque l'utilisateur sélectionne une suggestion, y compris une action 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. Consultez Fournisseurs de contenu pour savoir comment créer un fournisseur de contenu.

Lorsque le système identifie que votre activité est disponible dans la recherche et fournit des suggestions de recherche, la procédure suivante se déroule lorsque l'utilisateur saisit une requête :

Le système prend le texte de la requête de recherche (c'est-à-dire tout ce qui a été saisi jusqu'à présent) et exécute une requête auprès de votre fournisseur de contenu qui gère vos suggestions.
Votre fournisseur de contenu renvoie un Cursor qui pointe vers toutes les suggestions pertinentes pour le 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, les événements suivants peuvent 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 exécute la recherche, les suggestions sont ignorées et la recherche est transmise à votre activité pouvant faire l'objet d'une recherche à l'aide de l'intent ACTION_SEARCH normal.
Si l'utilisateur sélectionne une suggestion, un intent est envoyé à votre activité de recherche, avec une action et des données personnalisées pour que votre application puisse ouvrir le contenu suggéré.

Modifier la configuration indexable

Pour ajouter la prise en charge des suggestions personnalisées, ajoutez l'attribut android:searchSuggestAuthority à l'élément <searchable> dans votre fichier de configuration de recherche, comme indiqué 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, selon le type d'intent que vous associez à chaque suggestion et la façon dont vous souhaitez mettre en forme les requêtes adressées à votre fournisseur de contenu. Les autres attributs facultatifs sont décrits dans les sections suivantes.

Créer un fournisseur de contenu

Pour créer un fournisseur de contenu pour les suggestions personnalisées, commencez par consulter Fournisseurs de contenu pour savoir comment créer un fournisseur de contenu. Un fournisseur de contenu pour les suggestions personnalisées est semblable à n'importe quel autre fournisseur de contenu. Toutefois, pour chaque suggestion que vous fournissez, la ligne correspondante dans 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 ou 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 suggestions et renvoyer un Cursor qui pointe vers les lignes qu'il considère comme de bonnes suggestions.

La création d'un fournisseur de contenu pour les suggestions personnalisées est abordée dans les deux sections suivantes :

Gérer la requête de suggestion: Comment le système envoie des requêtes à votre fournisseur de contenu et comment les traiter.
Créer un tableau de suggestions: Découvrez comment définir les colonnes que le système attend 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 votre fournisseur de contenu. Implémentez cette méthode pour rechercher vos données de suggestions et renvoyer un Cursor pointant vers les suggestions que vous jugez pertinentes.

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

uri: Toujours un contenu Uri, mis en forme comme suit :
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Par défaut, le système transmet cet URI et y ajoute le texte de la requête :

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

Le texte de la requête à la fin est encodé à l'aide des règles d'encodage URI. Vous devrez 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 d'accès dans votre fichier de configuration pouvant faire l'objet d'une 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 pouvant faire l'objet d'une recherche. Si tel est le cas, clarifiez 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 faire référence à ce chemin d'accès.
projection: Toujours nul.
selection: La valeur fournie dans l'attribut android:searchSuggestSelection de votre fichier de configuration de recherche, ou "null" si vous ne déclarez pas l'attribut android:searchSuggestSelection. Ce point est abordé plus en détail dans la section suivante.
selectionArgs: Contient la requête de recherche comme premier et unique élément du tableau si vous déclarez l'attribut android:searchSuggestSelection dans votre configuration de recherche. Si vous ne déclarez pas android:searchSuggestSelection, ce paramètre est nul. Ce point est abordé plus en détail dans la section suivante.
sortOrder: Toujours nul.

Le système peut vous envoyer le texte de la requête de recherche de deux manières. Par défaut, le texte de la requête est inclus en tant que dernier chemin d'accès 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 la configuration de recherche, le texte de la requête est 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, qui est un objet Uri. Pour récupérer le texte de la requête dans ce cas, utilisez getLastPathSegment(), comme indiqué dans l'exemple suivant :

Kotlin

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

Java

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

Cela renvoie le dernier segment de Uri, qui correspond au texte de la requête saisie par l'utilisateur.

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

Au lieu d'utiliser l'URI, il peut être plus judicieux 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 de recherche avec votre chaîne de sélection SQLite. Dans la chaîne de sélection, incluez 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 vous pouvez 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, votre méthode query() fournit 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, en tant qu'arguments respectifs, ils sont synthétisés ensemble, ce qui signifie que le point d'interrogation est remplacé par le texte de la requête. Si vous recevez des requêtes de suggestions de cette manière et que vous devez ajouter des caractères génériques au texte de la requête, ajoutez-les au paramètre selectionArgs (ou faites-les précéder), car cette valeur est placée entre guillemets et insérée à la place du point d'interrogation.

Un autre attribut de l'exemple précédent 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 une intention 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, fournissez une valeur non nulle pour l'attribut android:searchSuggestSelection. Cela déclenche la requête pour transmettre selectionArgs. Vous pouvez ignorer le paramètre selection. Vous pouvez ainsi 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 un tableau de suggestions

Lorsque vous renvoyez des suggestions au système avec un Cursor, le système s'attend à ce que chaque ligne contienne des colonnes spécifiques. Que vous stockiez vos données de suggestions 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, mettez en forme les suggestions sous forme de lignes dans un tableau et présentez-les avec un Cursor.

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

Le système comprend plusieurs colonnes, mais seules deux d'entre elles sont obligatoires :

_ID: ID de ligne entier unique pour chaque suggestion. Le système en a besoin pour présenter les 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 sous le texte de la suggestion principale. Elle peut être nulle ou vide pour indiquer qu'il n'y a pas de texte secondaire.
SUGGEST_COLUMN_ICON_1: Chaîne URI de ressource, de contenu ou de fichier drawable. Si votre Cursor inclut cette colonne, toutes les suggestions sont fournies au format icône plus texte, avec l'icône drawable sur la gauche. Cette valeur peut être nulle ou égale à zéro pour indiquer qu'il n'y a pas d'icône dans cette ligne.
SUGGEST_COLUMN_ICON_2: Chaîne URI de ressource, de contenu ou de fichier drawable. Si votre Cursor inclut cette colonne, toutes les suggestions sont fournies au format icône plus texte, avec l'icône sur la droite. Cette valeur peut être nulle ou égale à zéro pour indiquer qu'aucune icône ne figure dans cette ligne.
SUGGEST_COLUMN_INTENT_ACTION: Chaîne d'action d'intent. Si cette colonne existe et contient une valeur dans la ligne donnée, l'action définie ici est utilisée pour former l'intention de la suggestion. Si l'élément n'est pas fourni, l'action est effectuée à partir du champ android:searchSuggestIntentAction de votre configuration 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 dans la ligne donnée, ces données sont utilisées pour former l'intention de la suggestion. Si l'élément n'est pas fourni, les données sont extraites du champ android:searchSuggestIntentData de votre configuration de recherche. Si aucune source n'est fournie, le champ de données de l'intention est défini sur "null". Si vos données sont identiques 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'accès à l'URI. Si cette colonne existe et contient une valeur dans la ligne donnée, "/" et cette valeur sont ajoutés au champ de données de l'intention. N'utilisez cette option que si le champ de données spécifié par l'attribut android:searchSuggestIntentData dans la configuration de recherche 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 dans une ligne donnée, il s'agit des données supplémentaires utilisées pour former l'intention de la suggestion. Si aucune valeur n'est fournie, le champ de données supplémentaires de l'intention est nul. Cette colonne permet aux suggestions de fournir des données supplémentaires incluses en tant qu'extra dans la clé EXTRA_DATA_KEY de l'intention.
SUGGEST_COLUMN_QUERY: Si cette colonne et cet élément existent dans la ligne donnée, il s'agit des données utilisées pour former la requête de la suggestion, incluses en tant qu'extra dans la clé QUERY de l'intention. Il est obligatoire si l'action de la suggestion est ACTION_SEARCH, mais facultatif dans le cas contraire.
SUGGEST_COLUMN_SHORTCUT_ID: Utilisé uniquement pour fournir 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. Les raccourcis sont généralement créés lorsque l'utilisateur appuie sur une suggestion dans le champ de recherche rapide. Si elle est manquante, le résultat est stocké sous forme de raccourci et n'est jamais actualisé. Si la valeur est définie sur SUGGEST_NEVER_MAKE_SHORTCUT, le résultat n'est pas stocké en tant que raccourci. Sinon, l'ID du raccourci est utilisé pour vérifier si une suggestion à jour est disponible à l'aide de SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Utilisé uniquement pour fournir des suggestions pour le champ de recherche rapide. Cette colonne indique qu'un spinner doit être affiché à la place d'une icône de SUGGEST_COLUMN_ICON_2 pendant que le raccourci de cette suggestion est actualisé dans la zone de recherche express.

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

Déclarer un intent pour les suggestions

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

Déclarer l'action d'intent

L'action d'intention la plus courante pour une suggestion personnalisée est ACTION_VIEW, qui convient lorsque vous souhaitez ouvrir quelque chose, comme la définition d'un mot, les coordonnées d'une personne ou une page Web. Toutefois, l'action d'intention 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 l'action de deux manières :

Utilisez l'attribut android:searchSuggestIntentAction de votre fichier de configuration de recherche pour définir l'action pour toutes les suggestions, comme indiqué 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 à effectuer pour chaque suggestion. Pour ce faire, ajoutez la colonne SUGGEST_COLUMN_INTENT_ACTION à votre tableau de suggestions et, pour chaque suggestion, indiquez 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 par défaut avec toutes les suggestions, puis remplacer cette action pour certaines suggestions en déclarant une action différente dans la colonne SUGGEST_COLUMN_INTENT_ACTION. Si vous n'incluez pas de valeur dans la colonne SUGGEST_COLUMN_INTENT_ACTION, l'intention fournie dans l'attribut android:searchSuggestIntentAction est utilisée.

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

Déclarer les données d'intention

Lorsque l'utilisateur sélectionne une suggestion, votre activité pouvant faire l'objet d'une recherche reçoit l'intent avec l'action que vous définissez (comme indiqué dans la section précédente). Toutefois, l'intent doit également contenir des données pour que votre activité puisse 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 jointes avec getData() ou getDataString().

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

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

Conseil : Il est généralement plus facile d'utiliser l'ID de ligne du tableau comme données d'intention, car il est toujours unique. Le moyen le plus simple de procéder consiste à utiliser le nom de colonne SUGGEST_COLUMN_INTENT_DATA comme alias pour la colonne d'ID de ligne.
Fragmente un URI de données en deux parties : la partie commune à toutes les suggestions et la partie propre à chaque suggestion. Placez ces parties respectivement dans l'attribut android:searchSuggestintentData de la configuration de recherche et dans la colonne SUGGEST_COLUMN_INTENT_DATA_ID de votre tableau de suggestions.
L'exemple suivant montre comment déclarer la partie de l'URI qui est commune à toutes les suggestions dans l'attribut android:searchSuggestIntentData de votre configuration 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 pour chaque suggestion (la partie unique) dans la colonne SUGGEST_COLUMN_INTENT_DATA_ID du tableau de suggestions. Lorsque l'utilisateur sélectionne une suggestion, le système prend 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 le Uri avec getData().

Ajouter des données

Si vous avez besoin d'exprimer plus d'informations avec votre intention, vous pouvez ajouter une autre colonne de tableau, 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 EXTRA_DATA_KEY du bundle d'extras de l'intention.

Gérer l'intent

Une fois que vous avez fourni des suggestions de recherche personnalisées avec des intents personnalisés, votre activité de recherche doit gérer ces intents lorsque l'utilisateur sélectionne une suggestion. Cela s'ajoute à la gestion de l'intention ACTION_SEARCH, que votre activité de recherche effectue déjà. 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 comportent un URI complet pointant vers l'élément suggéré, tel qu'il est 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 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é de recherche par nom pour répondre à l'intention 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 des suggestions à l'aide des commandes directionnelles, comme un trackball ou un pavé directionnel, le texte de la requête ne se met pas à 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. L'utilisateur peut ainsi voir la requête suggérée, puis sélectionner le champ de recherche et la modifier avant de l'envoyer.

Vous pouvez réécrire le texte de la requête de différentes manières :

Ajoutez l'attribut android:searchMode à votre configuration 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 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 les URL HTTP. N'utilisez pas de schémas d'URI internes pour réécrire la requête de cette manière.
Saisissez une chaîne de texte de requête unique dans la colonne SUGGEST_COLUMN_QUERY de votre tableau de suggestions. Si cette colonne est présente et contient une valeur pour la suggestion actuelle, elle est utilisée pour réécrire le texte de la requête et remplacer l'une des implémentations précédentes.

Exposer les suggestions de recherche au champ de recherche rapide

Une fois que vous avez configuré votre application pour qu'elle fournisse des suggestions de recherche personnalisées, il est très simple de les rendre disponibles dans le champ de recherche rapide accessible à tous. Il vous suffit de modifier votre configuration de recherche pour inclure android:includeInGlobalSearch avec la valeur "true".

Le seul cas où un travail supplémentaire est nécessaire est lorsque votre fournisseur de contenu exige 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 à la zone de recherche express à 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 du préfixe de chemin d'accès "/search_suggest_query" lorsque l'autorisation "android.permission.GLOBAL_SEARCH" existe. Cela 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, la zone de recherche express le lit par défaut.

Activer les suggestions sur un appareil

Par défaut, les applications ne sont pas activées pour fournir des suggestions dans la zone 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 la zone de recherche rapide en ouvrant Éléments pouvant faire l'objet d'une recherche, situé dans Paramètres > Recherche, et en activant votre application en tant qu'élément pouvant faire l'objet d'une recherche.

Chaque application disponible dans la zone de recherche rapide possède une entrée sur la page des paramètres Éléments pouvant faire l'objet d'une recherche. L'entrée inclut le nom de l'application et une brève description du contenu qui peut être recherché à partir de l'application et qui est disponible pour les suggestions dans le champ de recherche Express. Pour définir le texte de description de votre application pouvant faire l'objet d'une recherche, ajoutez l'attribut android:searchSettingsDescription à votre configuration de recherche, comme indiqué 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>

Rendez la chaîne pour android:searchSettingsDescription aussi concise que possible et indiquez 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. Il est important de fournir cette description pour que l'utilisateur sache quel type de suggestions sont proposées. Incluez toujours cet attribut lorsque android:includeInGlobalSearch est défini sur "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 le communiquer à vos utilisateurs. Par exemple, vous pouvez fournir une note la première fois qu'un utilisateur lance l'application, expliquant comment activer les suggestions de recherche pour la barre de recherche rapide.

Gérer les raccourcis des suggestions de la zone 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 de votre fournisseur de contenu afin de pouvoir y accéder rapidement sans avoir à interroger à nouveau votre fournisseur de contenu.

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

Demandez à la zone de recherche rapide d'interroger à nouveau votre fournisseur de contenu pour obtenir une nouvelle version du raccourci de suggestion.

Indiquez une valeur dans la colonne SUGGEST_COLUMN_SHORTCUT_ID pour que la suggestion soit réinterrogée afin d'obtenir une version actualisée chaque fois que le raccourci s'affiche. Le raccourci s'affiche rapidement avec les données les plus récentes disponibles 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 SUGGEST_URI_PATH_SHORTCUT au lieu de SUGGEST_URI_PATH_QUERY.

Le Cursor que vous renvoyez doit contenir une suggestion utilisant les mêmes colonnes que la suggestion d'origine ou être 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 (par exemple, une actualisation basée sur le réseau), vous pouvez également ajouter la colonne SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING à votre tableau de suggestions avec la valeur "true" pour afficher un indicateur de progression pour l'icône de droite jusqu'à ce que l'actualisation soit terminée. Toute valeur autre que "true" n'affiche pas le spinner de progression.
empêcher la suggestion d'être copiée 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. Cette étape n'est nécessaire que si vous ne souhaitez absolument pas que la suggestion copiée précédemment s'affiche. Si vous fournissez une valeur normale pour la colonne, le raccourci de suggestion ne s'affiche que jusqu'à ce que la requête d'actualisation renvoie un résultat.
Laisser le comportement par défaut du raccourci 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 jamais, vous n'avez pas besoin de la colonne SUGGEST_COLUMN_SHORTCUT_ID.

À propos du classement des suggestions du champ de recherche rapide

Une fois que vous avez mis les suggestions de recherche de votre application à la disposition de la barre de recherche rapide, le classement de la barre de recherche rapide détermine la façon dont les suggestions sont présentées à l'utilisateur pour une requête donnée. Cela peut dépendre du nombre d'autres applications qui ont 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 ne pouvons pas garantir le classement de vos suggestions ni leur affichage 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 fournies dans une position proéminente. Les applications qui fournissent des suggestions de mauvaise qualité sont plus susceptibles d'être classées plus bas ou de ne pas être affichées.

Ajouter des suggestions de recherche personnalisées Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Principes de base

Modifier la configuration indexable

Créer un fournisseur de contenu

Gérer la requête de suggestion

Obtenir la requête dans l'URI

Kotlin

Java

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

Créer un tableau de suggestions

Déclarer un intent pour les suggestions

Déclarer l'action d'intent

Déclarer les données d'intention

Ajouter des données

Gérer l'intent

Kotlin

Java

Réécrire le texte de la requête

Exposer les suggestions de recherche au champ de recherche rapide

Activer les suggestions sur un appareil

Gérer les raccourcis des suggestions de la zone de recherche rapide

À propos du classement des suggestions du champ de recherche rapide

Ajouter des suggestions de recherche personnalisées