Créer une interface de recherche

Essayer Compose

Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment ajouter une fonctionnalité de recherche dans Compose.

Barre 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 d'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 tous deux transmettre la requête de recherche de l'utilisateur à une activité spécifique de 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 sont disponibles, et le système démarre l'activité appropriée pour effectuer la recherche et présenter les résultats.

Voici d'autres fonctionnalités disponibles pour la boîte de dialogue et le widget de recherche :

• 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 assistée par le système Android afin de fournir des requêtes de recherche, à l'aide de la boîte de dialogue de recherche ou du widget de recherche.

Ressources associées :

• Icônes Material Design

Principes de base

Avant de commencer, choisissez si vous souhaitez implémenter votre interface de recherche à l'aide de la boîte de dialogue de recherche ou du widget de recherche. Elles 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. Lorsque l'utilisateur l'active, la boîte de dialogue de recherche s'affiche 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 de 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. Toutefois, vous pouvez le configurer pour que le système Android gère tous les événements d'entrée, transmette les requêtes à l'activité appropriée et fournisse des suggestions de recherche, comme la boîte de dialogue de recherche.

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 démarre ensuite l'activité que vous déclarez pour gérer les recherches (l'activité "searchable") et lui transmet 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 configure certains paramètres de la boîte de dialogue ou du widget de recherche. Il inclut les paramètres de fonctionnalités telles que la recherche vocale, les suggestions de recherche et le texte d'aide pour le champ de recherche.

Une activité pouvant faire l'objet d'une recherche

Le Activity qui reçoit la requête de recherche, recherche dans vos données et affiche les résultats de recherche.

Une interface de recherche fournie par l'un des éléments suivants :

Boîte de dialogue de recherche

 Par défaut, la boîte de dialogue de recherche est masquée. Il s'affiche en haut de l'écran lorsque vous appelez onSearchRequested() lorsque l'utilisateur appuie sur votre bouton Rechercher.

Un widget SearchView

L'utilisation du widget de recherche vous permet de placer le champ de recherche n'importe où dans votre activité, y compris en tant qu'affichage d'action dans la barre d'application.

Le reste de ce document vous explique comment créer la configuration de recherche et l'activité pouvant faire l'objet d'une 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 indexable

La première chose dont vous avez besoin est 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/.

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

L'attribut android:label est le seul attribut obligatoire. Il 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 la barre de recherche rapide. À ce moment-là, le libellé est visible dans la liste des éléments pouvant faire l'objet d'une recherche dans les paramètres système.

Bien que cela ne soit pas obligatoire, nous vous recommandons d'inclure systématiquement l'attribut android:hint, qui fournit une chaîne d'aide dans le champ de recherche avant que les utilisateurs saisissent une requête. L'indice est important, car il fournit aux utilisateurs des indices importants sur ce qu'ils peuvent rechercher.

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

Créer une activité pouvant être recherchée

Une activité de recherche est l'Activity de votre application qui effectue des recherches en fonction d'une chaîne de requête et présente les résultats de recherche.

Lorsque l'utilisateur exécute une recherche dans la boîte de dialogue ou le widget de recherche, le système démarre votre activité de recherche et lui fournit la requête de recherche dans un Intent avec l'action ACTION_SEARCH. Votre activité de recherche récupère la requête à partir de l'extra QUERY de l'intention, 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 n'importe quelle autre activité de votre application, le système doit savoir quelle activité est votre activité de recherche afin de pouvoir transmettre correctement la requête de recherche. Commencez par déclarer votre activité pouvant faire l'objet d'une recherche dans le fichier manifeste Android.

Déclarer une activité pouvant faire l'objet d'une recherche

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

1. Déclarez l'activité pour accepter l'intent ACTION_SEARCH dans un élément <intent-filter>.
2. 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 pouvant faire l'objet d'une recherche. Dans l'exemple précédent, il fait référence au fichier res/xml/searchable.xml.

Effectuer une recherche

Après avoir déclaré votre activité pouvant faire l'objet d'une recherche dans le fichier manifeste, suivez cette procédure pour effectuer une recherche dans votre activité pouvant faire l'objet d'une recherche :

1. Recevez la requête.
2. Recherchez dans vos données.
3. 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é de recherche et lui envoie un intent ACTION_SEARCH. Cette intention contient la requête de recherche dans l'extra de chaîne QUERY. Recherchez cet intent au démarrage de l'activité et extrayez la chaîne. Par exemple, voici comment obtenir la requête de recherche lorsque votre activité pouvant faire l'objet d'une recherche démarre :

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

@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 dans l'intention 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 proprement dite 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 nombreuses façons, 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 robuste dans les données textuelles et produire des résultats beaucoup plus rapidement. Pour en savoir plus sur FTS3 et la classe SQLiteDatabase, consultez sqlite.org.
• Si vos données sont stockées en ligne, les performances de recherche perçues peuvent être limitées par la connexion de données de l'utilisateur. Vous pouvez afficher un indicateur de progression jusqu'à ce que votre recherche renvoie des résultats. Consultez android.net pour obtenir une référence des API réseau et ProgressBar pour savoir comment afficher un indicateur de progression.

Présenter les résultats

Quel que soit l'emplacement de vos données et la façon dont vous les recherchez, nous vous recommandons de renvoyer les résultats de recherche vers votre activité consultable avec un Adapter. Vous pouvez ainsi présenter tous les résultats de recherche dans un RecyclerView. Si vos 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 dans un format différent, vous pouvez créer une extension de BaseAdapter.

Un Adapter lie chaque élément d'un ensemble de données à un objet View. Lorsque 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. Des implémentations telles que CursorAdapter sont donc nécessaires pour associer des données à un Cursor. 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 de l'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 de recherche à une activité de recherche 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 si 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 les requêtes de recherche de la boîte de dialogue de recherche. Par exemple, dans la section précédente sur la création d'une activité pouvant faire l'objet d'une recherche, une activité pouvant faire l'objet d'une recherche nommée SearchableActivity est créée. Si vous souhaitez qu'une activité distincte, telle que celle nommée OtherActivity, affiche la boîte de dialogue de recherche et transmette les recherches à SearchableActivity, déclarez dans le fichier manifeste que SearchableActivity est l'activité de recherche à utiliser pour la boîte de dialogue de recherche dans OtherActivity.

Pour déclarer l'activité pouvant faire l'objet d'une recherche pour la boîte de dialogue de recherche d'une activité, ajoutez un élément <meta-data> à l'intérieur de 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é pouvant faire l'objet d'une recherche et l'attribut android:name avec la valeur "android.app.default_searchable".

Par exemple, voici la déclaration pour une activité pouvant faire l'objet d'une recherche, SearchableActivity, et une autre activité, OtherActivity, qui utilise SearchableActivity pour effectuer les 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é de recherche à 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 démarre SearchableActivity et lui fournit l'intention ACTION_SEARCH.

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 façon, chaque activité hérite de la valeur, fournit la boîte de dialogue de recherche et transmet les recherches à la même activité de recherche. Si vous avez plusieurs activités pouvant faire l'objet d'une recherche, vous pouvez remplacer l'activité par défaut pouvant faire l'objet d'une recherche en plaçant une autre déclaration <meta-data> dans les activités individuelles.

Maintenant que la boîte de dialogue de recherche est 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é, le comportement du bouton peut varier d'un appareil à l'autre, et de nombreux appareils ne fournissent pas du tout de bouton de recherche. Par conséquent, lorsque vous utilisez la boîte de dialogue de recherche, vous devez fournir un bouton de recherche dans votre UI 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 dans la mise en page de l'UI qui appelle onSearchRequested().

Vous pouvez également activer la fonctionnalité de saisie pour la recherche, qui active la boîte de dialogue de recherche lorsque l'utilisateur commence à saisir du texte au clavier. Les frappes sont insérées dans la boîte de dialogue de recherche. Vous pouvez activer la saisie pour la recherche dans votre activité en appelant setDefaultKeyMode ou DEFAULT_KEYS_SEARCH_LOCAL pendant 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 Dialog flottant en haut de l'écran. Cela n'entraîne aucune modification de la pile d'activités. Par conséquent, lorsque la boîte de dialogue de recherche s'affiche, aucune méthode de cycle de vie, telle que onPause(), n'est appelée. Votre activité perd le focus d'entrée, car il est attribué à 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 focus d'entrée au profit de la boîte de dialogue de recherche. Vous pouvez donc effectuer toute tâche appropriée à l'événement, comme mettre un jeu en pause. Sauf si vous transmettez des données de contexte de recherche (ce qui est abordé dans une autre section de ce document), terminez la méthode en appelant l'implémentation de la superclasse :

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

@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é récupère le focus d'entrée. Vous pouvez vous inscrire pour 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 OnDismissListener, car il est appelé chaque fois que la boîte de dialogue de recherche se ferme. OnCancelListenerne 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é pouvant faire l'objet d'une recherche, les événements de cycle de vie d'activité normaux sont déclenchés lorsque l'utilisateur exécute une recherche. L'activité actuelle reçoit onPause(), comme décrit dans Présentation des activités. Toutefois, si l'activité actuelle est l'activité pouvant faire l'objet d'une recherche, deux scénarios sont possibles :

• Par défaut, l'activité pouvant faire l'objet d'une recherche 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é de recherche dans la pile d'activités. Par conséquent, lorsque vous appuyez sur le bouton "Retour", vous revenez à l'instance précédente de l'activité de recherche, au lieu de quitter l'activité de recherche.
• Si vous définissez android:launchMode sur "singleTop", l'activité pouvant faire l'objet d'une recherche reçoit l'intent ACTION_SEARCH avec un appel à onNewIntent(Intent), en transmettant le nouvel intent ACTION_SEARCH. Par exemple, voici comment gérer ce cas, dans lequel le mode de lancement de l'activité pouvant faire l'objet d'une recherche 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'intention de recherche se trouve désormais 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. La méthode getIntent() renvoie donc le même intent que celui reçu avec onCreate(). C'est pourquoi vous devez appeler setIntent(Intent) à l'intérieur de onNewIntent(Intent) : pour que l'intent enregistré par l'activité soit mis à jour si vous appelez getIntent() à l'avenir.

Le deuxième scénario, qui utilise le mode de lancement "singleTop", est généralement préférable, car après une recherche, l'utilisateur peut effectuer d'autres recherches. Vous ne voulez pas que votre application crée plusieurs instances de l'activité de recherche. Nous vous recommandons de définir votre activité de recherche sur le mode de lancement "singleTop" dans le fichier manifeste de l'application, comme indiqué 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é pouvant faire l'objet d'une recherche 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'intention que le système envoie à votre activité pouvant faire l'objet d'une recherche. Vous pouvez transmettre les données supplémentaires dans APP_DATA Bundle, qui est inclus dans l'intention ACTION_SEARCH.

Pour transmettre ce type de données à votre activité de recherche, 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 et appelez startSearch() pour activer la boîte de dialogue de recherche. Exemple :

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

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

Si vous renvoyez la valeur "true", cela signifie que vous avez géré cet événement de rappel et que vous avez appelé startSearch() pour activer la boîte de dialogue de recherche. Une fois que l'utilisateur a envoyé une requête, elle est transmise à votre activité pouvant faire l'objet d'une recherche, ainsi qu'aux 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 :

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

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

Utiliser le widget de recherche

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

Le widget de recherche offre les mêmes fonctionnalités que la boîte de dialogue de recherche. Il démarre l'activité appropriée lorsque l'utilisateur effectue une recherche, et il 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 ailleurs dans la mise en page de votre activité.

Configurer le widget Recherche

Après avoir créé une configuration de recherche et une activité pouvant faire l'objet d'une recherche, activez la recherche assistée pour chaque SearchView en appelant setSearchableInfo() et en lui transmettant l'objet SearchableInfo qui représente votre configuration 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 pendant le rappel onCreateOptionsMenu(), comme indiqué dans l'exemple suivant :

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
}

@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 de recherche est maintenant configuré et le système envoie les requêtes de recherche à votre activité pouvant faire l'objet d'une recherche. Vous pouvez également activer les suggestions de recherche pour le widget de recherche.

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 propose quelques fonctionnalités supplémentaires qui pourraient vous intéresser :

Bouton "Envoyer"

Par défaut, aucun bouton n'est disponible pour envoyer une requête de recherche. L'utilisateur doit donc appuyer sur la touche Retour 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 pour que l'utilisateur puisse l'affiner en appelant setQueryRefinementEnabled(true).

La possibilité d'activer ou de désactiver la visibilité du champ de recherche

Par défaut, le widget de recherche est "iconifié", ce qui signifie qu'il n'est représenté que par une icône de recherche (une loupe). Elle se développe pour afficher le champ de recherche lorsque l'utilisateur appuie sur l'icône. Comme le montre l'exemple précédent, vous pouvez afficher la barre de recherche par défaut en appelant setIconifiedByDefault(false). Vous pouvez également activer ou désactiver l'apparence du widget de recherche en appelant setIconified().

La classe SearchView contient plusieurs autres API qui vous permettent de personnaliser le widget de recherche. Toutefois, la plupart d'entre eux ne sont utilisés que lorsque vous gérez vous-même toutes les saisies utilisateur, au lieu d'utiliser le système Android pour fournir 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 de recherche dans la barre d'application en tant que vue d'action et que vous l'activez pour qu'il apparaisse dans la barre d'application s'il y a de la place (en définissant android:showAsAction="ifRoom"), le widget de recherche peut ne pas apparaître en tant que vue d'action. mais plutôt dans le menu à développer. Par exemple, lorsque votre application s'exécute sur un petit écran, il peut ne pas y avoir assez de place dans la barre d'application pour afficher le widget de recherche avec d'autres éléments d'action ou de navigation. L'élément de menu apparaît alors 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 d'action, c'est-à-dire le widget de 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 le 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 façon 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 widget de recherche en ajoutant l'attribut android:voiceSearchMode à votre configuration de recherche. Cela ajoute 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é pouvant faire l'objet d'une 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 recognizer qui renvoie le texte transcrit à l'activité de recherche.

Vous pouvez fournir des attributs supplémentaires pour spécifier le comportement de la recherche vocale, comme 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 de recherche peuvent tous deux 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 sélectionne une suggestion.

Vous pouvez fournir deux types de suggestions de recherche :

Suggestions de recherche de requêtes récentes

 Ces suggestions sont des mots que l'utilisateur a déjà 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 pour 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.