Para implementar a pesquisa com a assistência do sistema Android, ou seja, para entregar consultas de pesquisa a uma atividade e fornecer sugestões de pesquisa, seu app precisa fornecer uma configuração de pesquisa na forma de um arquivo XML.
Esta página descreve o arquivo de configuração de pesquisa em termos de sintaxe e uso. Para mais informações sobre como implementar recursos de pesquisa no seu app, consulte Criar uma interface de pesquisa.
- localização do arquivo:
res/xml/filename.xml
O Android usa o nome do arquivo como ID de recurso.- sintaxe:
-
<?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> - elementos:
-
<searchable>
- Define todas as configurações de pesquisa usadas pelo sistema Android para oferecer a pesquisa assistida.
Atributos:
android:label
- Recurso de string. Obrigatório. Nome do seu app. Ele precisa ser igual
ao nome aplicado ao atributo
android:label
do seu elemento de manifesto<activity>
ou<application>
. Esse rótulo só fica visível para o usuário quando você defineandroid:includeInGlobalSearch
como"true"
. Nesse caso, o rótulo é usado para identificar seu aplicativo como um item pesquisável nas configurações de pesquisa do sistema. android:hint
- Recurso de string. Recomendado. O texto a ser exibido no campo de texto de pesquisa quando nenhum texto é inserido. Fornece uma dica para o usuário sobre qual conteúdo é pesquisável. Para manter a consistência
com outros apps Android, formate a string de
android:hint
como "Pesquisar <content-or-product>". Por exemplo, "Pesquisar músicas e artistas" ou "Pesquisar no YouTube". android:searchMode
- Palavra-chave. Define modos suplementares que controlam a apresentação de pesquisa. Os modos
disponíveis definem como o texto da consulta precisa ser reescrito quando uma sugestão personalizada
recebe foco. São aceitos os seguintes valores de modo:
Valor Descrição "queryRewriteFromData"
Use o valor da coluna SUGGEST_COLUMN_INTENT_DATA
para reescrever o texto debquery. Essa função só pode ser usada quando os valores emSUGGEST_COLUMN_INTENT_DATA
forem adequados para inspeção e edição do usuário, como URIs HTTP."queryRewriteFromText"
Use o valor da coluna SUGGEST_COLUMN_TEXT_1
para reescrever o texto da consulta.Para mais informações, consulte a documentação sobre como reescrever o texto da consulta em Adicionar sugestões de pesquisa personalizadas.
android:searchButtonText
- Recurso de string. Texto a ser exibido no botão que executa a pesquisa. Por padrão, o botão mostra um ícone de pesquisa (uma lupa), que é ideal para internacionalização. Portanto, não use esse atributo para mudar o botão, a menos que o comportamento seja algo diferente de uma pesquisa, como uma solicitação de URL em um navegador da Web.
android:inputType
- Palavra-chave. Define o tipo de método de entrada a ser usado, como o tipo de
teclado de software. Esse atributo não é necessário na maioria das pesquisas em que texto de formato livre é esperado.
Consulte
inputType
para conferir uma lista de valores adequados para esse atributo. android:imeOptions
- Palavra-chave. Fornece outras opções para o método de entrada. Esse atributo não é necessário na maioria das pesquisas em
que o texto de formato livre é esperado. O IME padrão é
actionSearch
, que fornece o botão "Pesquisar" em vez de um retorno de carro no teclado de software. ConsulteimeOptions
para conferir uma lista de valores adequados para esse atributo.
Atributos de sugestão de pesquisa
Se você definir um provedor de conteúdo para gerar sugestões de pesquisa, será necessário definir atributos adicionais que configurem as comunicações com o provedor de conteúdo. Ao fornecer sugestões de pesquisa, você precisa de alguns destes atributos
<searchable>
:
android:searchSuggestAuthority
- String. Obrigatório para fornecer sugestões de pesquisa. Esse valor precisa corresponder à
string de autoridade fornecida no atributo
android:authorities
do elemento<provider>
do manifesto do Android. android:searchSuggestPath
- String. Esse caminho é usado como uma parte do
Uri
da consulta de sugestões, depois do prefixo e da autoridade e antes do caminho das sugestões padrão. Isso só é necessário se você tem um único provedor de conteúdo emitindo diferentes tipos de sugestões (por exemplo, para diferentes tipos de dados) e precisa de uma maneira de diferenciar as consultas de sugestões quando as recebe. android:searchSuggestSelection
- String. Esse valor é transmitido para a função de consulta como o parâmetro
selection
. Normalmente, essa é uma cláusula WHERE para seu banco de dados e precisa conter um único ponto de interrogação como marcador para a string de consulta real inserida pelo usuário, por exemplo,"query=?"
. No entanto, também é possível usar qualquer valor não nulo para acionar a entrega do texto de consulta usando o parâmetroselectionArgs
e ignorar o parâmetroselection
. android:searchSuggestIntentAction
- String. A ação de intent padrão a ser usada quando um usuário toca em uma sugestão de pesquisa personalizada, como
"android.intent.action.VIEW"
. Se esse valor não for substituído pela sugestão selecionada usando a colunaSUGGEST_COLUMN_INTENT_ACTION
, o valor será colocado no campo de ação deIntent
quando o usuário tocar em uma sugestão. android:searchSuggestIntentData
- String. Os dados de intent padrão a serem usados quando um usuário
toca em uma sugestão de pesquisa personalizada.
Se não for substituído pela sugestão selecionada, por meio da coluna
SUGGEST_COLUMN_INTENT_DATA
, esse valor será colocado no campo de dados deIntent
quando o usuário tocar em uma sugestão. android:searchSuggestThreshold
- Número inteiro. O número mínimo de caracteres necessários para acionar uma pesquisa de sugestão. Isso garante apenas que o sistema não consulte seu provedor de conteúdo para valores menores que o limite. O valor padrão é 0.
Para mais informações sobre os atributos acima para sugestões de pesquisa, consulte a documentação sobre como adicionar sugestões de pesquisa personalizadas e como adicionar sugestões personalizadas.
Atributos da caixa de pesquisa rápida
Para disponibilizar suas sugestões de pesquisa personalizadas na caixa de pesquisa rápida, você precisa de alguns dos seguintes atributos
<searchable>
:
android:includeInGlobalSearch
- Booleano. Obrigatório para fornecer sugestões na caixa de pesquisa rápida. Defina como
"true"
se você quiser que suas sugestões sejam incluídas na caixa de pesquisa rápida acessível globalmente. O usuário ainda precisa ativar o app como um item pesquisável nas configurações de pesquisa do sistema para que suas sugestões apareçam na caixa de pesquisa rápida. android:searchSettingsDescription
- Recurso de string. Fornece uma breve descrição das sugestões de pesquisa fornecidas para a caixa de pesquisa rápida, que é exibida na entrada de itens pesquisáveis do app. A descrição precisa descrever de forma concisa o conteúdo pesquisável. Por exemplo, "Artistas, álbuns e faixas" para um app de música ou "Notas salvas" para um app de bloco de notas.
android:queryAfterZeroResults
- Booleano. Defina como
"true"
se quiser que o provedor de conteúdo seja invocado para superconjuntos de consultas que anteriormente não retornaram resultados. Por exemplo, se o provedor de conteúdo não retornar resultados para "bo", será necessário fazer uma solicitação para "bob". Se definido como"false"
, os superconjuntos serão ignorados para uma única sessão – "bob" não invoca uma nova consulta. Dura apenas durante a vida útil da caixa de diálogo de pesquisa ou durante o período da atividade ao usar o widget de pesquisa. Quando a caixa ou atividade de pesquisa é reaberta, "bo" consulta seu provedor de conteúdo novamente. O valor padrão é "false".
Atributos de pesquisa por voz
Para ativar a pesquisa por voz, você precisa de alguns dos seguintes atributos
<searchable>
:
android:voiceSearchMode
- Palavra-chave. Obrigatório para fornecer recursos de pesquisa por voz.
Ativa a pesquisa por voz, com um modo específico para pesquisa por voz.
A pesquisa por voz pode não ser fornecida pelo dispositivo. Nesse caso, essas sinalizações
não têm efeito. São aceitos os seguintes valores de modo:
Valor Descrição "showVoiceSearchButton"
Exibe um botão de pesquisa por voz, se ele estiver disponível no dispositivo. Se definido, "launchWebSearch"
ou"launchRecognizer"
também precisam ser definidos, separados pelo caractere de barra vertical (|
)."launchWebSearch"
O botão de pesquisa por voz leva o usuário diretamente a uma atividade integrada de pesquisa na Web. A maioria dos aplicativos não usa essa flag, porque ela afasta o usuário da atividade em que a pesquisa foi invocada. "launchRecognizer"
O botão de pesquisa por voz leva o usuário diretamente a uma atividade de gravação de voz integrada. Essa atividade solicita que o usuário fale, transcreve o texto falado e encaminha o texto de consulta resultante para a atividade de pesquisa, exatamente como se o usuário tivesse digitado na interface de pesquisa e tocado no botão de pesquisa. android:voiceLanguageModel
- Palavra-chave. O modelo de idioma que
precisa ser usado pelo sistema de reconhecimento de voz. São aceitos os seguintes valores:
Valor Descrição "free_form"
Usa reconhecimento de voz de forma livre para ditar consultas. Isso é otimizado principalmente para inglês. Esse é o padrão. "web_search"
Usa reconhecimento de termos de pesquisa da Web para frases curtas, usadas em pesquisas. Esse recurso está disponível em mais idiomas que o "free_form"
.Consulte
EXTRA_LANGUAGE_MODEL
para saber mais. android:voicePromptText
- Recurso de string. Uma mensagem complementar a ser exibida na caixa de diálogo de entrada de texto por voz.
android:voiceLanguage
- String. O idioma falado esperado, expresso como o valor de string de
uma constante em
Locale
, como"de"
para alemão ou"fr"
para francês. Isso é necessário apenas se for diferente do valor atual deLocale.getDefault()
. android:voiceMaxResults
- Número inteiro. Define o número máximo de resultados a serem retornados, incluindo o "melhor" resultado, que é sempre fornecido como a consulta principal da intent
ACTION_SEARCH
. Precisa ser 1 ou mais. UseEXTRA_RESULTS
para receber os resultados da intent. Se não for fornecido, o reconhecedor escolherá quantos resultados devem ser retornados.
<actionkey>
- Define a chave e o comportamento do dispositivo para uma ação de pesquisa. Uma ação de pesquisa oferece um comportamento especial ao tocar em um botão no dispositivo, com base na consulta atual ou na sugestão em foco. Por exemplo, o aplicativo Contatos oferece uma ação de pesquisa para iniciar uma chamada telefônica para a sugestão de contato em foco no momento quando o botão "CALL" é tocado.
Nem todas as teclas de ação estão disponíveis em todos os dispositivos, e nem todas podem ser substituídas dessa forma. Por exemplo, a tecla "Home" não pode ser substituída e precisa sempre retornar à tela inicial. Além disso, não defina uma tecla de ação para uma tecla que é necessária para digitar uma consulta de pesquisa. Isso limita as teclas de ação disponíveis e razoáveis ao botão de chamada e ao botão de menu.
É necessário definir a
android:keycode
para definir a tecla e pelo menos um dos outros três atributos para definir a ação de pesquisa.Atributos:
android:keycode
- String. Obrigatório. Um código de tecla de
KeyEvent
que representa a tecla de ação a que você quer responder, por exemplo,"KEYCODE_CALL"
. Isso é adicionado à intentACTION_SEARCH
que é transmitida para sua atividade de pesquisa. Para examinar o código de tecla, usegetIntExtra(SearchManager.ACTION_KEY)
. Nem todas as teclas são compatíveis com uma ação de pesquisa, já que muitas são usadas para digitação, navegação ou funções do sistema. android:queryActionMsg
- String. Mensagem de ação a ser enviada se a tecla de ação for pressionada enquanto o usuário estiver inserindo o texto de consulta. Isso é adicionado ao intent
ACTION_SEARCH
que o sistema transmite para sua atividade de pesquisa. Para examinar a string, usegetStringExtra(SearchManager.ACTION_MSG)
. android:suggestActionMsg
- String. Mensagem de ação a ser enviada se a tecla de ação for pressionada enquanto uma sugestão estiver em foco. É adicionado à intent que o sistema transmite para a atividade de pesquisa usando a ação definida para a sugestão. Para examinar a
string, use
getStringExtra(SearchManager.ACTION_MSG)
. Isso só poderá ser usado se todas as suas sugestões forem compatíveis com essa tecla de ação. Se nem todas as sugestões puderem processar a mesma tecla de ação, use o seguinte atributoandroid:suggestActionMsgColumn
. android:suggestActionMsgColumn
- String. O nome da coluna no provedor de conteúdo que define a
mensagem de ação para essa tecla de ação, que será enviada se o usuário pressionar a tecla de ação
enquanto uma sugestão estiver em foco. Esse atributo permite controlar a tecla de ação com base em
sugestão por sugestão, porque, em vez de usar o atributo
android:suggestActionMsg
para definir a mensagem de ação para todas as sugestões, cada entrada no seu provedor de conteúdo fornece a própria mensagem de ação.Primeiro, você precisa definir uma coluna no seu provedor de conteúdo para cada sugestão para fornecer uma mensagem de ação e, em seguida, fornecer o nome dessa coluna nesse atributo. O sistema olha para o cursor de sugestão, usando a string fornecida aqui para selecionar a coluna da mensagem de ação e, em seguida, seleciona a string da mensagem de ação do cursor. Essa string é adicionada ao intent que o sistema transmite para sua atividade de pesquisa, usando a ação definida para sugestões. Para examinar a string, use
getStringExtra(SearchManager.ACTION_MSG)
. Se não houver dados para a sugestão selecionada, a tecla de ação será ignorada.
- exemplo:
- Arquivo XML salvo em
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>