Aggiungi suggerimenti di ricerca personalizzati

Prova Compose

Jetpack Compose è il toolkit per la UI consigliato per Android. Scopri come aggiungere la funzionalità di ricerca in Scrivi.

Barra di ricerca →

Puoi fornire suggerimenti per le ricerche in base alle query di ricerca recenti nella finestra di dialogo di ricerca di Android o nel widget di ricerca. Ad esempio, se un utente esegue una query "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 per le query recenti.

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

Nozioni di base

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

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

Per fornire suggerimenti per le query recenti, devi:

• Implementa un'attività in cui è possibile eseguire ricerche.
• Crea un content provider che estenda SearchRecentSuggestionsProvider e dichiaralo nel manifest dell'applicazione.
• Modifica la configurazione di 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 visualizza la finestra di dialogo di ricerca, visualizza i suggerimenti per le ricerche sotto la finestra di dialogo o il widget di ricerca. Fornisci l'origine da cui il sistema recupera i suggerimenti.

Quando il sistema rileva che la tua attività è ricercabile e fornisce suggerimenti di ricerca, quando l'utente digita una query:

1. Il sistema prende il testo della query di ricerca, qualsiasi cosa l'utente inizi a digitare, e esegue una query al fornitore di contenuti che contiene i tuoi suggerimenti.
2. Il tuo fornitore di contenuti restituisce un Cursor che punta a tutti i suggerimenti che corrispondono al testo della query di ricerca.
3. Il sistema mostra l'elenco dei suggerimenti forniti da Cursor.

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

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

La classe SearchRecentSuggestionsProvider che estendi per il tuo fornitore di contenuti svolge automaticamente il lavoro nei passaggi precedenti, quindi c'è poco codice da scrivere.

Creare un fornitore di contenuti

Il fornitore di contenuti necessario per i suggerimenti di query recenti è un'implementazione di SearchRecentSuggestionsProvider. Questa classe fa tutto per te. Ti basta scrivere un costruttore di classe che esegue una riga di codice.

Ad esempio, ecco un'implementazione completa di un content provider per i suggerimenti di query recenti:

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

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

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() trasmette il nome dell'autorità di ricerca e una modalità di database. L'autorità di ricerca può essere qualsiasi stringa univoca, ma la best practice è utilizzare un nome completo per il tuo fornitore di contenuti, ad esempio il nome del pacchetto seguito dal nome della classe del fornitore. Ad esempio, "com.example.MySuggestionProvider".

La modalità Database deve includere DATABASE_MODE_QUERIES e può includere facoltativamente 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:

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

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 classe SearchRecentSuggestionsProvider e nella configurazione di ricerca. Per esempio:

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

Modificare la configurazione di ricerca

Per configurare il sistema in modo che utilizzi il tuo provider di suggerimenti, aggiungi gli attributi android:searchSuggestAuthority e android:searchSuggestSelection all'elemento <searchable> nel file di configurazione ricercabile. Per 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 tuo 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: " ?". Si tratta di un segnaposto per l'argomento di selezione SQLite e viene sostituito automaticamente dal testo della query inserito dall'utente.

Salvare le query

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

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

@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à di database dichiarate dal tuo content provider.

Il metodo saveRecentQuery() accetta 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à a 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 per le query recenti. Per cancellare la cronologia delle query, chiama clearHistory(). Ad esempio:

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

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

Esegui questa operazione da un elemento di menu, un elemento delle preferenze o un pulsante "Cancella cronologia delle ricerche" a tua scelta. Fornisci una finestra di dialogo di conferma per verificare che l'utente voglia eliminare la cronologia delle ricerche.