Aggiungi suggerimenti di ricerca personalizzati

Prova Compose

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

Barra di ricerca →

Puoi fornire suggerimenti di ricerca basati sulle query di ricerca recenti nella finestra di dialogo di ricerca o nel widget di ricerca di Android. 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 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, l'attività ricercabile riceve un intent ACTION_SEARCH con il suggerimento come query di ricerca che l'attività ricercabile gestisce già.

Per fornire suggerimenti per le query recenti, devi:

• Implementare un'attività ricercabile.
• Creare un fornitore di contenuti che estenda SearchRecentSuggestionsProvider e dichiararlo nel manifest dell'applicazione.
• Modificare la configurazione ricercabile con informazioni sul fornitore di contenuti che fornisce i suggerimenti di ricerca.
• Salvare le query nel 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 di ricerca sotto la finestra di dialogo o il widget di ricerca. Devi fornire l'origine da cui il sistema recupera i suggerimenti.

Quando il sistema identifica 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, qualunque cosa l'utente inizi a digitare, e esegue una query sul fornitore di contenuti che contiene i tuoi suggerimenti.
2. Il fornitore di contenuti restituisce un Cursor che punta a tutti i suggerimenti che corrispondono al testo della query di ricerca.
3. Il sistema visualizza l'elenco dei suggerimenti forniti da Cursor.

Una volta visualizzati i suggerimenti per le query recenti, potrebbero verificarsi le seguenti situazioni:

• Se l'utente digita un altro tasto o modifica la query in qualsiasi modo, 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 all'attività ricercabile utilizzando l'intent normale ACTION_SEARCH.
• Se l'utente seleziona un suggerimento, all'attività ricercabile viene inviato un intent ACTION_SEARCH utilizzando il testo suggerito come query.

La classe SearchRecentSuggestionsProvider che estendi per il fornitore di contenuti esegue automaticamente il lavoro nei passaggi precedenti, quindi non devi scrivere molto codice.

Creare un fornitore di contenuti

Il fornitore di contenuti necessario per i suggerimenti per le query recenti è un'implementazione di SearchRecentSuggestionsProvider. Questa classe fa tutto per te. Devi solo scrivere un costruttore di classe che esegua una riga di codice.

Ad esempio, ecco un'implementazione completa di un fornitore di contenuti per i suggerimenti per le 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() 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 è utilizzare un nome completo per il fornitore di contenuti, ad esempio il nome del pacchetto seguito dal nome della classe del fornitore. Ad esempio, "com.example.MySuggestionProvider".

La modalità di 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, consulta 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 manifest dell'applicazione con la stessa stringa di autorità utilizzata nella classe SearchRecentSuggestionsProvider e nella configurazione ricercabile. Ad esempio:

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

Modificare la configurazione ricercabile

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

Salvare le query

Per popolare la raccolta di query recenti, aggiungi ogni query ricevuta dall'attività ricercabile a SearchRecentSuggestionsProvider. Per farlo, crea un'istanza di SearchRecentSuggestions e chiama saveRecentQuery() ogni volta che l'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 fornitore di contenuti.

Il metodo saveRecentQuery() accetta la stringa della 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 abiliti la modalità a due righe per i suggerimenti di ricerca con DATABASE_MODE_2LINES. Se abiliti la modalità a due righe, il testo della query corrisponde alla seconda riga quando il sistema cerca i suggerimenti corrispondenti.

Cancellare 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". Fornisci una finestra di dialogo di conferma per verificare che l'utente voglia eliminare la cronologia delle ricerche.