Crea un'interfaccia di ricerca

Quando è tutto pronto per aggiungere la funzionalità di ricerca alla tua app, Android ti consente di implementare l'interfaccia utente con una finestra di dialogo di ricerca visualizzata nella parte superiore della finestra delle attività o con un widget di ricerca che puoi inserire nel layout. Sia la finestra di dialogo di ricerca che il widget possono indirizzare la query di ricerca dell'utente a un'attività specifica nella tua app. In questo modo l'utente può avviare una ricerca da qualsiasi attività in cui la finestra di dialogo o il widget di ricerca sono disponibili e il sistema avvia l'attività appropriata per eseguire la ricerca e presentare i risultati.

Altre funzionalità disponibili per la finestra di dialogo e il widget di ricerca includono:

• Ricerca vocale
• Suggerimenti di ricerca basati sulle query recenti
• Suggerimenti di ricerca che corrispondono a risultati effettivi nei dati dell'app

Questo documento mostra come configurare l'app in modo che fornisca un'interfaccia di ricerca assistita dal sistema Android per l'invio di query di ricerca, utilizzando la finestra di dialogo di ricerca o il widget Ricerca.

Risorse correlate:

• Icone di material design

Nozioni di base

Prima di iniziare, decidi se implementare l'interfaccia di ricerca utilizzando la finestra di dialogo o il widget Ricerca. Forniscono le stesse funzionalità di ricerca, ma in modi leggermente diversi:

• La finestra di dialogo di ricerca è un componente dell'interfaccia utente controllato dal sistema Android. Se attivata dall'utente, la finestra di dialogo di ricerca viene visualizzata nella parte superiore dell'attività.

  Il sistema Android controlla tutti gli eventi nella finestra di dialogo di ricerca. Quando un utente invia una query, il sistema la invia all'attività specificata per gestire le ricerche. La finestra di dialogo può anche fornire suggerimenti di ricerca durante la digitazione dell'utente.

• Il widget di ricerca è un'istanza di SearchView che puoi posizionare ovunque nel layout. Per impostazione predefinita, il widget di ricerca si comporta come un widget EditText standard e non fa nulla, ma puoi configurarlo in modo che il sistema Android gestisca tutti gli eventi di input, invii le query all'attività appropriata e fornisca suggerimenti di ricerca, proprio come la finestra di dialogo di ricerca.

Quando l'utente esegue una ricerca dalla finestra di dialogo di ricerca o da un widget di ricerca, il sistema crea un elemento Intent e memorizza al suo interno la query dell'utente. Il sistema avvia quindi l'attività per cui dichiari di gestire le ricerche (l'"attività disponibile per la ricerca") e pubblica l'intenzione. Per configurare la tua app per questo tipo di ricerca assistita, devi disporre di:

Una configurazione di ricerca

Un file XML che configura alcune impostazioni per il widget o la finestra di dialogo di ricerca. Include impostazioni per funzionalità quali la ricerca vocale, i suggerimenti di ricerca e il testo dei suggerimenti per la casella di ricerca.

Un'attività disponibile per la ricerca

L'elemento Activity che riceve la query di ricerca, cerca tra i dati e visualizza i risultati di ricerca.

Un'interfaccia di ricerca, fornita da una delle seguenti opzioni:

La finestra di dialogo di ricerca

Per impostazione predefinita, la finestra di dialogo di ricerca è nascosta. Viene visualizzata nella parte superiore dello schermo quando chiami onSearchRequested() quando l'utente tocca il pulsante Cerca.

Un widget SearchView

Il widget di ricerca ti consente di inserire la casella di ricerca in qualsiasi punto della tua attività, ad esempio come visualizzazione delle azioni nella barra dell'app.

Il resto del documento mostra come creare la configurazione di ricerca e l'attività di ricerca e come implementare un'interfaccia di ricerca con la finestra di dialogo di ricerca o il widget di ricerca.

Crea una configurazione disponibile per la ricerca

Per prima cosa ti serve un file XML denominato configurazione della ricerca. Configura alcuni aspetti dell'interfaccia utente della finestra di dialogo o del widget di ricerca e definisce il comportamento di funzionalità come i suggerimenti e la ricerca vocale. Questo file viene tradizionalmente denominato searchable.xml e deve essere salvato nella directory del progetto res/xml/.

Il file di configurazione della ricerca deve includere l'elemento <searchable> come nodo radice e specificare uno o più attributi, come mostrato nell'esempio seguente:

<?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'attributo android:label è l'unico attributo obbligatorio. Rimanda a una risorsa stringa, che deve essere il nome dell'app. Questa etichetta non sarà visibile all'utente finché non abiliti i suggerimenti di ricerca per la Casella di ricerca rapida. A quel punto, l'etichetta sarà visibile nell'elenco degli elementi disponibili per la ricerca nelle impostazioni di sistema.

Sebbene non sia obbligatorio, consigliamo di includere sempre l'attributo android:hint, che fornisce una stringa di suggerimento nella casella di ricerca prima che gli utenti inseriscano una query. È importante perché fornisce indizi importanti per gli utenti su ciò che possono cercare.

L'elemento <searchable> accetta diversi altri attributi. Tuttavia, la maggior parte degli attributi non sarà necessaria finché non avrai aggiunto funzionalità quali i suggerimenti di ricerca e la ricerca vocale. Per informazioni dettagliate sul file di configurazione di ricerca, consulta il documento di riferimento sulla configurazione di ricerca.

Crea un'attività disponibile per la ricerca

Un'attività disponibile per la ricerca è Activity nella tua app che esegue ricerche basate su una stringa di query e presenta i risultati di ricerca.

Quando l'utente esegue una ricerca nella finestra di dialogo o nel widget di ricerca, il sistema avvia l'attività disponibile per la ricerca e la pubblica in un Intent con l'azione ACTION_SEARCH. L'attività disponibile per la ricerca recupera la query dagli extraQUERY dell'intent, poi esegue una ricerca nei dati e presenta i risultati.

Poiché puoi includere il widget o la finestra di dialogo di ricerca in qualsiasi altra attività nell'app, il sistema deve sapere quale attività è la tua attività disponibile per la ricerca in modo da poter pubblicare correttamente la query di ricerca. Per prima cosa, dichiara la tua attività ricercabile nel file manifest di Android.

Dichiara un'attività disponibile per la ricerca

Se non ne hai già uno, crea un Activity che esegua ricerche e fornisca risultati. Non è ancora necessario implementare la funzionalità di ricerca: è sufficiente creare un'attività che puoi dichiarare nel file manifest. All'interno dell'elemento <activity> del manifest, procedi nel seguente modo:

1. Dichiara l'attività in modo da accettare l'intent ACTION_SEARCH in un elemento <intent-filter>.
2. Specifica la configurazione di ricerca da utilizzare in un elemento <meta-data>.

Questo è quanto mostrato nell'esempio seguente:

<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'elemento <meta-data> deve includere l'attributo android:name con il valore "android.app.searchable" e l'attributo android:resource con un riferimento al file di configurazione disponibile per la ricerca. Nell'esempio precedente, fa riferimento al file res/xml/searchable.xml.

Eseguire una ricerca

Dopo aver dichiarato la tua attività disponibile per la ricerca nel file manifest, segui questa procedura per eseguire una ricerca nella tua attività disponibile per la ricerca:

1. Ricevi la query.
2. Cercare nei dati.
3. Presenta i risultati.

Ricevi la query

Quando un utente esegue una ricerca dalla finestra di dialogo o dal widget di ricerca, il sistema avvia la tua attività disponibile per la ricerca e le invia un intent ACTION_SEARCH. Questo intent inserisce la query di ricerca nella stringa QUERY aggiuntiva. Controlla questo intent quando inizia l'attività ed estrai la stringa. Ad esempio, ecco come trovare la query di ricerca quando inizia l'attività disponibile per la ricerca:

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 stringa QUERY viene sempre inclusa nell'intent ACTION_SEARCH. Nell'esempio precedente, la query viene recuperata e passata a un metodo doMySearch() locale in cui viene eseguita l'operazione di ricerca effettiva.

Cercare nei dati

Il processo di archiviazione e ricerca dei dati è specifico della tua app. Puoi archiviare e cercare i dati in molti modi e questo documento non ti mostra come fare. Considera il modo in cui archivi e cerchi i tuoi dati in base alle tue esigenze e al tuo formato dei dati. Ecco alcuni suggerimenti che potresti riuscire a implementare:

• Se i tuoi dati sono archiviati sul dispositivo in un database SQLite, l'esecuzione di una ricerca dell'intero testo (utilizzando FTS3 anziché una query LIKE) può fornire una ricerca più solida su dati di testo e produrre risultati molto più velocemente. Consulta sqlite.org per informazioni su FTS3 e sulla classe SQLiteDatabase per informazioni su SQLite su Android.
• Se i tuoi dati sono archiviati online, le prestazioni della ricerca percepita potrebbero essere inibite dalla connessione dati dell'utente. Ti consigliamo di visualizzare un indicatore di avanzamento fino a quando la ricerca non ritorna. Consulta android.net per un riferimento sulle API di rete e ProgressBar per informazioni su come visualizzare un indicatore di avanzamento.

Presenta i risultati

Indipendentemente da dove si trovano i tuoi dati e dalle modalità di ricerca, ti consigliamo di restituire i risultati di ricerca alla tua attività disponibile per la ricerca con un Adapter. In questo modo, puoi presentare tutti i risultati di ricerca in un RecyclerView. Se i tuoi dati provengono da una query di database SQLite, puoi applicare i risultati a un elemento RecyclerView utilizzando un CursorAdapter. Se i dati sono disponibili in un formato diverso, puoi creare un'estensione di BaseAdapter.

Un Adapter associa ogni elemento di un insieme di dati a un oggetto View. Quando Adapter viene applicato a un RecyclerView, ogni dato viene inserito come singola vista nell'elenco. Adapter è solo un'interfaccia, pertanto sono necessarie implementazioni come CursorAdapter, per associare i dati di un Cursor. Se nessuna delle implementazioni esistenti funziona per i tuoi dati, puoi implementarne una da BaseAdapter.

Utilizza la finestra di dialogo di ricerca

La finestra di dialogo di ricerca contiene una casella di ricerca mobile nella parte superiore dello schermo, con l'icona dell'app a sinistra. La finestra di dialogo di ricerca può fornire suggerimenti di ricerca durante la digitazione. Quando l'utente esegue una ricerca, il sistema invia la query di ricerca a un'attività disponibile per la ricerca che la esegue.

Per impostazione predefinita, la finestra di dialogo di ricerca è sempre nascosta fino a quando l'utente non la attiva. La tua app può attivare la finestra di dialogo di ricerca chiamando il numero onSearchRequested(). Tuttavia, questo metodo non funziona finché non abiliti la finestra di dialogo di ricerca per l'attività.

Per consentire l'esecuzione di ricerche nella finestra di dialogo di ricerca, indica al sistema quale attività ricercabile deve ricevere le query di ricerca dalla finestra di dialogo. Ad esempio, nella sezione precedente sulla creazione di un'attività disponibile per la ricerca, viene creata un'attività disponibile per la ricerca denominata SearchableActivity. Se vuoi che un'attività separata, ad esempio una denominata OtherActivity, mostri la finestra di dialogo di ricerca e invii le ricerche a SearchableActivity, dichiara nel file manifest che SearchableActivity è l'attività disponibile per la ricerca da utilizzare per la finestra di dialogo di ricerca in OtherActivity.

Per dichiarare l'attività disponibile per la ricerca per la finestra di dialogo di ricerca di un'attività, aggiungi un elemento <meta-data> all'interno del rispettivo elemento <activity> dell'attività. L'elemento <meta-data> deve includere l'attributo android:value che specifica il nome della classe dell'attività disponibile per la ricerca e l'attributo android:name con un valore "android.app.default_searchable".

Ad esempio, ecco la dichiarazione relativa a un'attività disponibile per la ricerca, SearchableActivity, e a un'altra attività, OtherActivity, che utilizza SearchableActivity per eseguire le ricerche eseguite dalla finestra di dialogo di ricerca:

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

Poiché ora OtherActivity include un elemento <meta-data> per dichiarare quale attività disponibile per la ricerca utilizzare per le ricerche, l'attività attiva la finestra di dialogo di ricerca. Anche se l'utente sta in questa attività, il metodo onSearchRequested() attiva la finestra di dialogo di ricerca. Quando l'utente esegue la ricerca, il sistema avvia SearchableActivity e lo invia all'intent ACTION_SEARCH.

Se vuoi che ogni attività della tua app fornisca la finestra di dialogo di ricerca, inserisci l'elemento <meta-data> precedente come elemento secondario dell'elemento <application>, anziché ogni <activity>. In questo modo, ogni attività eredita il valore, fornisce la finestra di dialogo di ricerca e invia le ricerche alla stessa attività disponibile per la ricerca. Se disponi di più attività disponibili per la ricerca, puoi eseguire l'override dell'attività disponibile per la ricerca predefinita inserendo una dichiarazione <meta-data> diversa all'interno delle singole attività.

Con la finestra di dialogo di ricerca ora attivata per le tue attività, la tua app è pronta per eseguire ricerche.

Richiamare la finestra di dialogo di ricerca

Anche se alcuni dispositivi forniscono un pulsante di ricerca dedicato, il comportamento di tale pulsante può variare in base al dispositivo e molti dispositivi non forniscono affatto un pulsante di ricerca. Di conseguenza, quando utilizzi la finestra di dialogo di ricerca, devi fornire un pulsante di ricerca nella tua UI che attivi la finestra di dialogo di ricerca chiamando onSearchRequested().

Ad esempio, aggiungi un pulsante di ricerca nel menu opzioni o nel layout UI che chiama onSearchRequested().

Puoi anche attivare la funzionalità "Digita per cercare", che attiva la finestra di dialogo di ricerca quando l'utente inizia a digitare sulla tastiera. Le sequenze di tasti vengono inserite nella finestra di dialogo di ricerca. Puoi attivare il tipo per ricercare nelle tue attività chiamando setDefaultKeyMode (o DEFAULT_KEYS_SEARCH_LOCAL) durante il metodo onCreate() dell'attività.

L'impatto della finestra di dialogo di ricerca sul ciclo di vita delle attività

La finestra di dialogo di ricerca è un elemento Dialog che galleggia nella parte superiore dello schermo. Non causa alcuna modifica nello stack delle attività, pertanto quando viene visualizzata la finestra di dialogo di ricerca, non viene chiamato alcun metodo del ciclo di vita, come onPause(). La tua attività perde lo stato attivo sull'input, perché lo stato attivo viene impostato sulla finestra di dialogo di ricerca.

Se vuoi ricevere una notifica quando viene attivata la finestra di dialogo di ricerca, esegui l'override del metodo onSearchRequested(). Quando il sistema chiama questo metodo, significa che la tua attività perde lo stato attivo dell'input nella finestra di dialogo di ricerca, quindi puoi svolgere qualsiasi operazione appropriata per l'evento, ad esempio mettere in pausa un gioco. A meno che tu non stia passando i dati sul contesto della ricerca, descritti in un'altra sezione di questo documento, termina il metodo chiamando l'implementazione della superclasse:

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

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

Se l'utente annulla la ricerca toccando il pulsante Indietro, la finestra di dialogo di ricerca si chiude e l'attività torna a selezionare l'input. Puoi registrarti per ricevere una notifica quando la finestra di dialogo di ricerca viene chiusa con setOnDismissListener(), setOnCancelListener() o entrambi. Devi solo registrare OnDismissListener, perché viene chiamato ogni volta che la finestra di dialogo di ricerca si chiude. OnCancelListener riguarda solo gli eventi in cui l'utente esce esplicitamente dalla finestra di dialogo di ricerca, quindi non viene richiamato quando viene eseguita una ricerca. Quando si esegue la ricerca, la finestra di dialogo scompare automaticamente.

Se l'attività corrente non è quella disponibile per la ricerca, gli eventi del normale ciclo di vita dell'attività vengono attivati quando l'utente esegue una ricerca, l'attività corrente riceve onPause(), come descritto nella sezione Introduzione alle attività. Tuttavia, se l'attività corrente è quella disponibile per la ricerca, si verifica una delle due seguenti situazioni:

• Per impostazione predefinita, l'attività disponibile per la ricerca riceve l'intent ACTION_SEARCH con una chiamata a onCreate() e una nuova istanza dell'attività viene spostata in cima all'elenco attività. Nell'elenco delle attività ora sono presenti due istanze dell'attività disponibile per la ricerca, quindi toccando il pulsante Indietro puoi tornare all'istanza precedente dell'attività disponibile per la ricerca, anziché uscire dall'attività disponibile per la ricerca.
• Se imposti android:launchMode su "singleTop", l'attività disponibile per la ricerca riceve l'intent ACTION_SEARCH con una chiamata a onNewIntent(Intent), passando il nuovo intent ACTION_SEARCH. Ad esempio, ecco come potresti gestire questo caso, in cui la modalità di avvio dell'attività disponibile per la ricerca è "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);
      }
  }
  

  Rispetto al codice di esempio nella sezione sull'esecuzione di una ricerca, tutto il codice per gestire l'intento di ricerca è ora nel metodo handleIntent(), in modo che sia onCreate() sia onNewIntent() possano eseguirlo.

  Quando il sistema chiama onNewIntent(Intent), l'attività non viene riavviata, quindi il metodo getIntent() restituisce lo stesso intent ricevuto con onCreate(). Questo è il motivo per cui devi chiamare setIntent(Intent) all'interno di onNewIntent(Intent), in modo che l'intent salvato dall'attività venga aggiornato nel caso in cui tu chiami getIntent() in futuro.

Il secondo scenario, che utilizza la modalità di avvio "singleTop", è in genere preferibile perché, dopo il termine di una ricerca, l'utente potrebbe eseguire ricerche aggiuntive e non vuoi che la tua app crei più istanze dell'attività disponibile per la ricerca. Ti consigliamo di impostare la tua attività disponibile per la ricerca sulla modalità di avvio "singleTop" nel file manifest dell'app, come mostrato nell'esempio seguente:

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

Trasmettere dati contestuali di ricerca

In alcuni casi, puoi apportare i perfezionamenti necessari alla query di ricerca all'interno dell'attività di ricerca per ogni ricerca effettuata. Tuttavia, se vuoi perfezionare i criteri di ricerca in base all'attività in cui l'utente esegue una ricerca, puoi fornire dati aggiuntivi nell'intento che il sistema invia alla tua attività disponibile per la ricerca. Puoi trasmettere i dati aggiuntivi in APP_DATA Bundle, che è incluso nell'intent ACTION_SEARCH.

Per passare questo tipo di dati all'attività disponibile per la ricerca, sostituisci il metodo onSearchRequested() per l'attività da cui l'utente può eseguire una ricerca, crea una Bundle con i dati aggiuntivi e chiama startSearch() per attivare la finestra di dialogo di ricerca. Ecco alcuni esempi:

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

Se restituisce true, indica che hai gestito correttamente questo evento di callback e chiama startSearch() per attivare la finestra di dialogo di ricerca. Dopo che l'utente invia una query, questa viene inviata alla tua attività disponibile per la ricerca insieme ai dati aggiunti. Puoi estrarre i dati aggiuntivi dal APP_DATA Bundle per perfezionare la ricerca, come mostrato nell'esempio seguente:

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

Utilizzare il widget Ricerca

Figura 1. Il widget SearchView come visualizzazione azione nella barra dell'app.

Il widget di ricerca offre le stesse funzionalità della finestra di dialogo di ricerca. Avvia l'attività appropriata quando l'utente esegue una ricerca e può fornire suggerimenti di ricerca ed eseguire ricerche vocali. Se l'opzione per inserire il widget di ricerca nella barra delle app non è presente, puoi inserire il widget di ricerca in un punto del layout delle attività.

Configurare il widget di ricerca

Dopo aver creato una configurazione di ricerca e un'attività disponibile per la ricerca, abilita la ricerca assistita per ogni SearchView chiamando setSearchableInfo() e passando l'oggetto SearchableInfo che rappresenta la configurazione disponibile per la ricerca.

Puoi ottenere un riferimento a SearchableInfo chiamando il numero getSearchableInfo() al numero SearchManager.

Ad esempio, se utilizzi SearchView come visualizzazione azione nella barra dell'app, abilita il widget durante il callback onCreateOptionsMenu(), come mostrato nell'esempio seguente:

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

Il widget di ricerca è ora configurato e il sistema fornisce le query di ricerca all'attività disponibile per la ricerca. Puoi anche attivare i suggerimenti di ricerca per il widget Ricerca.

Per ulteriori informazioni sulle visualizzazioni azioni nella barra dell'app, consulta Utilizzare le visualizzazioni azioni e i provider di azioni.

Altre funzioni del widget Ricerca

Il widget SearchView offre alcune funzionalità aggiuntive che potrebbero esserti utili:

Un pulsante Invia

Per impostazione predefinita, non esiste un pulsante per inviare una query di ricerca, pertanto l'utente deve premere il tasto Invio sulla tastiera per avviare la ricerca. Puoi aggiungere un pulsante "Invia" chiamando il numero setSubmitButtonEnabled(true).

Perfezionamento query per suggerimenti di ricerca

Quando attivi i suggerimenti di ricerca, in genere ti aspetti che gli utenti selezionino un suggerimento, ma che potrebbero anche voler perfezionare la query di ricerca suggerita. Puoi aggiungere un pulsante accanto a ogni suggerimento che inserisce il suggerimento nella casella di ricerca per il perfezionamento da parte dell'utente chiamando setQueryRefinementEnabled(true).

La possibilità di attivare/disattivare la visibilità della casella di ricerca

Per impostazione predefinita, il widget Ricerca è "iconificato", il che significa che è rappresentato solo da un'icona di ricerca, ovvero una lente d'ingrandimento. Si espande per mostrare la casella di ricerca quando l'utente tocca l'icona. Come mostrato nell'esempio precedente, puoi mostrare la casella di ricerca per impostazione predefinita chiamando setIconifiedByDefault(false). Puoi anche attivare/disattivare l'aspetto del widget Ricerca chiamando setIconified().

Esistono diverse altre API nella classe SearchView che consentono di personalizzare il widget di ricerca. Tuttavia, la maggior parte di queste viene utilizzata solo quando gestisci autonomamente tutti gli input utente, anziché utilizzare il sistema Android per offrire query di ricerca e visualizzare suggerimenti di ricerca.

Utilizzare sia il widget sia la finestra di dialogo

Se inserisci il widget Ricerca nella barra dell'app come visualizzazione azione e lo attivi in modo che venga mostrato nella barra dell'app se c'è spazio (impostando android:showAsAction="ifRoom"), il widget di ricerca potrebbe non apparire come visualizzazione delle azioni. Invece, nel menu extra potrebbe essere visualizzata una voce di menu. Ad esempio, quando l'app viene eseguita su uno schermo più piccolo, nella barra dell'app potrebbe non esserci abbastanza spazio per visualizzare il widget Ricerca insieme ad altri elementi di azione o di navigazione, pertanto la voce di menu potrebbe apparire nel menu extra. Quando viene inserita nel menu extra, l'elemento funziona come una normale voce di menu e non mostra la visualizzazione delle azioni, ovvero il widget di ricerca.

Per gestire questa situazione, la voce di menu a cui alleghi il widget di ricerca deve attivare la finestra di dialogo di ricerca quando l'utente la seleziona dal menu extra. A tale scopo, implementa onOptionsItemSelected() per gestire la voce di menu "Cerca" e apri la finestra di dialogo di ricerca chiamando onSearchRequested().

Per ulteriori informazioni su come funzionano gli elementi nella barra delle app e su come gestire questa situazione, consulta Aggiungere la barra delle app.

Aggiungi ricerca vocale

Puoi aggiungere la funzionalità di ricerca vocale alla finestra di dialogo o al widget di ricerca aggiungendo l'attributo android:voiceSearchMode alla configurazione disponibile per la ricerca. Viene aggiunto un pulsante di ricerca vocale che avvia un prompt vocale. Quando l'utente finisce di parlare, la query di ricerca trascritta viene inviata alla tua attività ricercabile.

Questo è quanto mostrato nell'esempio seguente:

<?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>

Il valore showVoiceSearchButton è obbligatorio per attivare la ricerca vocale. Il secondo valore, launchRecognizer, specifica che il pulsante di ricerca vocale deve avviare un riconoscimento che restituisce il testo trascritto all'attività disponibile per la ricerca.

Puoi fornire attributi aggiuntivi per specificare il comportamento della ricerca vocale, ad esempio la lingua prevista e il numero massimo di risultati da restituire. Consulta il riferimento Configurazione di ricerca per ulteriori informazioni sugli attributi disponibili.

Aggiungi suggerimenti di ricerca

Sia la finestra di dialogo che il widget di ricerca possono fornire suggerimenti di ricerca durante la digitazione dell'utente, con l'assistenza del sistema Android. Il sistema gestisce l'elenco dei suggerimenti e l'evento quando l'utente seleziona un suggerimento.

Puoi fornire due tipi di suggerimenti di ricerca:

Suggerimenti per la ricerca di query recenti

Questi suggerimenti sono parole che l'utente ha utilizzato in precedenza come query di ricerca nella tua app. Per ulteriori informazioni, consulta la sezione Aggiungere suggerimenti di ricerca personalizzati.

Suggerimenti di ricerca personalizzati

Si tratta dei suggerimenti di ricerca forniti dalla tua origine dati per aiutare gli utenti a selezionare immediatamente l'ortografia corretta o l'elemento che stanno cercando. Per ulteriori informazioni, consulta la sezione Aggiungere suggerimenti di ricerca personalizzati.