Questa pagina è stata tradotta dall'API Cloud Translation.

Configurazione della ricerca

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.

posizione 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 al nome applicato all'attributo android:label dell'elemento <activity> o <application> manifest. Questa etichetta è visibile all'utente solo quando imposti android:includeInGlobalSearch su "true", nel qual caso viene utilizzata per identificare la tua applicazione come elemento ricercabile nelle impostazioni di ricerca del sistema.

android:hint

Risorsa stringa. (consigliato). Il testo da visualizzare nel campo di testo di ricerca quando non viene inserito alcun testo. Fornisce all'utente un suggerimento sui contenuti ricercabili. 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 della ricerca. Le modalità disponibili definiscono come deve essere riscritto il testo della query quando un suggerimento personalizzato riceve il focus. 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. Questo deve essere utilizzato solo quando i valori in `SUGGEST_COLUMN_INTENT_DATA` sono adatti all'ispezione e alla modifica da parte dell'utente, come gli URI HTTP.
`"queryRewriteFromText"`	Utilizza il valore della colonna `SUGGEST_COLUMN_TEXT_1` per riscrivere il testo della query.

Per saperne di più, 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 diverso da una ricerca, ad esempio una richiesta di URL in un browser web.

android:inputType

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

android:imeOptions

Parola chiave. Fornisce opzioni aggiuntive per il metodo di input. Per la maggior parte delle ricerche in cui è previsto testo in formato libero, non è necessario questo attributo. L'IME predefinito è actionSearch, che fornisce il pulsante "Cerca" anziché un ritorno a capo nella tastiera virtuale. Consulta imeOptions per un elenco di valori adatti per 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 fornisci suggerimenti di ricerca, devi utilizzare alcuni dei seguenti attributi <searchable>:

android:searchSuggestAuthority: Stringa. (Obbligatorio per fornire suggerimenti di ricerca.) Questo valore deve corrispondere alla stringa di autorità fornita nell'attributo android:authorities dell'elemento <provider> del file manifest di Android.
android:searchSuggestPath: Stringa. Questo percorso viene utilizzato come parte della query suggerimenti Uri, dopo il prefisso e l'autorità e prima del percorso dei suggerimenti standard. Questo è necessario solo se hai un unico fornitore di contenuti che emette diversi tipi di suggerimenti, ad esempio per diversi tipi di dati, e hai bisogno di un modo per disambiguare le query di suggerimenti quando le 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 solo punto interrogativo come segnaposto per la stringa di query effettiva inserita dall'utente, ad esempio "query=?". Tuttavia, puoi anche utilizzare qualsiasi valore non nullo per attivare la pubblicazione del testo della query utilizzando il parametro selectionArgs e ignorare il parametro selection.
android:searchSuggestIntentAction: Stringa. L'azione di 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 di intent predefiniti da utilizzare quando un utente tocca un suggerimento di ricerca personalizzata. 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 la ricerca di un suggerimento. In questo modo, viene garantito solo che il sistema non esegua query sul tuo fornitore di contenuti per contenuti più brevi della soglia. Il valore predefinito è 0.

Per ulteriori informazioni sugli attributi precedenti per i suggerimenti di ricerca, consulta la documentazione sull'aggiunta di suggerimenti di ricerca personalizzati e sull'aggiunta di suggerimenti personalizzati.

Per rendere disponibili i suggerimenti per le ricerche personalizzate nella 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 "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 ricercabile 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 che fornisci alla casella di ricerca rapida, visualizzata nella voce degli elementi ricercabili per la tua applicazione. La descrizione deve descrivere in modo conciso i contenuti ricercabili. Ad esempio, "Artisti, album e brani" per un'applicazione musicale o "Note salvate" per un'applicazione di blocco note.
android:queryAfterZeroResults: Booleano. Imposta "true" se vuoi che il tuo fornitore di contenuti venga richiamato per i superset di query che in precedenza non restituivano risultati. Ad esempio, se il tuo fornitore di contenuti restituisce zero risultati per "bo", la query deve essere ripetuta per "bob". Se impostato su "false", i superset vengono ignorati per una singola sessione: "bob" non richiama una nuova query. Solo per la durata della finestra di dialogo di ricerca o dell'attività quando si utilizza il widget di ricerca. Quando la finestra di dialogo o l'attività di ricerca viene riaperta, "bo" esegue di nuovo una query sul tuo fornitore di contenuti. Il valore predefinito è false.

Attributi della ricerca vocale

Per attivare la ricerca vocale, devi disporre di alcuni dei seguenti attributi <searchable>:

android:voiceSearchMode

Parola chiave. (Obbligatorio per fornire funzionalità di ricerca vocale.) Attiva 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 effetto. Sono accettati i seguenti valori di modalità:

Valore	Descrizione
`"showVoiceSearchButton"`	Visualizza un pulsante di ricerca vocale, se la ricerca vocale è disponibile sul dispositivo. Se impostato, allora devono essere impostati anche `"launchWebSearch"` o `"launchRecognizer"`, separati dal carattere barra verticale (`\|`).
`"launchWebSearch"`	Il pulsante di ricerca vocale porta l'utente direttamente a un'attività di ricerca vocale sul web integrata. La maggior parte delle applicazioni non utilizza questo flag, in quanto allontana l'utente dall'attività in cui è stata richiamata la ricerca.
`"launchRecognizer"`	Il pulsante di ricerca vocale porta l'utente direttamente a un'attività di registrazione vocale integrata. Questa attività chiede all'utente di parlare, trascrive il testo parlato e inoltra il testo della query risultante all'attività ricercabile, proprio come se l'utente lo 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 dettare le query. Questa funzionalità è 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 di ricerca. Questa funzionalità è disponibile in più lingue rispetto a `"free_form"`.

Per saperne di più, consulta EXTRA_LANGUAGE_MODEL.

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 è 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 ACTION_SEARCH query principale dell'intent. Deve essere pari a 1 o maggiore. Utilizza EXTRA_RESULTS per ottenere i risultati dall'intent. Se non viene fornito, il sistema di riconoscimento sceglie il numero di risultati da restituire.

<actionkey>

Definisce una chiave e un comportamento del dispositivo per un'azione di ricerca. Un'azione di ricerca fornisce un comportamento speciale con un tocco di un pulsante sul dispositivo, in base alla query corrente o al suggerimento selezionato. Ad esempio, l'applicazione Contatti fornisce un'azione di ricerca per avviare una chiamata telefonica al suggerimento di contatto attualmente selezionato 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 modo. Ad esempio, il tasto "Home" non può essere sostituito e deve sempre tornare alla schermata Home. Inoltre, assicurati di non definire un tasto azione per un tasto necessario per digitare una query di ricerca. In questo modo, le chiavi di azione disponibili e ragionevoli sono limitate al pulsante di chiamata e al pulsante del 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 tasto di KeyEvent che rappresenta il tasto di azione a cui vuoi rispondere, ad esempio "KEYCODE_CALL". Questo viene aggiunto all'intent ACTION_SEARCH che viene trasmesso all'attività ricercabile. Per esaminare il codice chiave, utilizza getIntExtra(SearchManager.ACTION_KEY). Non tutti i tasti sono supportati per un'azione di ricerca, in quanto molti vengono 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 di azione mentre l'utente sta inserendo il testo della query. Questo valore viene aggiunto all'intent ACTION_SEARCH che il sistema passa all'attività ricercabile. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG).
android:suggestActionMsg: Stringa. Un messaggio di azione da inviare se viene premuto il tasto di azione mentre un suggerimento è attivo. Questo viene aggiunto all'intent che il sistema passa all'attività di ricerca utilizzando l'azione che definisci per il suggerimento. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG). Questa opzione deve essere utilizzata solo se tutti i suggerimenti supportano questo tasto azione. Se non tutti i suggerimenti possono gestire la stessa chiave di azione, devi utilizzare l'attributo android:suggestActionMsgColumn.
android:suggestActionMsgColumn: Stringa. Il nome della colonna nel tuo fornitore di contenuti che definisce il messaggio di azione per questo tasto di azione, da inviare se l'utente preme il tasto di azione mentre un suggerimento è attivo. Questo attributo ti consente di controllare la chiave di azione in base ai suggerimenti, perché, anziché 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, quindi fornisci il nome di questa colonna in questo attributo. Il sistema esamina il cursore dei suggerimenti, utilizzando la stringa fornita qui per selezionare la colonna del messaggio di azione e poi seleziona la stringa del messaggio di azione dal cursore. Questa stringa viene aggiunta all'intent che il sistema passa all'attività ricercabile, utilizzando l'azione che definisci per i suggerimenti. Per esaminare la stringa, utilizza getStringExtra(SearchManager.ACTION_MSG). Se i dati non esistono per il suggerimento selezionato, la chiave di azione viene ignorata.

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>

Configurazione della ricerca Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Attributi dei suggerimenti di ricerca

Attributi della casella di ricerca rapida

Attributi della ricerca vocale

Configurazione della ricerca