Aggiungi suggerimenti di ricerca personalizzati

Nella finestra di dialogo di ricerca o nel widget Ricerca di Android puoi fornire suggerimenti di ricerca basati sulle query di ricerca recenti. Ad esempio, se un utente esegue una query su "cuccioli", la query viene visualizzata come suggerimento quando digita di nuovo la stessa query. La Figura 1 mostra un esempio di finestra di dialogo di ricerca con suggerimenti di query recenti.

Prima di iniziare, implementa la finestra di dialogo di ricerca o un widget di ricerca per le ricerche di base nell'applicazione. Per scoprire come, consulta Creare un'interfaccia di ricerca.

Nozioni di base

Figura 1. Screenshot di una finestra di dialogo di ricerca con suggerimenti di query recenti.

I suggerimenti per le query recenti sono ricerche salvate. Quando l'utente seleziona un suggerimento, la tua attività disponibile per la ricerca riceve un intent ACTION_SEARCH con il suggerimento come query di ricerca già gestita dalla tua attività di ricerca.

Per fornire suggerimenti per le query recenti, devi:

  • Implementa un'attività disponibile per la ricerca.
  • Crea un fornitore di contenuti che estenda SearchRecentSuggestionsProvider e dichiaralo nel manifest dell'applicazione.
  • Modifica la configurazione disponibile per la ricerca con informazioni sul fornitore di contenuti che fornisce suggerimenti di ricerca.
  • Salva le query nel tuo fornitore di contenuti ogni volta che viene eseguita una ricerca.

Proprio come il sistema Android mostra la finestra di dialogo di ricerca, mostra i suggerimenti di ricerca sotto la finestra di dialogo o il widget Ricerca. Sei tu a indicare l'origine da cui il sistema recupera i suggerimenti.

Quando il sistema identifica che la tua attività è disponibile per la ricerca e fornisce suggerimenti per le ricerche, quando l'utente digita una query, si verifica quanto segue:

  1. Il sistema prende il testo della query di ricerca (a prescindere da ciò che l'utente inizia a digitare) ed esegue la query al fornitore di contenuti che contiene i tuoi suggerimenti.
  2. Il tuo fornitore di contenuti restituisce un Cursor che indirizza a tutti i suggerimenti che corrispondono al testo della query di ricerca.
  3. Il sistema visualizza l'elenco di suggerimenti forniti da Cursor.

Una volta visualizzati i suggerimenti per le query recenti, potrebbe verificarsi quanto segue:

  • Se l'utente digita un'altra chiave o modifica in qualsiasi modo la query, i passaggi precedenti vengono ripetuti e l'elenco dei suggerimenti viene aggiornato.
  • Se l'utente esegue la ricerca, i suggerimenti vengono ignorati e la ricerca viene inviata alla tua attività disponibile per la ricerca utilizzando il normale intent ACTION_SEARCH.
  • Se l'utente seleziona un suggerimento, un intent ACTION_SEARCH viene mostrato alla tua attività di ricerca utilizzando il testo suggerito come query.

La classe SearchRecentSuggestionsProvider che estendi per il tuo fornitore di contenuti svolge automaticamente le operazioni descritte nei passaggi precedenti, pertanto la scrittura del codice è ridotta.

Crea un fornitore di contenuti

Il fornitore di contenuti di cui hai bisogno per i suggerimenti per le query recenti è un'implementazione di SearchRecentSuggestionsProvider. Questo corso fa tutto per te. Devi solo scrivere un costruttore della classe che esegua una riga di codice.

Ad esempio, ecco un'implementazione completa di un fornitore di contenuti per suggerimenti di query recenti:

Kotlin

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

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

Java

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

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

La chiamata a setupSuggestions() passa il nome dell'autorità di ricerca e una modalità di database. L'autorità di ricerca può essere qualsiasi stringa univoca, ma la best practice consiste nell'utilizzare un nome completo per il fornitore di contenuti, ad esempio il nome del pacchetto seguito dal nome della classe del provider. Ad esempio, "com.example.MySuggestionProvider".

La modalità database deve includere DATABASE_MODE_QUERIES e può facoltativamente includere DATABASE_MODE_2LINES, che aggiunge una colonna alla tabella dei suggerimenti in modo da poter fornire una seconda riga di testo con ogni suggerimento. Se vuoi fornire due righe in ogni suggerimento, vedi l'esempio seguente:

Kotlin

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

Java

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

Dichiara il fornitore di contenuti nel file manifest dell'applicazione con la stessa stringa di autorità utilizzata nella tua classe SearchRecentSuggestionsProvider e nella configurazione disponibile per la ricerca. Ad esempio:

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

Modifica la configurazione disponibile per la ricerca

Per configurare il sistema in modo che utilizzi il tuo fornitore di suggerimenti, aggiungi gli attributi android:searchSuggestAuthority e android:searchSuggestSelection all'elemento <searchable> nel file di configurazione disponibile per la ricerca. Ad esempio:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="com.example.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

Il valore di android:searchSuggestAuthority deve essere un nome completo per il fornitore di contenuti che corrisponda esattamente all'autorità utilizzata nel fornitore di contenuti, ad esempio "com.example.MySuggestionProvider" negli esempi precedenti.

Il valore di android:searchSuggestSelection deve essere un singolo punto interrogativo preceduto da uno spazio: " ?". Questo è un segnaposto per l'argomento di selezione SQLite e viene sostituito automaticamente dal testo della query inserito dall'utente.

Salvare le query

Per completare la raccolta di query recenti, aggiungi ogni query ricevuta dalla tua attività di ricerca a SearchRecentSuggestionsProvider. Per farlo, crea un'istanza di SearchRecentSuggestions e chiama saveRecentQuery() ogni volta che la tua attività disponibile per la ricerca riceve una query. Ad esempio, ecco come puoi salvare la query durante il metodo onCreate() dell'attività:

Kotlin

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

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

Java

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

    Intent intent  = getIntent();

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

Il costruttore SearchRecentSuggestionsProvider richiede la stessa autorità e la stessa modalità database dichiarate dal tuo fornitore di contenuti.

Il metodo saveRecentQuery() prende la stringa di query di ricerca come primo parametro e, facoltativamente, una seconda stringa da includere come seconda riga del suggerimento o null. Il secondo parametro viene utilizzato solo se attivi la modalità a due righe per i suggerimenti di ricerca con DATABASE_MODE_2LINES. Se attivi la modalità su due righe, il testo della query viene confrontato con la seconda riga quando il sistema cerca suggerimenti corrispondenti.

Cancella i dati dei suggerimenti

Per proteggere la privacy dell'utente, fornisci sempre un modo per cancellare i suggerimenti di query recenti. Per cancellare la cronologia delle query, chiama clearHistory(). Ecco alcuni esempi:

Kotlin

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

Java

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

Esegui questa operazione scegliendo una voce di menu, una voce di preferenza o un pulsante "Cancella cronologia ricerche". Fornisci una finestra di dialogo di conferma per verificare che l'utente voglia eliminare la propria cronologia delle ricerche.