Ajouter des suggestions de recherche personnalisées

Vous pouvez fournir des suggestions de recherche basées sur des requêtes de recherche récentes dans la boîte de dialogue de recherche ou le widget Recherche d'Android. Par exemple, si un utilisateur interroge "chiots", cette requête apparaît en tant que suggestion lorsqu'il saisit à nouveau la même requête. La figure 1 illustre un exemple de boîte de dialogue de recherche avec des suggestions de requête récentes.

Avant de commencer, implémentez la boîte de dialogue ou un widget de recherche pour les recherches de base dans votre application. Pour en savoir plus, consultez Créer une interface de recherche.

Principes de base

Figure 1 : Capture d'écran d'une boîte de dialogue de recherche avec des suggestions de requête récentes.

Les suggestions de requêtes récentes sont des recherches enregistrées. Lorsque l'utilisateur sélectionne une suggestion, votre activité consultable reçoit un intent ACTION_SEARCH avec la suggestion en tant que requête de recherche déjà gérée par votre activité dans l'index de recherche.

Pour fournir des suggestions de requêtes récentes, vous devez:

  • Implémentez une activité incluse dans l'index de recherche.
  • Créez un fournisseur de contenu qui étend SearchRecentSuggestionsProvider et déclarez-le dans le fichier manifeste de votre application.
  • Modifiez la configuration interrogeable avec les informations sur le fournisseur de contenu qui fournit des suggestions de recherche.
  • Enregistrez des requêtes sur votre fournisseur de contenu chaque fois qu'une recherche est exécutée.

Tout comme le système Android affiche la boîte de dialogue de recherche, il affiche les suggestions de recherche sous la boîte de dialogue ou le widget Recherche. Vous indiquez la source à partir de laquelle le système récupère les suggestions.

Lorsque le système détermine que votre activité peut faire l'objet d'une recherche et fournit des suggestions de recherche, voici ce qui se produit lorsque l'utilisateur saisit une requête:

  1. Le système prend le texte de la requête de recherche (quel que soit le début de la saisie) et l'envoie au fournisseur de contenu qui contient vos suggestions.
  2. Votre fournisseur de contenu renvoie un Cursor qui pointe vers toutes les suggestions correspondant au texte de la requête de recherche.
  3. Le système affiche la liste des suggestions fournies par Cursor.

Une fois les suggestions de requêtes récentes affichées, voici ce qui peut se produire:

  • Si l'utilisateur saisit une autre clé ou modifie la requête, les étapes précédentes sont répétées et la liste de suggestions est mise à jour.
  • 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 ACTION_SEARCH est envoyé à votre activité de recherche en utilisant le texte suggéré comme requête.

La classe SearchRecentSuggestionsProvider que vous étendez pour votre fournisseur de contenu effectue automatiquement le travail des étapes précédentes, et nécessite donc peu de code à écrire.

Créer un fournisseur de contenu

Le fournisseur de contenu dont vous avez besoin pour les suggestions de requête récentes est une implémentation de SearchRecentSuggestionsProvider. Cette classe fait tout pour vous. Il vous suffit d'écrire un constructeur de classe qui exécute une ligne de code.

Par exemple, voici une implémentation complète d'un fournisseur de contenu pour des suggestions de requête récentes:

Kotlin

class MySuggestionProvider : SearchRecentSuggestionsProvider() {
    init {
        setupSuggestions(AUTHORITY, MODE)
    }

    companion object {
        const val AUTHORITY = "com.example.MySuggestionProvider"
        const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
    }
}

Java

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
    public final static String AUTHORITY = "com.example.MySuggestionProvider";
    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {
        setupSuggestions(AUTHORITY, MODE);
    }
}

L'appel à setupSuggestions() transmet le nom de l'autorité de recherche et un mode de base de données. L'autorité de recherche peut être n'importe quelle chaîne unique. Toutefois, la bonne pratique consiste à utiliser un nom complet pour votre fournisseur de contenu, tel que le nom du package suivi du nom de classe du fournisseur. Par exemple, "com.example.MySuggestionProvider".

Le mode Base de données doit inclure DATABASE_MODE_QUERIES et peut éventuellement inclure DATABASE_MODE_2LINES, qui ajoute une colonne à la table des suggestions afin que vous puissiez fournir une deuxième ligne de texte avec chaque suggestion. Si vous souhaitez fournir deux lignes dans chaque suggestion, consultez l'exemple suivant:

Kotlin

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

Java

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

Déclarez le fournisseur de contenu dans le fichier manifeste de votre application avec la même chaîne d'autorité que celle utilisée dans votre classe SearchRecentSuggestionsProvider et dans la configuration consultable. Par exemple :

<application>
    <provider android:name=".MySuggestionProvider"
              android:authorities="com.example.MySuggestionProvider" />
    ...
</application>

Modifier la configuration interrogeable

Pour configurer le système afin qu'il utilise votre fournisseur de suggestions, ajoutez les attributs android:searchSuggestAuthority et android:searchSuggestSelection à l'élément <searchable> de votre fichier de configuration inclus dans l'index de recherche. Par exemple :

<?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.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

La valeur de android:searchSuggestAuthority doit être un nom complet de votre fournisseur de contenu qui correspond exactement à l'autorité utilisée dans le fournisseur de contenu, comme "com.example.MySuggestionProvider" dans les exemples précédents.

La valeur de android:searchSuggestSelection doit être un seul point d'interrogation précédé d'un espace: " ?". Il s'agit d'un espace réservé pour l'argument de sélection SQLite. Il est automatiquement remplacé par le texte de requête saisi par l'utilisateur.

Enregistrer les requêtes

Pour renseigner votre collection de requêtes récentes, ajoutez chaque requête reçue par votre activité interrogeable à votre SearchRecentSuggestionsProvider. Pour ce faire, créez une instance de SearchRecentSuggestions et appelez saveRecentQuery() chaque fois que votre activité dans l'index de recherche reçoit une requête. Par exemple, voici comment enregistrer la requête lors de la méthode onCreate() de votre activité:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                    .saveRecentQuery(query, null)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent  = getIntent();

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
        suggestions.saveRecentQuery(query, null);
    }
}

Le constructeur SearchRecentSuggestionsProvider nécessite la même autorité et le même mode de base de données que ceux déclarés par votre fournisseur de contenu.

La méthode saveRecentQuery() utilise la chaîne de requête de recherche comme premier paramètre et, éventuellement, une deuxième chaîne à inclure comme deuxième ligne de la suggestion ou une valeur nulle. Le deuxième paramètre n'est utilisé que si vous activez le mode sur deux lignes pour les suggestions de recherche avec DATABASE_MODE_2LINES. Si vous activez le mode sur deux lignes, le texte de la requête correspond à la deuxième ligne lorsque le système recherche des suggestions correspondantes.

Effacer les données des suggestions

Pour protéger la confidentialité de l'utilisateur, fournissez-lui toujours un moyen d'effacer les suggestions de requête récentes. Pour effacer l'historique des requêtes, appelez clearHistory(). Par exemple :

Kotlin

SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
        .clearHistory()

Java

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
        HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
suggestions.clearHistory();

Pour ce faire, utilisez l'élément de menu, l'élément de préférence ou le bouton "Effacer l'historique des recherches". Afficher une boîte de dialogue de confirmation pour confirmer que l'utilisateur souhaite supprimer son historique des recherches.