Quando utilizzi il widget Ricerca o la finestra di dialogo 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 vuole l'utente e fornirgli accesso immediato. La Figura 1 mostra un esempio di finestra di ricerca con suggerimenti personalizzati.
Una volta forniti suggerimenti personalizzati, puoi anche renderli disponibili alla 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 gli articoli Creare un'interfaccia di ricerca e Fornitori di contenuti.
Nozioni di base
Quando l'utente seleziona un suggerimento personalizzato, il sistema invia un
Intent
alla tua
attività disponibile per la ricerca. A differenza di una normale query di ricerca che invia un intent con l'azione ACTION_SEARCH
, puoi invece definire i suggerimenti personalizzati da utilizzare ACTION_VIEW
o qualsiasi altra azione intent e includere anche i dati pertinenti al suggerimento selezionato. Nell'esempio del dizionario, quando l'utente seleziona un suggerimento, l'app può aprire immediatamente la definizione di quella parola, anziché cercare corrispondenze nel dizionario.
Per fornire suggerimenti personalizzati, procedi nel seguente modo:
- Implementa un'attività di ricerca di base, come descritto nella sezione Creare un'interfaccia di ricerca.
- Modifica la configurazione disponibile per la ricerca con informazioni sul fornitore di contenuti che fornisce suggerimenti personalizzati.
- Crea una tabella, ad esempio in un
SQLiteDatabase
, per i tuoi suggerimenti e formatta la tabella con le colonne obbligatorie. - Crea un provider di contenuti che abbia accesso alla tabella dei suggerimenti e dichiara il provider nel tuo manifest.
- Dichiara il tipo di
Intent
da inviare quando l'utente seleziona un suggerimento, inclusi un'azione personalizzata e dati personalizzati.
Il sistema Android mostra la finestra di dialogo di ricerca, così come mostra i suggerimenti di ricerca. Hai bisogno di un fornitore di contenuti dal quale il sistema può recuperare i tuoi suggerimenti. Consulta Fornitori di contenuti per scoprire come creare un fornitore di contenuti.
Quando il sistema identifica che la tua attività è disponibile per la ricerca e fornisce suggerimenti per le ricerche, quando l'utente inserisce una query viene eseguita la seguente procedura:
- Il sistema acquisisce il testo della query di ricerca, ovvero ciò che è stato inserito fino a quel momento, ed esegue una query al fornitore di contenuti, che gestisce i tuoi suggerimenti.
- Il tuo fornitore di contenuti restituisce un
Cursor
che indirizza a tutti i suggerimenti pertinenti al testo della query di ricerca. - Il sistema mostra l'elenco di suggerimenti forniti da
Cursor
.
Una volta visualizzati i suggerimenti personalizzati, potrebbe verificarsi quanto segue:
- Se l'utente inserisce un'altra lettera o modifica in qualsiasi modo la query, i passaggi precedenti si ripetono e l'elenco dei suggerimenti si aggiorna di conseguenza.
- Se l'utente esegue la ricerca, i suggerimenti vengono ignorati e la ricerca viene inviata all'attività disponibile per la ricerca utilizzando il normale intent
ACTION_SEARCH
. - Se l'utente seleziona un suggerimento, viene inviato un intent alla tua attività disponibile per la ricerca, con un'azione personalizzata e dati personalizzati in modo che la tua app possa aprire i contenuti suggeriti.
Modifica la configurazione disponibile per la ricerca
Per aggiungere il supporto dei suggerimenti personalizzati, aggiungi l'attributo android:searchSuggestAuthority
all'elemento <searchable>
nel file di configurazione disponibile per la ricerca, 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 allegato a ciascun suggerimento e di come vuoi formattare le query al tuo fornitore di contenuti. Gli altri attributi facoltativi sono illustrati nelle sezioni seguenti.
Crea un fornitore di contenuti
Per creare un fornitore di contenuti per i suggerimenti personalizzati, consulta innanzitutto
Fornitori di contenuti
per informazioni su come creare un fornitore di contenuti. Un fornitore di contenuti per suggerimenti personalizzati
è simile a qualsiasi altro fornitore di contenuti. Tuttavia, per ogni suggerimento fornito, la rispettiva riga in 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 Ricerca, il sistema
chiede suggerimenti al fornitore di contenuti chiamando
query()
ogni volta che viene inserita una lettera. Nell'implementazione di query()
, il fornitore di contenuti deve cercare i dati relativi ai suggerimenti e restituire un Cursor
che indirizzi alle righe che ritiene siano buoni suggerimenti.
I dettagli sulla creazione di un fornitore di contenuti per suggerimenti personalizzati sono discussi nelle seguenti due sezioni:
- Gestire la query di suggerimento
- Il modo in cui il sistema invia richieste al tuo fornitore di contenuti e come gestirle.
- Creare una tabella di suggerimenti
- Come definire le colonne che il sistema prevede nel
Cursor
restituito con ogni query.
Gestire la query di suggerimento
Quando il sistema richiede suggerimenti al tuo fornitore di contenuti, richiama il metodo query()
del fornitore. Implementa questo metodo per cercare nei dati relativi ai suggerimenti e restituire un Cursor
che rimandi 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 è che il sistema passi questo URI e vi aggiunga il testo della query:
content://your.authority/optional.suggest.path/
SUGGEST_URI_PATH_QUERY
/puppiesIl testo della query alla fine è codificato utilizzando le regole di codifica dell'URI, quindi potrebbe essere necessario decodificarlo 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 disponibile per la ricerca con l'attributoandroid:searchSuggestPath
. È necessario solo se utilizzi lo stesso fornitore di contenuti per più attività disponibili per la ricerca. In questo caso, chiarisci l'origine della query di suggerimento.projection
- Sempre null.
selection
- Valore specificato nell'attributo
android:searchSuggestSelection
del file di configurazione disponibile per la ricerca oppure nullo se non dichiari l'attributoandroid:searchSuggestSelection
. La seguente sezione tratta questo aspetto in modo più approfondito.selectionArgs
- Contiene la query di ricerca come primo e unico elemento dell'array se dichiari l'attributo
android:searchSuggestSelection
nella configurazione disponibile per la ricerca. Se non dichiariandroid:searchSuggestSelection
, questo parametro è nullo. La seguente sezione tratta questo argomento in modo più approfondito.sortOrder
- Sempre null.
Il sistema può inviarti il testo della query di ricerca in due modi. Il metodo predefinito consente di includere il testo della query come ultimo percorso dell'URI dei contenuti trasmesso nel parametro uri
. Tuttavia, se includi un valore di selezione nell'attributo android:searchSuggestSelection
della configurazione ricercabile, il testo della query viene passato come primo elemento dell'array di stringhe selectionArgs
. Queste due opzioni sono
descritte di seguito.
Ottieni la query nell'URI
Per impostazione predefinita, la query viene aggiunta come ultimo segmento del parametro uri
, 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();
Questo restituisce l'ultimo segmento di Uri
, ovvero il testo della query inserito dall'utente.
Ottieni la query negli argomenti di selezione
Invece di utilizzare l'URI, potrebbe essere più opportuno che il tuo metodo query()
riceva tutto ciò di cui ha bisogno per eseguire la ricerca e potresti volere che i parametri selection
e selectionArgs
abbiano i valori appropriati. In questo caso, aggiungi l'attributo android:searchSuggestSelection
alla configurazione disponibile per la ricerca 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 nell'array selectionArgs
.
Ad esempio, ecco come potresti formare l'attributo android:searchSuggestSelection
per creare una dichiarazione di ricerca di testo completo:
<?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()
pubblica il parametro selection
come "word MATCH ?"
e il parametro selectionArgs
come query di ricerca. Quando passi questi elementi a un metodo
query()
SQLite, i rispettivi argomenti vengono sintetizzati
insieme, il che significa che il punto interrogativo viene sostituito con il testo della query. Se ricevi query di suggerimento in questo modo e devi aggiungere caratteri jolly al testo della query, aggiungili o anteponili 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 intent inviata con ciascun intent quando l'utente seleziona un suggerimento. Questo argomento verrà discusso ulteriormente nella sezione Dichiarare un intento di suggerimenti.
Crea una tabella di suggerimenti
Quando restituisci suggerimenti al sistema con un valore Cursor
, il sistema prevede colonne specifiche in ogni riga. Indipendentemente dal fatto che 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 di una tabella e presentali con un Cursor
.
Il sistema riconosce diverse colonne, ma ne sono obbligatorie solo due:
_ID
- Un ID riga di un numero intero univoco per ogni suggerimento. Il sistema richiede questa operazione 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 in dettaglio nelle sezioni seguenti.
SUGGEST_COLUMN_TEXT_2
- Una stringa. Se
Cursor
include questa colonna, tutti i suggerimenti vengono forniti in un formato a due righe. La stringa in questa colonna viene visualizzata come seconda riga di testo più piccola sotto il testo del suggerimento principale. Può essere nullo o vuoto per indicare l'assenza di testo secondario. SUGGEST_COLUMN_ICON_1
- Una stringa di risorse, contenuti o URI di file disegnabili. Se
Cursor
include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona disegnabile a sinistra. Può essere null o zero per indicare che non ci sono icone in questa riga. SUGGEST_COLUMN_ICON_2
- Una stringa di risorse, contenuti o URI di file disegnabili. Se
Cursor
include questa colonna, tutti i suggerimenti vengono forniti in un formato icona più testo con l'icona a destra. Può essere null o zero per indicare che non ci sono icone 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 disponibile per la ricerca. Se l'azione è la stessa per tutti i suggerimenti, è più efficiente specificarla utilizzandoandroid:searchSuggestIntentAction
e omettere questa colonna. SUGGEST_COLUMN_INTENT_DATA
- Una stringa URI di 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 recuperati dal campo
android:searchSuggestIntentData
nella configurazione disponibile per la ricerca. Se non viene fornita nessuna delle due origini, il campo dei dati dell'intent è nullo. Se i dati sono gli stessi per tutti i suggerimenti o se possono essere descritti utilizzando una parte costante e un ID specifico, è più efficiente specificarli utilizzandoandroid:searchSuggestIntentData
e omettere 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.
Da utilizzare solo se il campo dei dati specificato dall'attributo
android:searchSuggestIntentData
nella configurazione disponibile per la ricerca è 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, questi sono i dati aggiuntivi utilizzati per formare l'intent del suggerimento.
Se non viene specificato, il campo dei dati in eccesso dell'intent è nullo. Questa colonna consente ai suggerimenti di fornire dati aggiuntivi che sono inclusi come extra nella chiave
EXTRA_DATA_KEY
dell'intent. SUGGEST_COLUMN_QUERY
- Se la colonna esiste e questo elemento esiste nella riga specificata, questi sono i dati utilizzati per creare la query del suggerimento, inclusi come extra nella chiave
QUERY
dell'intent. È obbligatoria se l'azione del suggerimento èACTION_SEARCH
, altrimenti facoltativa. SUGGEST_COLUMN_SHORTCUT_ID
- Utilizzato solo quando fornisci suggerimenti per la Casella di ricerca rapida. Questa colonna indica se un suggerimento di ricerca deve essere archiviato come scorciatoia e se deve essere convalidato. In genere le scorciatoie vengono create quando l'utente tocca un suggerimento dalla Casella di ricerca rapida. Se mancante, il risultato viene memorizzato come scorciatoia e non viene mai aggiornato. Se viene impostato su
SUGGEST_NEVER_MAKE_SHORTCUT
, il risultato non viene archiviato come scorciatoia. In caso contrario, l'ID scorciatoia viene utilizzato per verificare la presenza di un suggerimento aggiornato utilizzandoSUGGEST_URI_PATH_SHORTCUT
. SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
- Utilizzato solo quando fornisci suggerimenti per la Casella di ricerca rapida. Questa colonna
specifica che è necessario mostrare una rotellina 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 è trattata in modo più approfondito nelle sezioni seguenti.
Dichiarare un intento di ricevere suggerimenti
Quando l'utente seleziona un suggerimento dall'elenco visualizzato nella finestra di dialogo o nel widget di ricerca, il sistema invia un Intent
personalizzato alla tua attività disponibile per la ricerca. Devi definire l'azione e i dati relativi all'intent.
Dichiara l'azione intent
L'azione più comune per intenzione relativa a 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 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 intent, puoi definire l'azione in due modi:
- Utilizza l'attributo
android:searchSuggestIntentAction
del file di configurazione disponibile per la ricerca 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 colonnaSUGGEST_COLUMN_INTENT_ACTION
alla tabella dei suggerimenti e, per ogni suggerimento, inserisci al suo interno 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 per tutti i suggerimenti per impostazione predefinita e poi ignorare 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
.
Dichiarare i dati sull'intenzione
Quando l'utente seleziona un suggerimento, la tua attività disponibile per la ricerca riceve l'intent con l'azione che definisci, come descritto nella sezione precedente, ma l'intent deve anche includere i dati della tua attività per identificare il suggerimento selezionato. In particolare, i dati devono essere univoci per ogni suggerimento, ad esempio l'ID riga del suggerimento nella tabella SQLite.
Quando l'intent viene ricevuto, puoi recuperare i dati allegati con getData()
o getDataString()
.
Puoi definire i dati inclusi con l'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 ciascun intent nella tabella dei suggerimenti includendo la colonna
SUGGEST_COLUMN_INTENT_DATA
e compilandola con i dati univoci per ogni riga. I dati di questa colonna sono associati all'intent esattamente come lo definisci in questa colonna. Puoi quindi recuperarlo congetData()
ogetDataString()
. - Frammenta un URI 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 disponibile per la ricerca e nella colonnaSUGGEST_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 disponibile per la 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 di ogni suggerimento (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 daandroid:searchSuggestIntentData
, aggiunge una barra (/) e poi aggiunge il rispettivo valore dalla colonnaSUGGEST_COLUMN_INTENT_DATA_ID
per formare un URI di contenuti completo. Puoi quindi recuperareUri
congetData()
.
Aggiungi altri dati
Se vuoi fornire ulteriori informazioni, puoi aggiungere un'altra colonna della tabella, come SUGGEST_COLUMN_INTENT_EXTRA_DATA
, che può memorizzare ulteriori informazioni sul suggerimento. I dati salvati in questa colonna vengono inseriti nel EXTRA_DATA_KEY
del bundle aggiuntivo dell'intent.
Gestire l'intent
Dopo aver fornito suggerimenti di ricerca personalizzati con intent personalizzati, avrai bisogno della tua attività disponibile per la ricerca per gestire questi intent quando l'utente seleziona un suggerimento. Questa operazione si aggiunge alla gestione dell'intent ACTION_SEARCH
, che avviene già nelle tue attività di ricerca. 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 intent è ACTION_VIEW
e i dati
portano un URI completo che punta all'elemento suggerito, come sintetizzato dalla
stringa android:searchSuggestIntentData
e
dalla colonna SUGGEST_COLUMN_INTENT_DATA_ID
. L'URI passa quindi al metodo showResult()
locale che invia una query al fornitore di contenuti per l'elemento specificato dall'URI.
Riscrivi 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 e modificarla prima di inviarla come ricerca.
Puoi riscrivere il testo della query nei seguenti modi:
- Aggiungi l'attributo
android:searchMode
alla configurazione disponibile per la ricerca con il valore"queryRewriteFromText"
. In questo caso, i contenuti della colonnaSUGGEST_COLUMN_TEXT_1
del suggerimento vengono utilizzati per riscrivere il testo della query. - Aggiungi l'attributo
android:searchMode
alla configurazione\ disponibile per la ricerca con il valore"queryRewriteFromData"
. In questo caso, i contenuti della colonnaSUGGEST_COLUMN_INTENT_DATA
del suggerimento vengono utilizzati per riscrivere il testo della query. Utilizzalo solo con URI o altri formati di dati visibili all'utente, come 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.
Mostra i suggerimenti di ricerca alla Casella di ricerca rapida
Dopo aver configurato la tua app in modo da fornire suggerimenti di ricerca personalizzati, per renderli disponibili nella Casella di ricerca rapida accessibile a livello globale è sufficiente modificare la tua configurazione disponibile per la ricerca per 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>
per consentire al provider di concedere alla Casella di ricerca rapida l'accesso in lettura al tuo fornitore di contenuti, come illustrato 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 provider 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"
. Questo consente l'accesso alla Casella di ricerca rapida in modo che possa chiedere suggerimenti al fornitore di contenuti.
Se il tuo fornitore di contenuti non applica le autorizzazioni di lettura, la Casella di ricerca rapida le legge per impostazione predefinita.
Attivare i suggerimenti su un dispositivo
Per impostazione predefinita, le app non sono in grado di fornire suggerimenti nella Casella di ricerca rapida, anche se sono configurate in tal modo. L'utente sceglie se includere suggerimenti della tua app nella Casella di ricerca rapida aprendo gli Elementi ricercabili, che si trovano in Impostazioni > Ricerca, e attivando la tua app come elemento disponibile per la ricerca.
Ogni app disponibile per la Casella di ricerca rapida è associata a una voce nella pagina di impostazioni Elementi ricercabili. La voce include il nome dell'app e una breve descrizione dei contenuti che possono essere cercati dall'app e resi disponibili per i suggerimenti nella Casella di ricerca rapida. Per definire il testo descrittivo per la tua app disponibile per la ricerca, aggiungi l'attributo android:searchSettingsDescription
alla configurazione disponibile per la ricerca, come illustrato 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" android:includeInGlobalSearch="true" android:searchSettingsDescription="@string/search_description" > </searchable>
Fai in modo che la stringa per android:searchSettingsDescription
sia il più concisa
possibile e indica i contenuti disponibili per la ricerca. Ad esempio, "Artisti, album e tracce" per un'app di musica o "Note salvate" per un'app per blocchi note. Questa descrizione è importante per consentire all'utente di sapere che tipo di suggerimenti viene fornito. 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, considera come comunicarlo agli utenti. Ad esempio, puoi 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 che l'utente seleziona dalla Casella di ricerca rapida possono essere convertiti automaticamente in scorciatoie. Si tratta di suggerimenti che il sistema copia dal tuo fornitore di contenuti in modo che possa accedere rapidamente al suggerimento senza dover eseguire una nuova query.
Per impostazione predefinita, questa opzione è abilitata 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 suggerimenti fanno riferimento a dati dinamici, come lo stato di presenza di un contatto, richiedi l'aggiornamento delle scorciatoie dei suggerimenti quando vengono mostrate all'utente. A questo scopo, 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 effettui una nuova query al tuo fornitore di contenuti per ottenere una versione aggiornata della scorciatoia del suggerimento.
Fornisci un valore nella colonna
SUGGEST_COLUMN_SHORTCUT_ID
per il suggerimento da ripetere per una versione nuova ogni volta che viene visualizzata la scorciatoia. La scorciatoia viene visualizzata rapidamente con i dati disponibili più di recente fino alla restituzione della query di aggiornamento, dopodiché il suggerimento viene aggiornato con le nuove informazioni. La query di aggiornamento viene inviata al fornitore di contenuti con un percorso URI pari aSUGGEST_URI_PATH_SHORTCUT
anziché aSUGGEST_URI_PATH_QUERY
.Imposta il criterio
Cursor
che restituisci per contenere un suggerimento utilizzando le stesse colonne del suggerimento originale oppure lascia vuoto il suggerimento, che indica che la scorciatoia non è più valida, nel qual caso il suggerimento scompare e la scorciatoia viene rimossa.Se un suggerimento si riferisce a dati il cui aggiornamento può richiedere più tempo, ad esempio un aggiornamento basato sulla rete, puoi anche aggiungere la colonna
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
alla tabella dei suggerimenti con il valore true per mostrare una rotellina di avanzamento per l'icona a destra fino al completamento dell'aggiornamento. Qualsiasi valore diverso da true non mostra la rotellina di avanzamento.Impedisce del tutto che il suggerimento venga copiato in una scorciatoia.
Specifica un valore di
SUGGEST_NEVER_MAKE_SHORTCUT
nella colonnaSUGGEST_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, la scorciatoia del suggerimento viene visualizzata solo fino a quando non viene restituita la query di aggiornamento.Consenti l'applicazione del comportamento predefinito della scorciatoia.
Lascia vuoto il campo
SUGGEST_COLUMN_SHORTCUT_ID
per ogni suggerimento che non viene modificato e che può essere salvato come scorciatoia.
Se nessuno dei tuoi suggerimenti cambia, non hai bisogno della colonna SUGGEST_COLUMN_SHORTCUT_ID
.
Informazioni sul ranking dei suggerimenti della Casella di ricerca rapida
Dopo aver reso disponibili i suggerimenti di ricerca della tua app alla Casella di ricerca rapida, il ranking della Casella di ricerca rapida determina il modo in cui i suggerimenti vengono mostrati all'utente per una determinata query. Ciò potrebbe dipendere da quante altre app hanno risultati per quella query e dalla frequenza con cui l'utente seleziona i tuoi risultati rispetto a quelli di altre app. Non vi è alcuna garanzia riguardo al ranking dei tuoi suggerimenti o alla loro visualizzazione o meno 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 avere un ranking più basso o non essere visualizzate.