Configurazione della ricerca

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

In questa pagina viene descritto il file di configurazione della ricerca in termini di sintassi e di utilizzo. Per ulteriori informazioni informazioni su come implementare le funzionalità di ricerca per la tua applicazione, vedi Crea un'interfaccia di ricerca.

percorso del file:

res/xml/filename.xml

Android utilizza il nome del file come ID risorsa.

sintassi:

<?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>

elementi:

<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 a il nome applicato all'attributo android:label del tuo <activity> o <application> . Questa etichetta è visibile all'utente solo quando la imposti Da android:includeInGlobalSearch a "true", nel qual caso viene usata questa etichetta 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 testo di ricerca quando non viene inserito alcun testo. Fornisce un suggerimento all'utente 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. Consente di impostare modalità aggiuntive che controllano la presentazione di ricerca. Disponibile definiscono il modo in cui il testo della query deve essere riscritto quando un suggerimento personalizzato riceve il focus. Sono accettati i seguenti valori della modalità:

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

Per ulteriori 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. Di Per impostazione predefinita, il pulsante mostra un'icona di ricerca (una lente d'ingrandimento), ideale per internazionalizzazione. Non usare quindi questo attributo per modificare il pulsante, a meno che il comportamento non sia qualcosa di diverso dalla ricerca, come una richiesta di URL in un browser web.

android:inputType

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

android:imeOptions

Parola chiave. Fornisce opzioni aggiuntive per il metodo di inserimento. Per la maggior parte delle ricerche, in quale testo in formato libero è previsto, non hai bisogno di questo attributo. L'IME predefinito è actionSearch, che fornisce la funzionalità di "ricerca" anziché un ritorno a capo nel tastiera software. Vedi imeOptions per un elenco di valori adatti a questo attributo.

Attributi dei suggerimenti di ricerca

Se definisci un fornitore di contenuti per generare suggerimenti di ricerca, devi definire attributi aggiuntivi che configurano le comunicazioni con il fornitore di contenuti. Quando viene fornita la ricerca suggerimenti, devi disporre di alcuni dei seguenti attributi <searchable>:

android:searchSuggestAuthority

Stringa. (Obbligatorio per fornire suggerimenti di ricerca). Questo valore deve corrispondere alla stringa di autorizzazione specificata in android:authorities dell'elemento <provider> del file manifest Android.

android:searchSuggestPath

Stringa. Questo percorso viene utilizzato come parte dei suggerimenti query Uri, dopo il prefisso e dell'IA e prima del percorso dei suggerimenti standard. Questa operazione è necessaria solo se disponi di un un singolo fornitore di contenuti che emette vari tipi di suggerimenti, ad esempio per tipi di dati; inoltre, ti serve un modo per distinguere le query dei suggerimenti quando ricevi che li rappresentano.

android:searchSuggestSelection

Stringa. Questo valore viene passato come il parametro selection. Tipicamente si tratta di una clausola WHERE per il database e deve contenere un singolo punto interrogativo come segnaposto per stringa di query effettiva inserita dall'utente, ad esempio "query=?". Tuttavia, puoi anche utilizzare qualsiasi valore diverso da null per attivare la pubblicazione del testo della query utilizzando il metodo selectionArgs, quindi ignora il parametro selection).

android:searchSuggestIntentAction

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

android:searchSuggestIntentData

Stringa. I dati sull'intent predefiniti da usare quando un utente tocca un suggerimento di ricerca personalizzata. Se non viene sostituito dal suggerimento selezionato, tramite SUGGEST_COLUMN_INTENT_DATA colonna: questo valore viene inserito nel campo dati della Intent quando l'utente tocca un suggerimento.

android:searchSuggestThreshold

Numero intero. Il numero minimo di caratteri necessario per attivare una ricerca di suggerimenti. Ciò garantisce solo che il sistema non esegua query sui tuoi fornitore di contenuti per qualsiasi elemento inferiore alla soglia. Il valore predefinito è 0.

Per ulteriori informazioni sugli attributi sopra riportati per i suggerimenti di ricerca, consulta la documentazione per aggiungere suggerimenti di ricerca personalizzati e l'aggiunta di suggerimenti personalizzati.

Attributi della casella di ricerca rapida

Per rendere i tuoi suggerimenti di ricerca personalizzati disponibili nella Casella di ricerca rapida, hai bisogno di alcune delle seguenti attributi <searchable>:

android:includeInGlobalSearch

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

android:searchSettingsDescription

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

android:queryAfterZeroResults

Booleano. Imposta "true" se vuoi che il tuo fornitore di contenuti sia per i soprainsiemi di query che in precedenza non restituivano risultati. Ad esempio, se il tuo fornitore di contenuti restituisce zero risultati per "bo", ma deve essere presente una nuova query per "bob". Se impostato su "false", i superinsiemi vengono ignorati per una singola sessione "bob" non richiama una riquery. Dura solo l'intera durata della finestra di dialogo di ricerca l'attività quando si usa il widget Ricerca. Quando la finestra di dialogo o l'attività di ricerca viene riaperta, "bo" invia nuovamente una query al tuo 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. (Necessari 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 della modalità:

Valore	Descrizione
"showVoiceSearchButton"	Visualizza un pulsante per la ricerca vocale, se la ricerca vocale è disponibile sul dispositivo. Se impostato, devi impostare anche "launchWebSearch" o "launchRecognizer", separate dalla barra verticale (|).
"launchWebSearch"	Il pulsante di ricerca vocale porta l'utente direttamente a un'attività di ricerca web vocale integrata. La maggior parte delle applicazioni non usa questo flag, perché allontana l'utente dall'attività in cui è stata richiamata la ricerca.
"launchRecognizer"	Il pulsante per la ricerca vocale l'utente direttamente a un'attività di registrazione vocale integrata. Questa attività chiede all'utente di parlare, trascrive il testo pronunciato e inoltra i il testo della query all'attività di ricerca, proprio come se l'utente lo avesse digitato nel UI e hai toccato il pulsante di ricerca.

android:voiceLanguageModel

Parola chiave. Il modello linguistico deve essere utilizzata 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. Si tratta principalmente ottimizzato per l'inglese. Questa è l'impostazione predefinita.
"web_search"	Utilizza il riconoscimento dei termini di ricerca web per frasi più brevi simili a quelle di ricerca. Questo è disponibile in più lingue rispetto a: "free_form".

Consulta EXTRA_LANGUAGE_MODEL per altri 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, come "de" per il tedesco o "fr" per il francese. È necessario solo se è diverso dal valore corrente di Locale.getDefault().

android:voiceMaxResults

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

<actionkey>

Definisce la chiave e il comportamento del dispositivo per un'azione di ricerca. Un'azione di ricerca offre un'eccezione comportamento del dispositivo toccando un pulsante, in base alla query corrente o suggerimento. Ad esempio, l'applicazione Contatti fornisce un'azione di ricerca per avviare una chiamata chiamata al suggerimento di contatto attualmente attivo quando viene toccato il pulsante CHIAMA.

Non tutti i tasti di azione sono disponibili su tutti i dispositivi e non tutti i tasti possono essere sostituiti in questo in molti modi diversi. Ad esempio, la scheda "Home" non è possibile eseguire l'override della chiave e deve sempre tornare alla home page schermo. Inoltre, assicurati di non definire un tasto azione per una chiave necessaria per digitare una ricerca query. Questo limita i tasti di azione disponibili e ragionevoli per il pulsante di chiamata e il menu .

Devi definire il 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 KeyEvent che rappresenta Il tasto azione a cui vuoi rispondere, ad esempio "KEYCODE_CALL". Questo viene aggiunto al ACTION_SEARCH l'intent che viene trasmesso alla tua attività di ricerca. Per esaminare il codice della chiave, utilizza getIntExtra(SearchManager.ACTION_KEY). Non tutte le chiavi sono supportate per un'azione di ricerca, perché molte vengono utilizzate per la digitazione. navigazione o funzioni di sistema.

android:queryActionMsg

Stringa. Un messaggio di azione da inviare se viene premuto il tasto di azione mentre l'utente sta inserendo il testo della query. Questo valore viene aggiunto al ACTION_SEARCH l'intento che il sistema trasmette all'attività disponibile per la ricerca. Per esaminare la stringa, usa getStringExtra(SearchManager.ACTION_MSG).

android:suggestActionMsg

Stringa. Un messaggio di azione da inviare se viene premuto il tasto di azione mentre è attivo il suggerimento. Questo valore viene aggiunto all'intent che il sistema trasmette al tuo attività di ricerca, utilizzando l'azione definita per il suggerimento. Per esaminare le stringa, utilizza getStringExtra(SearchManager.ACTION_MSG). Deve essere utilizzato solo se tutti i suggerimenti supportano questo tasto azione. Se non tutte possono gestire lo stesso tasto azione, devi utilizzare il seguente Attributo android:suggestActionMsgColumn.

android:suggestActionMsgColumn

Stringa. Il nome della colonna nel fornitore di contenuti che definisce la messaggio di azione per questo tasto azione, che deve essere inviato se l'utente preme il tasto azione mentre è attivo un suggerimento. Questo attributo ti consente di controllare il tasto azione su un suggerimento per suggerimento, perché, invece di utilizzare Attributo android:suggestActionMsg per definire il messaggio di azione per tutti suggerimenti, ogni voce del fornitore di contenuti fornisce il proprio messaggio di azione.

Innanzitutto, devi definire una colonna nel fornitore di contenuti per ogni suggerimento da fornire un messaggio di azione, quindi specifica il nome della colonna in questo attributo. Il sistema guarda il cursore del suggerimento, utilizzando la stringa qui fornita per selezionare l'azione messaggio, quindi seleziona la stringa del messaggio di azione dal cursore. La stringa è aggiunta all'intent che il sistema trasmette alla tua attività di ricerca, utilizzando l'azione per i suggerimenti. Per esaminare la stringa, usa getStringExtra(SearchManager.ACTION_MSG). Se non esistono dati per il suggerimento selezionato, la chiave di azione viene ignorata.

esempio:

File XML salvato alle ore 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>