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

Créer une interface de recherche

Lorsque vous êtes prêt à ajouter une fonctionnalité de recherche à votre application, Android vous aide à implémenter l'interface utilisateur avec une boîte de dialogue de recherche qui s'affiche en haut de la fenêtre de l'activité ou un widget de recherche que vous pouvez insérer dans votre mise en page. La boîte de dialogue de recherche et le widget peuvent transmettre la requête de recherche de l'utilisateur à une activité spécifique dans votre application. Ainsi, l'utilisateur peut lancer une recherche à partir de n'importe quelle activité où la boîte de dialogue ou le widget de recherche est disponible, et le système lance l'activité appropriée pour effectuer la recherche et présenter les résultats.

Les autres fonctionnalités disponibles pour la boîte de dialogue et le widget de recherche sont les suivantes:

Recherche vocale
Suggestions de recherche basées sur les requêtes récentes
Suggestions de recherche correspondant aux résultats réels dans les données de votre application

Ce document explique comment configurer votre application pour fournir une interface de recherche avec l'aide du système Android afin de fournir des requêtes de recherche à l'aide de la boîte de dialogue ou du widget Recherche.

Ressources associées :

Icônes Material Design

Principes de base

Avant de commencer, indiquez si vous souhaitez implémenter votre interface de recherche à l'aide de la boîte de dialogue ou du widget Recherche. Ils offrent les mêmes fonctionnalités de recherche, mais de manière légèrement différente:

La boîte de dialogue de recherche est un composant d'interface utilisateur contrôlé par le système Android. Lorsqu'elle est activée par l'utilisateur, la boîte de dialogue de recherche apparaît en haut de l'activité.
Le système Android contrôle tous les événements de la boîte de dialogue de recherche. Lorsque l'utilisateur envoie une requête, le système la transmet à l'activité que vous spécifiez pour gérer les recherches. La boîte de dialogue peut également fournir des suggestions de recherche pendant que l'utilisateur saisit du texte.
Le widget Recherche est une instance de SearchView que vous pouvez placer n'importe où dans votre mise en page. Par défaut, le widget Recherche se comporte comme un widget EditText standard et ne fait rien, mais vous pouvez le configurer de sorte que le système Android gère tous les événements d'entrée, envoie les requêtes à l'activité appropriée et fournisse des suggestions de recherche, tout comme la boîte de dialogue de recherche.

Remarque:Ce document explique comment intégrer le widget Recherche au système pour l'implémentation de la recherche assistée. Toutefois, vous pouvez également gérer vous-même toutes les entrées utilisateur dans le widget de recherche à l'aide de différentes méthodes de rappel et d'écouteurs. Si vous souhaitez gérer vous-même les entrées utilisateur, lisez le document de référence sur SearchView et ses interfaces imbriquées.

Lorsque l'utilisateur effectue une recherche à partir de la boîte de dialogue de recherche ou d'un widget de recherche, le système crée un Intent et y stocke la requête de l'utilisateur. Le système lance ensuite l'activité que vous déclarez pour gérer les recherches (l'activité consultable) et lui envoie l'intent. Pour configurer votre application pour ce type de recherche assistée, vous avez besoin des éléments suivants:

Une configuration de recherche: Fichier XML qui permet de configurer certains paramètres de la boîte de dialogue ou du widget de recherche. Il inclut des paramètres pour des fonctionnalités telles que la recherche vocale, les suggestions de recherche et les indications du champ de recherche.
Une activité interrogeable: Le Activity qui reçoit la requête de recherche, recherche vos données et affiche les résultats de la recherche.
Une interface de recherche, fournie par l'un des éléments suivants:

Le reste de ce document explique comment créer la configuration de recherche et l'activité de recherche, et comment implémenter une interface de recherche avec la boîte de dialogue de recherche ou le widget Recherche.

Créer une configuration incluse dans l'index de recherche

Vous avez tout d'abord besoin d'un fichier XML appelé configuration de recherche. Il configure certains aspects de l'interface utilisateur de la boîte de dialogue ou du widget de recherche, et définit le comportement de fonctionnalités telles que les suggestions et la recherche vocale. Ce fichier est traditionnellement nommé searchable.xml et doit être enregistré dans le répertoire du projet res/xml/.

Remarque:Le système utilise ce fichier pour instancier un objet SearchableInfo. Vous ne pouvez pas créer cet objet vous-même au moment de l'exécution. Vous devez déclarer la configuration de recherche au format XML.

Le fichier de configuration de la recherche doit inclure l'élément <searchable> en tant que nœud racine et spécifier un ou plusieurs attributs, 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" >
</searchable>

L'attribut android:label est le seul attribut obligatoire. Elle pointe vers une ressource de chaîne, qui doit être le nom de l'application. Ce libellé n'est pas visible par l'utilisateur tant que vous n'avez pas activé les suggestions de recherche pour le champ de recherche rapide. Il apparaît alors dans la liste des éléments inclus dans l'index de recherche des paramètres système.

Bien que ce ne soit pas obligatoire, nous vous recommandons de toujours inclure l'attribut android:hint, qui fournit une chaîne d'indication dans le champ de recherche avant que les utilisateurs ne saisissent une requête. Cette suggestion est importante, car elle fournit des indices importants aux utilisateurs sur ce qu'ils peuvent rechercher.

Conseil:Pour des raisons de cohérence avec les autres applications Android, mettez en forme la chaîne android:hint sous la forme "Rechercher <content-or-product>". Par exemple, "Rechercher des titres et des artistes" ou "Rechercher sur YouTube".

L'élément <searchable> accepte plusieurs autres attributs. Cependant, vous n'avez pas besoin de la plupart des attributs tant que vous n'avez pas ajouté de fonctionnalités telles que les suggestions de recherche et la recherche vocale. Pour en savoir plus sur le fichier de configuration de recherche, consultez la documentation de référence sur la configuration de la recherche.

Créer une activité incluse dans l'index de recherche

Une activité incluse dans l'index de recherche correspond au Activity de votre application qui effectue des recherches basées sur une chaîne de requête et présente les résultats.

Lorsque l'utilisateur effectue une recherche dans la boîte de dialogue ou le widget de recherche, le système lance votre activité interrogeable et lui envoie la requête de recherche dans un Intent avec l'action ACTION_SEARCH. Votre activité dans l'index de recherche récupère la requête de l'extra QUERY de l'intent, puis recherche vos données et présente les résultats.

Étant donné que vous pouvez inclure la boîte de dialogue ou le widget de recherche dans toute autre activité de votre application, le système doit savoir quelle activité correspond à votre activité de recherche afin de pouvoir diffuser correctement la requête de recherche. Commencez par déclarer l'activité incluse dans l'index de recherche dans le fichier manifeste Android.

Déclarer une activité interrogeable

Si vous n'en avez pas encore, créez un Activity qui effectue des recherches et présente des résultats. Vous n'avez pas encore besoin d'implémenter la fonctionnalité de recherche. Il vous suffit de créer une activité que vous pouvez déclarer dans le fichier manifeste. Dans l'élément <activity> du fichier manifeste, procédez comme suit:

Déclarez l'activité pour accepter l'intent ACTION_SEARCH dans un élément <intent-filter>.
Spécifiez la configuration de recherche à utiliser dans un élément <meta-data>.

Ce processus est illustré dans l'exemple suivant :

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

L'élément <meta-data> doit inclure l'attribut android:name avec la valeur "android.app.searchable" et l'attribut android:resource avec une référence au fichier de configuration inclus dans l'index de recherche. Dans l'exemple précédent, il fait référence au fichier res/xml/searchable.xml.

Remarque:<intent-filter> n'a pas besoin d'un <category> avec la valeur DEFAULT (que vous voyez généralement dans les éléments <activity>), car le système transmet explicitement l'intent ACTION_SEARCH à votre activité interrogeable à l'aide de son nom de composant.

Effectuer une recherche

Après avoir déclaré votre activité interrogeable dans le fichier manifeste, procédez comme suit pour effectuer une recherche dans votre activité interrogeable:

Recevez la requête.
Effectuez des recherches dans vos données.
Présentez les résultats.

Recevoir la requête

Lorsqu'un utilisateur effectue une recherche à partir de la boîte de dialogue ou du widget de recherche, le système démarre votre activité consultable et lui envoie un intent ACTION_SEARCH. Cet intent transmet la requête de recherche dans l'extra de chaîne QUERY. Recherchez cet intent au début de l'activité et extrayez la chaîne. Par exemple, voici comment obtenir la requête de recherche lorsque votre activité interrogeable commence:

Kotlin

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

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

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

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

La chaîne QUERY est toujours incluse avec l'intent ACTION_SEARCH. Dans l'exemple précédent, la requête est récupérée et transmise à une méthode doMySearch() locale où l'opération de recherche réelle est effectuée.

Rechercher dans vos données

Le processus de stockage et de recherche de vos données est propre à votre application. Vous pouvez stocker et rechercher vos données de différentes manières, et ce document ne vous montre pas comment faire. Réfléchissez à la manière dont vous stockez et recherchez vos données en fonction de vos besoins et de leur format. Voici quelques conseils que vous pouvez appliquer:

Si vos données sont stockées dans une base de données SQLite sur l'appareil, effectuer une recherche en texte intégral à l'aide de FTS3 plutôt qu'une requête LIKE peut fournir une recherche plus efficace dans les données textuelles et produire des résultats beaucoup plus rapidement. Consultez sqlite.org pour en savoir plus sur FTS3 et sur la classe SQLiteDatabase pour en savoir plus sur SQLite sur Android.
Si vos données sont stockées en ligne, la connexion de données de l'utilisateur peut entraver les performances de recherche perçues. Vous pouvez afficher un indicateur de progression jusqu'à ce que la recherche soit renvoyée. Consultez android.net pour en savoir plus sur les API réseau et ProgressBar pour savoir comment afficher un indicateur de progression.

Présenter les résultats

Peu importe l'emplacement de vos données et la manière dont vous les effectuez, nous vous recommandons de renvoyer les résultats de recherche à votre activité consultable avec un Adapter. De cette façon, vous pouvez présenter tous les résultats de la recherche dans un RecyclerView. Si les données proviennent d'une requête de base de données SQLite, vous pouvez appliquer vos résultats à un RecyclerView à l'aide d'un CursorAdapter. Si vos données sont disponibles dans un format différent, vous pouvez créer une extension de BaseAdapter.

Une Adapter lie chaque élément d'un ensemble de données à un objet View. Lorsque le Adapter est appliqué à un RecyclerView, chaque élément de données est inséré en tant que vue individuelle dans la liste. Adapter n'est qu'une interface. Par conséquent, les implémentations telles que CursorAdapter, pour la liaison de données à partir d'un Cursor, sont nécessaires. Si aucune des implémentations existantes ne fonctionne pour vos données, vous pouvez implémenter la vôtre à partir de BaseAdapter.

Utiliser la boîte de dialogue de recherche

La boîte de dialogue de recherche fournit un champ de recherche flottant en haut de l'écran, avec l'icône d'application à gauche. La boîte de dialogue de recherche peut fournir des suggestions de recherche à mesure que l'utilisateur saisit du texte. Lorsque l'utilisateur effectue une recherche, le système envoie la requête à une activité interrogeable qui effectue la recherche.

Par défaut, la boîte de dialogue de recherche est toujours masquée jusqu'à ce que l'utilisateur l'active. Votre application peut activer la boîte de dialogue de recherche en appelant onSearchRequested(). Toutefois, cette méthode ne fonctionne que lorsque vous activez la boîte de dialogue de recherche pour l'activité.

Pour permettre à la boîte de dialogue de recherche d'effectuer des recherches, indiquez au système quelle activité de recherche doit recevoir des requêtes de recherche à partir de la boîte de dialogue de recherche. Par exemple, dans la section précédente sur la création d'une activité consultable, une activité incluse dans l'index de recherche nommée SearchableActivity est créée. Si vous souhaitez qu'une activité distincte, telle que OtherActivity, affiche la boîte de dialogue de recherche et envoie les recherches à SearchableActivity, déclarez dans le fichier manifeste que SearchableActivity est l'activité consultable à utiliser pour la boîte de dialogue de recherche dans OtherActivity.

Pour déclarer l'activité consultable pour la boîte de dialogue de recherche d'une activité, ajoutez un élément <meta-data> dans l'élément <activity> de l'activité correspondante. L'élément <meta-data> doit inclure l'attribut android:value qui spécifie le nom de classe de l'activité de recherche et l'attribut android:name avec la valeur "android.app.default_searchable".

Par exemple, voici la déclaration d'une activité interrogeable, SearchableActivity, et d'une autre activité, OtherActivity, qui utilise SearchableActivity pour effectuer des recherches exécutées à partir de sa boîte de dialogue de recherche:

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

Étant donné que OtherActivity inclut désormais un élément <meta-data> pour déclarer l'activité interrogeable à utiliser pour les recherches, l'activité active la boîte de dialogue de recherche. Bien que l'utilisateur se trouve dans cette activité, la méthode onSearchRequested() active la boîte de dialogue de recherche. Lorsque l'utilisateur exécute la recherche, le système lance SearchableActivity et lui envoie l'intent ACTION_SEARCH.

Remarque:L'activité incluse dans l'index de recherche fournit la boîte de dialogue de recherche par défaut. Vous n'avez donc pas besoin d'ajouter cette déclaration à SearchableActivity.

Si vous souhaitez que chaque activité de votre application fournisse la boîte de dialogue de recherche, insérez l'élément <meta-data> précédent en tant qu'enfant de l'élément <application>, au lieu de chaque <activity>. De cette manière, chaque activité hérite de la valeur, affiche la boîte de dialogue de recherche et envoie les recherches à la même activité interrogeable. Si vous avez plusieurs activités incluses dans l'index de recherche, vous pouvez remplacer l'activité par défaut en plaçant une déclaration <meta-data> différente à l'intérieur de chaque activité.

La boîte de dialogue de recherche étant désormais activée pour vos activités, votre application est prête à effectuer des recherches.

Appeler la boîte de dialogue de recherche

Bien que certains appareils fournissent un bouton de recherche dédié, son comportement peut varier d'un appareil à l'autre. Par ailleurs, de nombreux appareils ne fournissent pas de bouton de recherche. Ainsi, lorsque vous utilisez la boîte de dialogue de recherche, vous devez fournir un bouton de recherche dans votre interface utilisateur qui active la boîte de dialogue de recherche en appelant onSearchRequested().

Par exemple, ajoutez un bouton de recherche dans votre menu d'options ou votre mise en page d'interface utilisateur qui appelle onSearchRequested().

Vous pouvez également activer la fonctionnalité "Saisir pour rechercher", qui active la boîte de dialogue de recherche lorsque l'utilisateur commence à saisir du texte au clavier. Les combinaisons de touches sont insérées dans la boîte de dialogue de recherche. Vous pouvez activer la recherche par type dans votre activité en appelant setDefaultKeyMode ou DEFAULT_KEYS_SEARCH_LOCAL au cours de la méthode onCreate() de votre activité.

Impact de la boîte de dialogue de recherche sur le cycle de vie de votre activité

La boîte de dialogue de recherche est un élément Dialog qui flotte en haut de l'écran. Cela ne modifie pas la pile d'activités. Par conséquent, lorsque la boîte de dialogue de recherche apparaît, aucune méthode de cycle de vie (telle que onPause()) n'est appelée. Votre activité perd la sélection d'entrées, car celles-ci sont transmises à la boîte de dialogue de recherche.

Si vous souhaitez être averti lorsque la boîte de dialogue de recherche est activée, remplacez la méthode onSearchRequested(). Lorsque le système appelle cette méthode, cela indique que votre activité perd le ciblage d'entrée dans la boîte de dialogue de recherche. Vous pouvez donc effectuer toutes les tâches adaptées à l'événement, telles que la mise en pause d'un jeu. À moins de transmettre des données de contexte de recherche (abordées dans une autre section de ce document), terminez la méthode en appelant l'implémentation de la super-classe:

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

Si l'utilisateur annule la recherche en appuyant sur le bouton "Retour", la boîte de dialogue de recherche se ferme et l'activité retrouve le focus d'entrée. Vous pouvez demander à recevoir une notification lorsque la boîte de dialogue de recherche est fermée avec setOnDismissListener(), setOnCancelListener() ou les deux. Il vous suffit d'enregistrer le OnDismissListener, car il est appelé à chaque fois que la boîte de dialogue de recherche se ferme. OnCancelListener ne concerne que les événements dans lesquels l'utilisateur quitte explicitement la boîte de dialogue de recherche. Il n'est donc pas appelé lorsqu'une recherche est exécutée. Lorsque la recherche est exécutée, la boîte de dialogue de recherche disparaît automatiquement.

Si l'activité actuelle n'est pas l'activité incluse dans l'index de recherche, les événements de cycle de vie de l'activité normale sont déclenchés lorsque l'utilisateur effectue une recherche. L'activité actuelle reçoit onPause(), comme décrit dans la section Présentation des activités. Toutefois, si l'activité en cours est l'activité incluse dans l'index de recherche, l'une des deux situations suivantes se produit:

Par défaut, l'activité interrogeable reçoit l'intent ACTION_SEARCH avec un appel à onCreate(), et une nouvelle instance de l'activité est placée en haut de la pile d'activités. Il existe désormais deux instances de votre activité consultable dans la pile d'activités. Par conséquent, appuyer sur le bouton "Retour" vous ramène à l'instance précédente de l'activité incluse dans l'index de recherche au lieu de la quitter.

Si vous définissez android:launchMode sur "singleTop", l'activité interrogeable reçoit l'intent ACTION_SEARCH avec un appel à onNewIntent(Intent), transmettant le nouvel intent ACTION_SEARCH. Par exemple, voici comment vous pouvez gérer le cas où le mode de lancement de l'activité consultable est "singleTop":

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)
    handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    handleIntent(intent)
}

private fun handleIntent(intent: Intent) {
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);
    handleIntent(getIntent());
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    handleIntent(intent);
}

private void handleIntent(Intent intent) {
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

Par rapport à l'exemple de code de la section sur l'exécution d'une recherche, tout le code permettant de gérer l'intent de recherche se trouve maintenant dans la méthode handleIntent(), afin que onCreate() et onNewIntent() puissent l'exécuter.

Lorsque le système appelle onNewIntent(Intent), l'activité n'est pas redémarrée. Par conséquent, la méthode getIntent() renvoie le même intent que celui reçu avec onCreate(). C'est pourquoi vous devez appeler setIntent(Intent) dans onNewIntent(Intent): afin que l'intent enregistré par l'activité soit mis à jour au cas où vous appeleriez getIntent() à l'avenir.

Le deuxième scénario, qui utilise le mode de lancement "singleTop", est généralement préférable, car une fois la recherche effectuée, l'utilisateur peut effectuer des recherches supplémentaires. Il est donc préférable que votre application ne crée pas plusieurs instances de l'activité consultable. Nous vous recommandons de définir votre activité interrogeable sur le mode de lancement "singleTop" dans le fichier manifeste de l'application, comme illustré dans l'exemple suivant:

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

Transmettre des données de contexte de recherche

Dans certains cas, vous pouvez affiner la requête de recherche dans l'activité interrogeable pour chaque recherche effectuée. Toutefois, si vous souhaitez affiner vos critères de recherche en fonction de l'activité à partir de laquelle l'utilisateur effectue une recherche, vous pouvez fournir des données supplémentaires dans l'intent que le système envoie à votre activité interrogeable. Vous pouvez transmettre les données supplémentaires dans APP_DATA Bundle, qui est inclus dans l'intent ACTION_SEARCH.

Pour transmettre ce type de données à votre activité interrogeable, remplacez la méthode onSearchRequested() pour l'activité à partir de laquelle l'utilisateur peut effectuer une recherche, créez un Bundle avec les données supplémentaires, puis appelez startSearch() pour activer la boîte de dialogue de recherche. Par exemple :

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

Le renvoi de la valeur "true" indique que vous gérez correctement cet événement de rappel et que vous appelez startSearch() pour activer la boîte de dialogue de recherche. Une fois que l'utilisateur a envoyé une requête, celle-ci est transmise à votre activité interrogeable avec les données que vous ajoutez. Vous pouvez extraire les données supplémentaires de APP_DATA Bundle pour affiner la recherche, comme illustré dans l'exemple suivant:

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

Attention:N'appelez jamais la méthode startSearch() en dehors de la méthode de rappel onSearchRequested(). Pour activer la boîte de dialogue de recherche dans votre activité, appelez toujours onSearchRequested(). Sinon, onSearchRequested() n'est pas appelé et les personnalisations, telles que l'ajout de appData dans l'exemple précédent, ne sont pas prises en compte.

Utiliser le widget Recherche

Image montrant une vue de recherche dans la barre supérieure de l'application

Figure 1 : Le widget SearchView en tant que vue d'action dans la barre d'application.

Le widget Recherche offre les mêmes fonctionnalités que la boîte de dialogue de recherche. Elle lance l'activité appropriée lorsque l'utilisateur effectue une recherche et peut fournir des suggestions de recherche et effectuer une recherche vocale. Si vous ne pouvez pas placer le widget de recherche dans la barre d'application, vous pouvez le placer quelque part dans la mise en page de votre activité.

Configurer le widget Recherche

Après avoir créé une configuration de recherche et une activité de recherche, activez la recherche assistée pour chaque SearchView en appelant setSearchableInfo() et en lui transmettant l'objet SearchableInfo qui représente votre configuration d'index de recherche.

Vous pouvez obtenir une référence à SearchableInfo en appelant getSearchableInfo() sur SearchManager.

Par exemple, si vous utilisez un SearchView comme vue d'action dans la barre d'application, activez le widget lors du rappel onCreateOptionsMenu(), comme illustré dans l'exemple suivant:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

Le widget Recherche est maintenant configuré, et le système envoie des requêtes de recherche à votre activité interrogeable. Vous pouvez également activer les suggestions de recherche pour le widget Recherche.

Remarque:Si vous souhaitez gérer vous-même toutes les entrées utilisateur, vous pouvez utiliser certaines méthodes de rappel et certains écouteurs d'événements. Pour en savoir plus, consultez la documentation de référence sur SearchView et ses interfaces imbriquées.

Pour en savoir plus sur les vues d'action dans la barre d'application, consultez Utiliser des vues d'action et des fournisseurs d'action.

Autres fonctionnalités du widget Recherche

Le widget SearchView fournit quelques fonctionnalités supplémentaires que vous pourriez souhaiter:

Un bouton "Envoyer": Par défaut, il n'y a pas de bouton pour envoyer une requête de recherche. L'utilisateur doit donc appuyer sur la touche Entrée du clavier pour lancer une recherche. Vous pouvez ajouter un bouton "Envoyer" en appelant setSubmitButtonEnabled(true).
Affinement des requêtes pour les suggestions de recherche: Lorsque vous activez les suggestions de recherche, vous vous attendez généralement à ce que les utilisateurs sélectionnent une suggestion, mais ils peuvent également vouloir affiner la requête de recherche suggérée. Vous pouvez ajouter un bouton à côté de chaque suggestion qui insère la suggestion dans le champ de recherche afin que l'utilisateur puisse affiner la recherche en appelant setQueryRefinementEnabled(true).
Possibilité d'activer/de désactiver la visibilité du champ de recherche: Par défaut, le widget Recherche est "iconifié". Cela signifie qu'il n'est représenté que par une icône de recherche, à savoir une loupe. Elle se développe pour afficher le champ de recherche lorsque l'utilisateur appuie sur l'icône. Comme indiqué dans l'exemple précédent, vous pouvez afficher le champ de recherche par défaut en appelant setIconifiedByDefault(false). Vous pouvez également modifier l'apparence du widget Recherche en appelant setIconified().

La classe SearchView comporte plusieurs autres API qui vous permettent de personnaliser le widget Recherche. Cependant, la plupart d'entre elles ne sont utilisées que lorsque vous gérez vous-même toutes les entrées utilisateur, au lieu d'utiliser le système Android pour diffuser des requêtes de recherche et afficher des suggestions de recherche.

Utiliser à la fois le widget et la boîte de dialogue

Si vous insérez le widget Recherche dans la barre d'application en tant que vue d'action et que vous activez son affichage dans la barre d'application s'il y a de la place (en définissant android:showAsAction="ifRoom"), le widget Recherche peut ne pas apparaître en tant que vue d'action. À la place, un élément de menu peut apparaître dans le menu à développer. Par exemple, lorsque votre application s'exécute sur un écran de petite taille, il est possible qu'il n'y ait pas assez d'espace dans la barre d'application pour afficher le widget de recherche avec d'autres actions ou éléments de navigation. L'élément de menu apparaît donc dans le menu à développer. Lorsqu'il est placé dans le menu à développer, l'élément fonctionne comme un élément de menu ordinaire et n'affiche pas la vue des actions, c'est-à-dire le widget Recherche.

Pour gérer cette situation, l'élément de menu auquel vous associez le widget de recherche doit activer la boîte de dialogue de recherche lorsque l'utilisateur la sélectionne dans le menu à développer. Pour ce faire, implémentez onOptionsItemSelected() pour gérer l'élément de menu "Rechercher" et ouvrez la boîte de dialogue de recherche en appelant onSearchRequested().

Pour en savoir plus sur le fonctionnement des éléments de la barre d'application et sur la manière de gérer cette situation, consultez Ajouter la barre d'application.

Ajouter la recherche vocale

Vous pouvez ajouter la fonctionnalité de recherche vocale à votre boîte de dialogue ou à votre widget de recherche en ajoutant l'attribut android:voiceSearchMode à votre configuration consultable. Cela permet d'ajouter un bouton de recherche vocale qui lance une invite vocale. Lorsque l'utilisateur a fini de parler, la requête de recherche transcrite est envoyée à votre activité d'index de recherche.

Ce processus est 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/search_label"
    android:hint="@string/search_hint"
    android:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

La valeur showVoiceSearchButton est requise pour activer la recherche vocale. La deuxième valeur, launchRecognizer, indique que le bouton de recherche vocale doit lancer un programme de reconnaissance qui renvoie le texte transcrit à l'activité interrogeable.

Vous pouvez fournir des attributs supplémentaires pour spécifier le comportement de la recherche vocale, tels que la langue attendue et le nombre maximal de résultats à renvoyer. Pour en savoir plus sur les attributs disponibles, consultez la documentation de référence sur la configuration de la recherche.

Ajouter des suggestions de recherche

La boîte de dialogue de recherche et le widget Recherche peuvent fournir des suggestions de recherche à mesure que l'utilisateur saisit du texte, avec l'aide du système Android. Le système gère la liste des suggestions et l'événement lorsque l'utilisateur en sélectionne une.

Vous pouvez fournir deux types de suggestions de recherche:

Suggestions pour les requêtes récentes: Ces suggestions sont des mots que l'utilisateur a précédemment utilisés comme requêtes de recherche dans votre application. Pour en savoir plus, consultez Ajouter des suggestions de recherche personnalisées.
Suggestions de recherche personnalisées: Il s'agit de suggestions de recherche que vous fournissez à partir de votre propre source de données afin d'aider les utilisateurs à sélectionner immédiatement l'orthographe ou l'élément qu'ils recherchent. Pour en savoir plus, consultez Ajouter des suggestions de recherche personnalisées.