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
![](https://developer.android.com/static/images/search/search-suggest-custom.png?authuser=6&hl=fr)
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
/puppiesLe 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'attributandroid: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.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'attributandroid: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 pasandroid: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.
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
.
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 deandroid: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 deandroid: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 estACTION_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 deSUGGEST_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 colonneSUGGEST_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é.
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 degetData()
ou degetDataString()
. - 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 colonneSUGGEST_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 deandroid:searchSuggestIntentData
, ajoute une barre oblique (/), puis ajoute la valeur correspondante de la colonneSUGGEST_COLUMN_INTENT_DATA_ID
pour former un URI de contenu complet. Vous pouvez ensuite récupérerUri
avecgetData()
.
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.
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 colonneSUGGEST_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 colonneSUGGEST_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 deSUGGEST_URI_PATH_SHORTCUT
(au lieu deSUGGEST_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 colonneSUGGEST_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.