Cerca configurazione

Per implementare la ricerca con l'assistenza del sistema Android, ovvero per inviare query di ricerca a un'attività e fornire suggerimenti di ricerca, l'applicazione deve fornire una configurazione di ricerca sotto forma di file XML.

Questa pagina descrive il file di configurazione della ricerca in termini di sintassi e utilizzo. Per ulteriori informazioni su come implementare le funzionalità di ricerca per la tua applicazione, consulta Creare un'interfaccia di ricerca.

percorso file:

res/xml/filename.xml
Android utilizza il nome file come ID risorsa.

:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>

:

<searchable>

Definisce tutte le configurazioni di ricerca utilizzate dal sistema Android per fornire la ricerca assistita.

Attributi:

android:label

Risorsa stringa. (Obbligatorio) Il nome della tua applicazione. Deve essere uguale al nome applicato all'attributo android:label dell'elemento manifest <activity> o <application>. Questa etichetta è visibile all'utente soltanto se imposti android:includeInGlobalSearch su "true". In questo caso, viene utilizzata per identificare la tua applicazione come elemento disponibile per la ricerca nelle impostazioni di ricerca del sistema.

android:hint

Risorsa stringa. (opzione consigliata). Il testo da visualizzare nel campo di ricerca quando non viene inserito alcun testo. Fornisce all'utente un suggerimento sui contenuti disponibili per la ricerca. Per coerenza con altre applicazioni Android, formatta la stringa per android:hint come "Cerca <content-or-product>". Ad esempio, "Cerca brani e artisti" o "Cerca su YouTube".

android:searchMode

Parola chiave. Imposta modalità aggiuntive che controllano la presentazione nella ricerca. Le modalità disponibili definiscono in che modo il testo della query deve essere riscritto quando un suggerimento personalizzato è attivo. Sono accettati i seguenti valori di modalità:

Valore	Descrizione
"queryRewriteFromData"	Utilizza il valore della colonna SUGGEST_COLUMN_INTENT_DATA per riscrivere il testo della query. Deve essere utilizzato solo quando i valori in SUGGEST_COLUMN_INTENT_DATA sono adatti per l'ispezione e la modifica da parte dell'utente, ad esempio gli URI HTTP.
"queryRewriteFromText"	Utilizza il valore della colonna SUGGEST_COLUMN_TEXT_1 per riscrivere il testo della query.

Per maggiori informazioni, consulta la documentazione sulla riscrittura del testo della query in Aggiungere suggerimenti di ricerca personalizzati.

android:searchButtonText

Risorsa stringa. Il testo da visualizzare nel pulsante che esegue la ricerca. Per impostazione predefinita, il pulsante mostra un'icona di ricerca (una lente d'ingrandimento), ideale per l'internazionalizzazione. Pertanto, non utilizzare questo attributo per modificare il pulsante, a meno che il comportamento non sia qualcosa di diverso da una ricerca, come una richiesta di un URL in un browser web.

android:inputType

Parola chiave. Definisce il tipo di metodo di immissione da utilizzare, ad esempio il tipo di tastiera virtuale. Questo attributo non è necessario per la maggior parte delle ricerche in cui è previsto testo in formato libero. Consulta inputType per un elenco dei valori adatti per questo attributo.

android:imeOptions

Parola chiave. Fornisce opzioni aggiuntive per il metodo di inserimento. Questo attributo non è necessario per la maggior parte delle ricerche, in cui è previsto testo in formato libero. L'IME predefinito è actionSearch, che fornisce il pulsante "Cerca" anziché un ritorno a capo nella tastiera software. Consulta imeOptions per un elenco di valori adatti per questo attributo.

Attributi dei suggerimenti di ricerca

Se definisci un fornitore di contenuti che generi suggerimenti di ricerca, devi definire attributi aggiuntivi che configurano le comunicazioni con il fornitore di contenuti. Quando fornisci suggerimenti di ricerca, ti servono alcuni dei seguenti attributi <searchable>:

android:searchSuggestAuthority

Stringa. (Obbligatorio per fornire suggerimenti di ricerca). Questo valore deve corrispondere alla stringa dell'autorità fornita nell'attributo android:authorities dell'elemento <provider> del manifest Android.

android:searchSuggestPath

Stringa. Questo percorso viene utilizzato come parte della query di suggerimenti Uri, dopo il prefisso e l'autorità e prima del percorso dei suggerimenti standard. Questa operazione è necessaria solo se un singolo fornitore di contenuti invia tipi diversi di suggerimenti, ad esempio per tipi di dati diversi, e hai bisogno di un modo per distinguere le query dei suggerimenti quando li ricevi.

android:searchSuggestSelection

Stringa. Questo valore viene passato alla funzione di query come parametro selection. In genere si tratta di una clausola WHERE per il tuo database e deve contenere un singolo punto interrogativo come segnaposto per la stringa di query effettiva inserita dall'utente, ad esempio "query=?". Tuttavia, puoi anche utilizzare qualsiasi valore non null per attivare la pubblicazione del testo della query utilizzando il parametro selectionArgs e ignorare il parametro selection.

android:searchSuggestIntentAction

Stringa. L'azione intent predefinita da utilizzare quando un utente tocca un suggerimento di ricerca personalizzato, ad esempio "android.intent.action.VIEW". Se questo valore non viene sostituito dal suggerimento selezionato utilizzando la colonna SUGGEST_COLUMN_INTENT_ACTION, il valore viene inserito nel campo azione di Intent quando l'utente tocca un suggerimento.

android:searchSuggestIntentData

Stringa. I dati sugli intent predefiniti da utilizzare quando un utente tocca un suggerimento di ricerca personalizzato. Se non viene sostituito dal suggerimento selezionato, tramite la colonna SUGGEST_COLUMN_INTENT_DATA, questo valore viene inserito nel campo dati di Intent quando l'utente tocca un suggerimento.

android:searchSuggestThreshold

Numero intero. Il numero minimo di caratteri necessari per attivare una ricerca di suggerimenti. Questo garantisce che il sistema non interrompa il tuo fornitore di contenuti per nulla di inferiore alla soglia. Il valore predefinito è 0.

Per saperne di più sugli attributi riportati sopra per i suggerimenti di ricerca, consulta la documentazione relativa all'aggiunta di suggerimenti di ricerca personalizzati e all'aggiunta di suggerimenti personalizzati.

Attributi della Casella di ricerca rapida

Per rendere disponibili i suggerimenti di ricerca personalizzati alla Casella di ricerca rapida, devi disporre di alcuni dei seguenti attributi <searchable>:

android:includeInGlobalSearch

Booleano. (Obbligatorio per fornire suggerimenti di ricerca nella Casella di ricerca rapida). Imposta su "true" se vuoi che i tuoi suggerimenti vengano inclusi nella Casella di ricerca rapida accessibile a livello globale. L'utente deve comunque attivare la tua applicazione come elemento disponibile per la ricerca nelle impostazioni di ricerca del sistema prima che i tuoi suggerimenti vengano visualizzati nella Casella di ricerca rapida.

android:searchSettingsDescription

Risorsa stringa. Fornisce una breve descrizione dei suggerimenti di ricerca forniti alla Casella di ricerca rapida, che viene visualizzata nella voce degli elementi disponibili per la ricerca per la tua applicazione. La descrizione deve descrivere concisamente i contenuti disponibili per la ricerca. Ad esempio, "Artisti, album e tracce" per un'applicazione di musica o "Note salvate" per un'applicazione di blocco note.

android:queryAfterZeroResults

Booleano. Imposta su "true" se vuoi che il tuo fornitore di contenuti venga richiamato per i superinsiemi di query che in precedenza non offrivano risultati. Ad esempio, se il fornitore di contenuti restituisce zero risultati per "bo", è necessario ripetere la query per "bob". Se viene impostato su "false", i superset vengono ignorati per una singola sessione: "bob" non richiama una riquery. Questo dura solo per l'intera durata della finestra di dialogo di ricerca o per tutta la durata dell'attività quando utilizzi il widget di ricerca. Quando la finestra di dialogo o l'attività di ricerca vengono riaperte, "bo" invia una nuova query al fornitore di contenuti. Il valore predefinito è false.

Attributi della ricerca vocale

Per attivare la ricerca vocale, sono necessari alcuni dei seguenti attributi <searchable>:

android:voiceSearchMode

Parola chiave. (Obbligatorio per fornire funzionalità di ricerca vocale) Consente di attivare la ricerca vocale, con una modalità specifica per la ricerca vocale. La ricerca vocale potrebbe non essere fornita dal dispositivo, nel qual caso questi flag non hanno alcun effetto. Sono accettati i seguenti valori di modalità:

Valore	Descrizione
"showVoiceSearchButton"	Mostrare un pulsante per la ricerca vocale, se la ricerca vocale è disponibile sul dispositivo. Se impostato, è necessario impostare anche "launchWebSearch" o "launchRecognizer", separati dal carattere barra verticale (|).
"launchWebSearch"	Il pulsante di ricerca vocale indirizza l'utente direttamente a un'attività di ricerca web vocale integrata. La maggior parte delle applicazioni non utilizza questo flag, poiché sottrae l'utente all'attività in cui è stata richiamata la ricerca.
"launchRecognizer"	Il pulsante di ricerca vocale indirizza l'utente direttamente a un'attività di registrazione vocale integrata. Questa attività chiede all'utente di parlare, trascrive il testo pronunciato e inoltra il testo della query risultante all'attività disponibile per la ricerca, proprio come se l'utente l'avesse digitato nell'interfaccia utente di ricerca e avesse toccato il pulsante di ricerca.

android:voiceLanguageModel

Parola chiave. Il modello linguistico che deve essere utilizzato dal sistema di riconoscimento vocale. Sono accettati i seguenti valori:

Valore	Descrizione
"free_form"	Utilizza il riconoscimento vocale in formato libero per la dettatura delle query. ed è ottimizzata principalmente per l'inglese. Questa è l'impostazione predefinita.
"web_search"	Utilizza il riconoscimento dei termini di ricerca web per frasi più brevi simili a quelle della ricerca. Questa funzionalità è disponibile in più lingue rispetto a "free_form".

Consulta EXTRA_LANGUAGE_MODEL per ulteriori informazioni.

android:voicePromptText

Risorsa stringa. Un messaggio aggiuntivo da visualizzare nella finestra di dialogo dell'input vocale.

android:voiceLanguage

Stringa. La lingua parlata prevista, espressa come valore stringa di una costante in Locale, ad esempio "de" per il tedesco o "fr" per il francese. Questo campo è necessario solo se è diverso dal valore attuale di Locale.getDefault().

android:voiceMaxResults

Numero intero. Imposta il numero massimo di risultati da restituire, incluso il risultato "migliore", che viene sempre fornito come query principale dell'intent ACTION_SEARCH. Deve essere pari o superiore a 1. Utilizza EXTRA_RESULTS per ottenere i risultati dall'intent. Se non viene specificato, il riconoscimento sceglie il numero di risultati da restituire.

<actionkey>

Definisce una chiave dispositivo e il comportamento per un'azione di ricerca. Un'azione di ricerca determina un comportamento speciale quando tocca un pulsante sul dispositivo, in base alla query corrente o al suggerimento attivo. Ad esempio, l'applicazione Contatti fornisce un'azione di ricerca per avviare una telefonata al suggerimento di contatto attualmente attivo quando si tocca il pulsante CHIAMA.

Non tutti i tasti di azione sono disponibili su ogni dispositivo e non tutte le chiavi possono essere sostituite in questo modo. Ad esempio, la chiave "Home" non può essere ignorata e deve sempre tornare alla schermata Home. Inoltre, assicurati di non definire un tasto di azione necessario per digitare una query di ricerca. In questo modo, i tasti di azione disponibili e ragionevoli sono limitati al pulsante di chiamata e al pulsante Menu.

Devi definire android:keycode per definire la chiave e almeno uno degli altri tre attributi per definire l'azione di ricerca.

Attributi:

android:keycode

Stringa. (Obbligatorio) Un codice chiave di KeyEvent che rappresenta la chiave di azione a cui vuoi rispondere, ad esempio "KEYCODE_CALL". Questo viene aggiunto all'intent ACTION_SEARCH trasmesso all'attività disponibile per la ricerca. Per esaminare il codice della chiave, utilizza getIntExtra(SearchManager.ACTION_KEY). Non tutti i tasti sono supportati per un'azione di ricerca, poiché molti sono utilizzati per la digitazione, la navigazione o le funzioni di sistema.

android:queryActionMsg

Stringa. Un messaggio di azione da inviare se viene premuto il tasto azione mentre l'utente inserisce il testo della query. Questa operazione viene aggiunta all'intent ACTION_SEARCH che il sistema passa alla tua attività disponibile per la ricerca. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

Stringa. Un messaggio di azione da inviare se viene premuto il tasto azione mentre è attivo un suggerimento. Questo viene aggiunto all'intent che il sistema passa alla tua attività di ricerca, utilizzando l'azione che definisci per il suggerimento. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG). Deve essere utilizzato solo se tutti i suggerimenti supportano questo tasto azione. Se non tutti i suggerimenti possono gestire la stessa chiave di azione, devi utilizzare il seguente attributo android:suggestActionMsgColumn.

android:suggestActionMsgColumn

Stringa. Il nome della colonna nel fornitore di contenuti che definisce il messaggio di azione per questa chiave di azione, da inviare se l'utente preme il tasto azione mentre è attivo un suggerimento. Questo attributo consente di controllare la chiave di azione in base al suggerimento per suggerimento. Infatti, invece di utilizzare l'attributo android:suggestActionMsg per definire il messaggio di azione per tutti i suggerimenti, ogni voce del tuo fornitore di contenuti fornisce il proprio messaggio di azione.

Innanzitutto, devi definire una colonna nel tuo fornitore di contenuti per ogni suggerimento per cui fornire un messaggio di azione, poi indicare il nome di quella colonna in questo attributo. Il sistema controlla il cursore del suggerimento utilizzando la stringa fornita qui per selezionare la colonna dei messaggi di azione, quindi seleziona la stringa del messaggio di azione dal cursore. La stringa viene aggiunta all'intent che il sistema passa all'attività disponibile per la ricerca, utilizzando l'azione definita per i suggerimenti. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG). Se non esistono dati per il suggerimento selezionato, il tasto azione viene ignorato.

esempio:

File XML salvato in res/xml/searchable.xml:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>