Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiungi suggerimenti di ricerca personalizzati

Quando utilizzi la finestra di dialogo di ricerca o il widget di ricerca di Android, puoi fornire suggerimenti di ricerca personalizzati creati a partire dai dati della tua app. Ad esempio, se la tua app è un dizionario, puoi suggerire parole del dizionario che corrispondono al testo inserito nel campo di ricerca prima che l'utente finisca di inserire la query. Questi suggerimenti sono preziosi perché possono prevedere in modo efficace ciò che l'utente vuole e fornire un accesso immediato. La figura 1 mostra un esempio di una finestra di dialogo di ricerca con suggerimenti personalizzati.

Una volta forniti i suggerimenti personalizzati, puoi renderli disponibili anche nella casella di ricerca rapida a livello di sistema, fornendo l'accesso ai tuoi contenuti dall'esterno della tua app.

Prima di aggiungere suggerimenti personalizzati, implementa la finestra di dialogo di ricerca di Android o un widget di ricerca per le ricerche nella tua app. Consulta Creare un'interfaccia di ricerca e Fornitori di contenuti.

Nozioni di base

Figura 1. Screenshot di una finestra di dialogo di ricerca con suggerimenti di ricerca personalizzati.

Quando l'utente seleziona un suggerimento personalizzato, il sistema invia un Intent alla tua attività ricercabile. A differenza di una normale query di ricerca che invia un intent con l'azione ACTION_SEARCH, puoi definire i tuoi suggerimenti personalizzati in modo che utilizzino ACTION_VIEW o qualsiasi altra azione di intent e includere anche dati pertinenti al suggerimento selezionato. Nell'esempio del dizionario, quando l'utente seleziona un suggerimento, l'app può aprire immediatamente la definizione della parola, anziché cercare corrispondenze nel dizionario.

Per fornire suggerimenti personalizzati, segui questi passaggi:

Implementa un'attività di ricerca di base, come descritto in Creare un'interfaccia di ricerca.
Modifica la configurazione di ricerca con informazioni sul fornitore di contenuti che fornisce suggerimenti personalizzati.
Crea una tabella, ad esempio in un SQLiteDatabase, per i tuoi suggerimenti e formattala con le colonne richieste.
Crea un fornitore di contenuti che abbia accesso alla tabella dei suggerimenti e dichiara il fornitore nel file manifest.
Dichiara il tipo di Intent da inviare quando l'utente seleziona un suggerimento, inclusi un'azione personalizzata e dati personalizzati.

Proprio come il sistema Android mostra la finestra di dialogo di ricerca, mostra anche i suggerimenti per le ricerche. Devi avere un fornitore di contenuti da cui il sistema possa recuperare i tuoi suggerimenti. Leggi Fornitori di contenuti per scoprire come creare un fornitore di contenuti.

Quando il sistema identifica che la tua attività è ricercabile e fornisce suggerimenti di ricerca, la seguente procedura viene eseguita quando l'utente inserisce una query:

Il sistema prende il testo della query di ricerca, ovvero tutto ciò che è stato inserito finora, ed esegue una query al tuo fornitore di contenuti che gestisce i suggerimenti.
Il tuo fornitore di contenuti restituisce un Cursor che rimanda a tutti i suggerimenti pertinenti al testo della query di ricerca.
Il sistema mostra l'elenco dei suggerimenti forniti da Cursor.

Una volta visualizzati i suggerimenti personalizzati, potrebbe verificarsi quanto segue:

Se l'utente inserisce un'altra lettera o modifica la query in qualsiasi modo, i passaggi precedenti vengono ripetuti e l'elenco dei suggerimenti viene aggiornato di conseguenza.
Se l'utente esegue la ricerca, i suggerimenti vengono ignorati e la ricerca viene inviata alla tua attività ricercabile utilizzando l'intent ACTION_SEARCH normale.
Se l'utente seleziona un suggerimento, viene inviato un intent all'attività di ricerca, che contiene un'azione personalizzata e dati personalizzati in modo che la tua app possa aprire i contenuti suggeriti.

Modificare la configurazione di ricerca

Per aggiungere il supporto per i suggerimenti personalizzati, aggiungi l'attributo android:searchSuggestAuthority all'elemento <searchable> nel file di configurazione ricercabile, 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Potresti aver bisogno di attributi aggiuntivi, a seconda del tipo di intent che associ a ogni suggerimento e di come vuoi formattare le query per il tuo fornitore di contenuti. Gli altri attributi facoltativi sono descritti nelle sezioni seguenti.

Creare un fornitore di contenuti

Per creare un fornitore di contenuti per i suggerimenti personalizzati, consulta prima la sezione Fornitori di contenuti per scoprire come creare un fornitore di contenuti. Un fornitore di contenuti per i suggerimenti personalizzati è simile a qualsiasi altro fornitore di contenuti. Tuttavia, per ogni suggerimento fornito, la riga corrispondente nel Cursor deve includere colonne specifiche che il sistema comprende e utilizza per formattare i suggerimenti.

Quando l'utente inserisce del testo nella finestra di dialogo di ricerca o nel widget di ricerca, il sistema interroga il tuo fornitore di contenuti per ottenere suggerimenti chiamando query() ogni volta che viene inserita una lettera. Nell'implementazione di query(), il tuo fornitore di contenuti deve cercare nei dati dei suggerimenti e restituire un Cursor che rimanda alle righe che ritiene siano buoni suggerimenti.

I dettagli sulla creazione di un fornitore di contenuti per i suggerimenti personalizzati sono descritti nelle due sezioni seguenti:

Gestire la query di suggerimento: Come il sistema invia le richieste al tuo fornitore di contenuti e come gestirle.
Creare una tabella dei suggerimenti: Come definire le colonne che il sistema si aspetta in Cursor restituito con ogni query.

Gestire la query di suggerimento

Quando il sistema richiede suggerimenti al tuo fornitore di contenuti, chiama il metodo query() del fornitore di contenuti. Implementa questo metodo per cercare i dati dei suggerimenti e restituire un Cursor che punta ai suggerimenti che ritieni pertinenti.

Ecco un riepilogo dei parametri che il sistema passa al tuo metodo query(), elencati in ordine:

uri: Sempre un contenuto Uri, formattato come segue:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Il comportamento predefinito prevede che il sistema passi questo URI e aggiunga il testo della query:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Il testo della query alla fine è codificato utilizzando le regole di codifica URI, quindi potresti doverlo decodificare prima di eseguire una ricerca.

La parte optional.suggest.path è inclusa nell'URI solo se imposti un percorso di questo tipo nel file di configurazione ricercabile con l'attributo android:searchSuggestPath. È necessario solo se utilizzi lo stesso fornitore di contenuti per più attività ricercabili. Se è così, disambigua l'origine della query di suggerimento.

Nota: SUGGEST_URI_PATH_QUERY non è la stringa letterale fornita nell'URI, ma una costante. Utilizzalo se devi fare riferimento a questo percorso.
projection: Sempre null.
selection: Il valore fornito nell'attributo android:searchSuggestSelection del file di configurazione ricercabile o null se non dichiari l'attributo android:searchSuggestSelection. La sezione seguente approfondisce questo argomento.
selectionArgs: Contiene la query di ricerca come primo e unico elemento dell'array se dichiari l'attributo android:searchSuggestSelection nella configurazione di ricerca. Se non dichiari android:searchSuggestSelection, questo parametro è nullo. La sezione seguente approfondisce questo argomento.
sortOrder: Sempre null.

Il sistema può inviarti il testo della query di ricerca in due modi. Il modo predefinito è che il testo della query venga incluso come ultimo percorso dell'URI dei contenuti passato nel parametro uri. Tuttavia, se includi un valore di selezione nell'attributo android:searchSuggestSelection della configurazione di ricerca, il testo della query viene passato come primo elemento dell'array di stringhe selectionArgs. Queste due opzioni sono descritte di seguito.

Recupera la query nell'URI

Per impostazione predefinita, la query viene aggiunta come ultimo segmento del parametro uri, ovvero un oggetto Uri. Per recuperare il testo della query in questo caso, utilizza getLastPathSegment(), come mostrato nell'esempio seguente:

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

String query = uri.getLastPathSegment().toLowerCase();

Restituisce l'ultimo segmento di Uri, ovvero il testo della query inserito dall'utente.

Ottieni la query negli argomenti di selezione

Anziché utilizzare l'URI, potrebbe essere più sensato che il tuo metodo query() riceva tutto ciò di cui ha bisogno per eseguire la ricerca e che i parametri selection e selectionArgs contengano i valori appropriati. In questo caso, aggiungi l'attributo android:searchSuggestSelection alla configurazione ricercabile con la stringa di selezione SQLite. Nella stringa di selezione, includi un punto interrogativo (?) come segnaposto per la query di ricerca effettiva. Il sistema chiama query() con la stringa di selezione come parametro selection e la query di ricerca come primo elemento dell'array selectionArgs.

Ad esempio, ecco come potresti formare l'attributo android:searchSuggestSelection per creare un'istruzione di ricerca full-text:

<?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.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Con questa configurazione, il metodo query() fornisce il parametro selection come "word MATCH ?" e il parametro selectionArgs come query di ricerca. Quando li passi a un metodo query() SQLite come rispettivi argomenti, vengono sintetizzati insieme, il che significa che il punto interrogativo viene sostituito dal testo della query. Se ricevi query di suggerimento in questo modo e devi aggiungere caratteri jolly al testo della query, aggiungili come prefisso o suffisso al parametro selectionArgs, perché questo valore è racchiuso tra virgolette e inserito al posto del punto interrogativo.

Un altro attributo nell'esempio precedente è android:searchSuggestIntentAction, che definisce l'azione di intent inviata con ogni intent quando l'utente seleziona un suggerimento. Questo argomento viene trattato più nel dettaglio nella sezione Dichiarare un intent per i suggerimenti.

Suggerimento: se non vuoi definire una clausola di selezione nell'attributo android:searchSuggestSelection, ma vuoi comunque ricevere il testo della query nel parametro selectionArgs, fornisci un valore non nullo per l'attributo android:searchSuggestSelection. In questo modo, la query passa selectionArgs e puoi ignorare il parametro selection. In questo modo, puoi definire la clausola di selezione effettiva a un livello inferiore, in modo che il tuo fornitore di contenuti non debba gestirla.

Creare una tabella dei suggerimenti

Quando restituisci i suggerimenti al sistema con un Cursor, il sistema prevede colonne specifiche in ogni riga. Indipendentemente dal fatto che tu memorizzi i dati dei suggerimenti in un database SQLite sul dispositivo, in un database su un server web o in un altro formato sul dispositivo o sul web, formatta i suggerimenti come righe in una tabella e presentali con un Cursor.

Nota:se i suggerimenti di ricerca non sono memorizzati in un formato di tabella, ad esempio una tabella SQLite, utilizzando le colonne richieste dal sistema, puoi cercare corrispondenze nei dati dei suggerimenti e poi formattarli nella tabella necessaria per ogni richiesta. Per farlo, crea un MatrixCursor utilizzando i nomi delle colonne obbligatori, quindi aggiungi una riga per ogni suggerimento utilizzando addRow(Object[]). Restituisci il prodotto finale dal metodo query() del tuo fornitore di contenuti.

Il sistema comprende diverse colonne, ma solo due sono obbligatorie:

_ID: Un ID riga intero univoco per ogni suggerimento. Il sistema richiede queste informazioni per presentare suggerimenti in un ListView.
SUGGEST_COLUMN_TEXT_1: La stringa presentata come suggerimento.

Le seguenti colonne sono tutte facoltative. La maggior parte viene discussa più nel dettaglio nelle sezioni seguenti.

SUGGEST_COLUMN_TEXT_2: Una stringa. Se il tuo Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato a due righe. La stringa in questa colonna viene visualizzata come una seconda riga di testo più piccola sotto il testo del suggerimento principale. Può essere nullo o vuoto per indicare che non è presente alcun testo secondario.
SUGGEST_COLUMN_ICON_1: Una stringa URI di una risorsa disegnabile, di contenuti o di un file. Se il tuo Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona disegnabile sul lato sinistro. Questo può essere null o zero per indicare che non è presente alcuna icona in questa riga.
SUGGEST_COLUMN_ICON_2: Una stringa URI di una risorsa disegnabile, di contenuti o di un file. Se il tuo Cursor include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona sul lato destro. Può essere null o zero per indicare che non è presente alcuna icona in questa riga.
SUGGEST_COLUMN_INTENT_ACTION: Una stringa di azione intent. Se questa colonna esiste e contiene un valore nella riga specificata, l'azione definita qui viene utilizzata per formare l'intent del suggerimento. Se l'elemento non viene fornito, l'azione viene eseguita dal campo android:searchSuggestIntentAction nella configurazione di ricerca. Se l'azione è la stessa per tutti i suggerimenti, è più efficiente specificarla utilizzando android:searchSuggestIntentAction e omettere questa colonna.
SUGGEST_COLUMN_INTENT_DATA: Una stringa URI dati. Se questa colonna esiste e contiene un valore nella riga specificata, questi dati vengono utilizzati per formare l'intent del suggerimento. Se l'elemento non viene fornito, i dati vengono presi dal campo android:searchSuggestIntentData nella configurazione di ricerca. Se non viene fornita alcuna origine, il campo dati dell'intent è null. Se i dati sono gli stessi per tutti i suggerimenti o possono essere descritti utilizzando una parte costante e un ID specifico, è più efficiente specificarli utilizzando android:searchSuggestIntentData e omettendo questa colonna.
SUGGEST_COLUMN_INTENT_DATA_ID: Una stringa di percorso URI. Se questa colonna esiste e contiene un valore nella riga specificata, "/" e questo valore vengono aggiunti al campo dati nell'intent. Utilizza questa opzione solo se il campo dati specificato dall'attributo android:searchSuggestIntentData nella configurazione ricercabile è già impostato su una stringa di base appropriata.
SUGGEST_COLUMN_INTENT_EXTRA_DATA: Dati arbitrari. Se questa colonna esiste e contiene un valore in una determinata riga, si tratta dei dati extra utilizzati per formare l'intent del suggerimento. Se non viene fornito, il campo di dati extra dell'intent è nullo. Questa colonna consente ai suggerimenti di fornire dati aggiuntivi inclusi come extra nella chiave EXTRA_DATA_KEY dell'intent.
SUGGEST_COLUMN_QUERY: Se questa colonna esiste e questo elemento esiste nella riga specificata, questi sono i dati utilizzati per formare la query del suggerimento, inclusi come extra nella chiave QUERY dell'intent. È obbligatorio se l'azione del suggerimento è ACTION_SEARCH, ma facoltativo altrimenti.
SUGGEST_COLUMN_SHORTCUT_ID: Utilizzato solo per fornire suggerimenti per la casella di ricerca rapida. Questa colonna indica se un suggerimento di ricerca deve essere memorizzato come scorciatoia e se deve essere convalidato. Le scorciatoie vengono create in genere quando l'utente tocca un suggerimento nella casella di ricerca rapida. Se manca, il risultato viene memorizzato come scorciatoia e non viene mai aggiornato. Se impostato su SUGGEST_NEVER_MAKE_SHORTCUT, il risultato non viene memorizzato come scorciatoia. In caso contrario, l'ID della scorciatoia viene utilizzato per controllare un suggerimento aggiornato utilizzando SUGGEST_URI_PATH_SHORTCUT.
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING: Utilizzato solo per fornire suggerimenti per la casella di ricerca rapida. Questa colonna specifica che deve essere mostrato un indicatore di caricamento anziché un'icona di SUGGEST_COLUMN_ICON_2 mentre la scorciatoia di questo suggerimento viene aggiornata nella casella di ricerca rapida.

La maggior parte di queste colonne viene discussa più avanti nelle sezioni seguenti.

Dichiarare un intent per i suggerimenti

Quando l'utente seleziona un suggerimento dall'elenco visualizzato sotto la finestra di dialogo o il widget di ricerca, il sistema invia un intent Intent personalizzato alla tua attività ricercabile. Devi definire l'azione e i dati per l'intent.

Dichiarare l'azione intent

L'azione di intent più comune per un suggerimento personalizzato è ACTION_VIEW, che è appropriata quando vuoi aprire qualcosa, come la definizione di una parola, i dati di contatto di una persona o una pagina web. Tuttavia, l'azione di intent può essere qualsiasi altra azione e può essere diversa per ogni suggerimento.

A seconda che tu voglia che tutti i suggerimenti utilizzino la stessa azione di intent, puoi definire l'azione in due modi:

Utilizza l'attributo android:searchSuggestIntentAction del file di configurazione in cui è possibile eseguire ricerche per definire l'azione per tutti i suggerimenti, 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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW" >
</searchable>

Utilizza la colonna SUGGEST_COLUMN_INTENT_ACTION per definire l'azione per i singoli suggerimenti. Per farlo, aggiungi la colonna SUGGEST_COLUMN_INTENT_ACTION alla tabella dei suggerimenti e, per ogni suggerimento, inserisci l'azione da utilizzare, ad esempio "android.intent.action.VIEW".

Puoi anche combinare queste due tecniche. Ad esempio, puoi includere l'attributo android:searchSuggestIntentAction con un'azione da utilizzare con tutti i suggerimenti per impostazione predefinita, poi sostituire questa azione per alcuni suggerimenti dichiarando un'azione diversa nella colonna SUGGEST_COLUMN_INTENT_ACTION. Se non includi un valore nella colonna SUGGEST_COLUMN_INTENT_ACTION, viene utilizzato l'intent fornito nell'attributo android:searchSuggestIntentAction.

Nota:se non includi l'attributo android:searchSuggestIntentAction nella configurazione di ricerca, devi obbligatoriamente includere un valore nella colonna SUGGEST_COLUMN_INTENT_ACTION per ogni suggerimento, altrimenti l'intent non va a buon fine.

Dichiarare i dati sugli intenti

Quando l'utente seleziona un suggerimento, l'attività ricercabile riceve l'intent con l'azione che definisci, come descritto nella sezione precedente, ma l'intent deve anche contenere dati per l'attività per identificare quale suggerimento è selezionato. Nello specifico, i dati devono essere univoci per ogni suggerimento, ad esempio l'ID riga del suggerimento nella tabella SQLite. Quando viene ricevuto l'intent, puoi recuperare i dati allegati con getData() o getDataString().

Puoi definire i dati inclusi nell'intent in due modi:

Definisci i dati per ogni suggerimento all'interno della colonna SUGGEST_COLUMN_INTENT_DATA della tabella dei suggerimenti.
Fornisci tutte le informazioni necessarie per ogni intento nella tabella dei suggerimenti includendo la colonna SUGGEST_COLUMN_INTENT_DATA e inserendo dati univoci per ogni riga. I dati di questa colonna sono associati all'intent esattamente come lo definisci in questa colonna. Puoi recuperarlo con getData() o getDataString().

Suggerimento: in genere è più facile utilizzare l'ID riga della tabella come dati di intent, perché è sempre univoco. Il modo più semplice per farlo è utilizzare il nome della colonna SUGGEST_COLUMN_INTENT_DATA come alias per la colonna ID riga.
Frammenta un URI di dati in due parti: la parte comune a tutti i suggerimenti e la parte univoca per ogni suggerimento. Inserisci queste parti nell'attributo android:searchSuggestintentData della configurazione ricercabile e nella colonna SUGGEST_COLUMN_INTENT_DATA_ID della tabella dei suggerimenti, rispettivamente.
L'esempio seguente mostra come dichiarare la parte dell'URI comune a tutti i suggerimenti nell'attributo android:searchSuggestIntentData della configurazione di ricerca:
```
  <?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.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW"
      android:searchSuggestIntentData="content://com.example/datatable" >
  </searchable>
  
```
Includi il percorso finale per ogni suggerimento, ovvero la parte univoca, nella colonna SUGGEST_COLUMN_INTENT_DATA_ID della tabella dei suggerimenti. Quando l'utente seleziona un suggerimento, il sistema prende la stringa da android:searchSuggestIntentData, aggiunge una barra (/) e poi aggiunge il rispettivo valore dalla colonna SUGGEST_COLUMN_INTENT_DATA_ID per formare un URI completo dei contenuti. Puoi quindi recuperare Uri con getData().

Aggiungere altri dati

Se devi esprimere ulteriori informazioni con l'intent, puoi aggiungere un'altra colonna della tabella, ad esempio SUGGEST_COLUMN_INTENT_EXTRA_DATA, che può memorizzare informazioni aggiuntive sul suggerimento. I dati salvati in questa colonna vengono inseriti in EXTRA_DATA_KEY dell'extra bundle dell'intent.

Gestire l'intent

Dopo aver fornito suggerimenti di ricerca personalizzati con intent personalizzati, devi fare in modo che la tua attività ricercabile gestisca questi intent quando l'utente seleziona un suggerimento. Questo si aggiunge alla gestione dell'ACTION_SEARCHintent, che la tua attività ricercabile già svolge. Ecco un esempio di come puoi gestire gli intent durante il callback onCreate() dell'attività:

Kotlin

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Java

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

In questo esempio, l'azione di intent è ACTION_VIEW e i dati contengono un URI completo che punta all'elemento suggerito, come sintetizzato dalla stringa android:searchSuggestIntentData e dalla colonna SUGGEST_COLUMN_INTENT_DATA_ID. L'URI viene quindi passato al metodo locale showResult() che esegue query sul content provider per l'elemento specificato dall'URI.

Nota:non devi aggiungere un filtro per intent al file manifest di Android per l'azione intent che hai definito con l'attributo android:searchSuggestIntentAction o la colonna SUGGEST_COLUMN_INTENT_ACTION. Il sistema apre l'attività ricercabile per nome per fornire l'intent del suggerimento, quindi l'attività non deve dichiarare l'azione accettata.

Riscrivere il testo della query

Per impostazione predefinita, se l'utente naviga nell'elenco dei suggerimenti utilizzando controlli direzionali, ad esempio con una trackball o un D-pad, il testo della query non viene aggiornato. Tuttavia, puoi riscrivere temporaneamente il testo della query dell'utente così come appare nella casella di testo con una query che corrisponde al suggerimento in primo piano. In questo modo, l'utente può vedere la query suggerita e selezionare la casella di ricerca per modificarla prima di inviarla come ricerca.

Puoi riscrivere il testo della query nei seguenti modi:

Aggiungi l'attributo android:searchMode alla configurazione di ricerca con il valore "queryRewriteFromText". In questo caso, i contenuti della colonna SUGGEST_COLUMN_TEXT_1 del suggerimento vengono utilizzati per riscrivere il testo della query.
Aggiungi l'attributo android:searchMode alla configurazione\ di ricerca con il valore "queryRewriteFromData". In questo caso, i contenuti della colonna SUGGEST_COLUMN_INTENT_DATA del suggerimento vengono utilizzati per riscrivere il testo della query. Utilizza questa opzione solo con URI o altri formati di dati destinati a essere visibili agli utenti, ad esempio gli URL HTTP. Non utilizzare schemi URI interni per riscrivere la query in questo modo.
Fornisci una stringa di testo della query univoca nella colonna SUGGEST_COLUMN_QUERY della tabella dei suggerimenti. Se questa colonna è presente e contiene un valore per il suggerimento corrente, viene utilizzata per riscrivere il testo della query e sostituire una delle implementazioni precedenti.

Mostrare i suggerimenti di ricerca nella casella di ricerca rapida

Una volta configurata l'app per fornire suggerimenti di ricerca personalizzati, renderli disponibili nella casella di ricerca rapida accessibile a livello globale è semplice come modificare la configurazione ricercabile in modo da includere android:includeInGlobalSearch con il valore "true".

L'unico scenario in cui è necessario un lavoro aggiuntivo è quando il tuo fornitore di contenuti richiede un'autorizzazione di lettura. In questo caso, devi aggiungere un elemento <path-permission> affinché il fornitore conceda l'accesso in lettura della casella di ricerca rapida al tuo fornitore di contenuti, come mostrato nell'esempio seguente:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

In questo esempio, il fornitore limita l'accesso in lettura e scrittura ai contenuti. L'elemento <path-permission> modifica la limitazione concedendo l'accesso in lettura ai contenuti all'interno del prefisso del percorso "/search_suggest_query" quando esiste l'autorizzazione "android.permission.GLOBAL_SEARCH". In questo modo, la casella di ricerca rapida può interrogare il tuo fornitore di contenuti per ricevere suggerimenti.

Se il tuo fornitore di contenuti non applica le autorizzazioni di lettura, la casella di ricerca rapida la legge per impostazione predefinita.

Attivare i suggerimenti su un dispositivo

Per impostazione predefinita, le app non sono abilitate a fornire suggerimenti nella casella di ricerca rapida, anche se sono configurate per farlo. L'utente sceglie se includere i suggerimenti della tua app nella casella di ricerca rapida aprendo Elementi ricercabili, che si trova in Impostazioni > Ricerca, e attivando la tua app come elemento ricercabile.

Ogni app disponibile per la casella di ricerca rapida ha una voce nella pagina delle impostazioni Elementi ricercabili. La voce include il nome dell'app e una breve descrizione dei contenuti ricercabili dall'app e resi disponibili per i suggerimenti nella casella di ricerca rapida. Per definire il testo della descrizione per l'app ricercabile, aggiungi l'attributo android:searchSettingsDescription alla configurazione ricercabile, come mostrato nel seguente 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.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

Rendi la stringa per android:searchSettingsDescription il più concisa possibile e indica i contenuti ricercabili. Ad esempio, "Artisti, album e brani" per un'app di musica o "Note salvate" per un'app per prendere appunti. Fornire questa descrizione è importante affinché l'utente sappia che tipo di suggerimenti vengono forniti. Includi sempre questo attributo quando android:includeInGlobalSearch è true.

Poiché l'utente deve visitare il menu delle impostazioni per attivare i suggerimenti di ricerca per la tua app, se la ricerca è un aspetto importante della tua app, valuta come comunicarlo agli utenti. Ad esempio, potresti fornire una nota la prima volta che un utente avvia l'app che spiega come attivare i suggerimenti di ricerca per la casella di ricerca rapida.

Gestire le scorciatoie dei suggerimenti della casella di ricerca rapida

I suggerimenti selezionati dall'utente nella casella di ricerca rapida possono essere trasformati automaticamente in scorciatoie. Questi sono suggerimenti che il sistema copia dal tuo fornitore di contenuti in modo da potervi accedere rapidamente senza dover interrogare nuovamente il fornitore di contenuti.

Per impostazione predefinita, questa opzione è attivata per tutti i suggerimenti recuperati dalla casella di ricerca rapida, ma se i dati dei suggerimenti cambiano nel tempo, puoi richiedere l'aggiornamento delle scorciatoie. Ad esempio, se i tuoi suggerimenti si riferiscono a dati dinamici, come lo stato di presenza di un contatto, richiedi che le scorciatoie dei suggerimenti vengano aggiornate quando vengono mostrate all'utente. A tal fine, includi SUGGEST_COLUMN_SHORTCUT_ID nella tabella dei suggerimenti. Puoi utilizzare questa colonna per configurare il comportamento della scorciatoia per ogni suggerimento in uno dei seguenti modi:

Fai in modo che la casella di ricerca rapida interroghi di nuovo il tuo fornitore di contenuti per ottenere una versione aggiornata della scorciatoia per i suggerimenti.

Fornisci un valore nella colonna SUGGEST_COLUMN_SHORTCUT_ID affinché la query venga eseguita di nuovo per ottenere una versione aggiornata ogni volta che viene visualizzata la scorciatoia. La scorciatoia viene visualizzata rapidamente con i dati disponibili più recentemente fino a quando non viene restituita la query di aggiornamento, a quel punto il suggerimento viene aggiornato con le nuove informazioni. La query di aggiornamento viene inviata al tuo fornitore di contenuti con un percorso URI di SUGGEST_URI_PATH_SHORTCUT anziché SUGGEST_URI_PATH_QUERY.

Fai in modo che Cursor restituito contenga un suggerimento che utilizzi le stesse colonne del suggerimento originale o sia vuoto, a indicare che la scorciatoia non è più valida. In questo caso, il suggerimento scompare e la scorciatoia viene rimossa.

Se un suggerimento si riferisce a dati che possono richiedere più tempo per l'aggiornamento, ad esempio un aggiornamento basato sulla rete, puoi anche aggiungere la colonna SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING alla tabella dei suggerimenti con un valore true per mostrare un indicatore di caricamento per l'icona a destra finché l'aggiornamento non è completato. Qualsiasi valore diverso da true non mostra l'indicatore di avanzamento.
Impedire che il suggerimento venga copiato in una scorciatoia.

Fornisci un valore di SUGGEST_NEVER_MAKE_SHORTCUT nella colonna SUGGEST_COLUMN_SHORTCUT_ID. In questo caso, il suggerimento non viene mai copiato in una scorciatoia. Questa operazione è necessaria solo se non vuoi assolutamente che venga visualizzato il suggerimento copiato in precedenza. Se fornisci un valore normale per la colonna, il suggerimento della scorciatoia viene visualizzato solo fino a quando non viene restituita la query di aggiornamento.
Consenti l'applicazione del comportamento predefinito delle scorciatoie.

Lascia vuoto il campo SUGGEST_COLUMN_SHORTCUT_ID per ogni suggerimento che non cambia e che può essere salvato come scorciatoia.

Se nessuno dei tuoi suggerimenti cambia mai, non hai bisogno della colonna SUGGEST_COLUMN_SHORTCUT_ID.

Informazioni sul ranking dei suggerimenti della casella di ricerca rapida

Una volta che hai reso disponibili i suggerimenti per le ricerche della tua app nella casella di ricerca rapida, il ranking della casella di ricerca rapida determina la modalità di visualizzazione dei suggerimenti per l'utente per una determinata query. Ciò potrebbe dipendere dal numero di altre app che hanno risultati per quella query e dalla frequenza con cui l'utente seleziona i tuoi risultati rispetto a quelli di altre app. Non esiste alcuna garanzia in merito al ranking dei suggerimenti o alla visualizzazione dei suggerimenti della tua app per una determinata query. In generale, fornire risultati di qualità aumenta la probabilità che i suggerimenti della tua app vengano forniti in una posizione in evidenza e le app che forniscono suggerimenti di bassa qualità hanno maggiori probabilità di essere classificate in una posizione inferiore o di non essere visualizzate.

Aggiungi suggerimenti di ricerca personalizzati Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Nozioni di base

Modificare la configurazione di ricerca

Creare un fornitore di contenuti

Gestire la query di suggerimento

Recupera la query nell'URI

Kotlin

Java

Ottieni la query negli argomenti di selezione

Creare una tabella dei suggerimenti

Dichiarare un intent per i suggerimenti

Dichiarare l'azione intent

Dichiarare i dati sugli intenti

Aggiungere altri dati

Gestire l'intent

Kotlin

Java

Riscrivere il testo della query

Mostrare i suggerimenti di ricerca nella casella di ricerca rapida

Attivare i suggerimenti su un dispositivo

Gestire le scorciatoie dei suggerimenti della casella di ricerca rapida

Informazioni sul ranking dei suggerimenti della casella di ricerca rapida

Aggiungi suggerimenti di ricerca personalizzati