Configuração pesquisável

Para implementar a pesquisa com assistência do sistema Android (a fim de 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 saber mais sobre como implementar recursos de pesquisa para seu app, comece consultando Como criar uma interface de pesquisa no guia do desenvolvedor

localização do arquivo:

res/xml/filename.xml
O Android usa o nome do arquivo como o ID do 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 fornecer a pesquisa assistida.

atributos:

android:label

Recurso de string. Obrigatório. Nome do seu app. Precisa ser o mesmo nome aplicado ao atributo android:label do seu elemento do manifesto <activity> ou <application>. Esse rótulo só fica visível para o usuário quando você define android:includeInGlobalSearch como "true". Nesse caso, a etiqueta é usada para identificar seu app como um item pesquisável nas configurações de pesquisa do sistema.

android:hint

Recurso de string. Recomendado. Texto a ser exibido no campo de texto de pesquisa quando nenhum texto for inserido. Fornece uma dica para o usuário sobre qual conteúdo pode ser pesquisado. Para manter a consistência com outros apps para Android, formate a string de android:hint como "Pesquisar <conteúdo-ou-produto>". 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 atualmente definem como o texto da consulta será reescrito quando uma sugestão personalizada receber o foco. São aceitos os seguintes valores de modo:

Valor	Descrição
`"queryRewriteFromText"`	Usa o valor da coluna `SUGGEST_COLUMN_TEXT_1` para reescrever o texto da consulta.
`"queryRewriteFromData"`	Usa o valor da coluna `SUGGEST_COLUMN_INTENT_DATA` para reescrever o texto da consulta. É usado somente quando os valores em `SUGGEST_COLUMN_INTENT_DATA` forem adequados para inspeção e edição do usuário, normalmente URIs HTTP.

Para saber mais, consulte a discussão sobre como reescrever o texto da consulta em Como adicionar sugestões 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. Por esse motivo, não use esse atributo para mudar o botão, a menos que o comportamento seja 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, por exemplo, o tipo de teclado virtual. Esse atributo não é necessário na maior parte das pesquisas em que texto de formato livre é esperado. Consulte inputType para ver 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 editor de método de entrada (IME, na sigla em inglês) padrão é "actionSearch", que fornece o botão "Pesquisar" no lugar de um retorno de carro no teclado virtual. Consulte imeOptions para ver uma lista de valores adequados para esse atributo.

Atributos de sugestão de pesquisa

Se você definiu um provedor de conteúdo para gerar sugestões de pesquisa, é necessário definir atributos suplementares que configurem as comunicações com o provedor de conteúdo. Ao fornecer sugestões de pesquisa, você precisará 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 de consulta de sugestões, depois do prefixo e da autoridade, mas antes do caminho de sugestões padrão. Só é necessário caso você tenha um único provedor de conteúdo que emite diferentes tipos de sugestões (por exemplo, diferentes tipos de dados) e precise de uma maneira de eliminar a ambiguidade das consultas de sugestões ao recebê-las.
android:searchSuggestSelection: String. Esse valor é transmitido para a função de consulta como o parâmetro selection. Normalmente, essa é uma cláusula WHERE para o banco de dados e precisa conter um único ponto de interrogação, que é um marcador para a string de consulta real digitada pelo usuário (por exemplo, "query=?"). No entanto, você também pode usar qualquer valor não nulo para acionar a entrega do texto da consulta por meio do parâmetro selectionArgs (e ignorar o parâmetro selection).
android:searchSuggestIntentAction: String. Ação do intent padrão a ser usada quando um usuário clica em uma sugestão de pesquisa personalizada (por exemplo, "android.intent.action.VIEW"). Se não for substituído pela sugestão selecionada (por meio da coluna SUGGEST_COLUMN_INTENT_ACTION), esse valor será colocado no campo de ação de Intent quando o usuário clicar em uma sugestão.
android:searchSuggestIntentData: String. Dados do intent padrão a serem usados quando um usuário clicar 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 de Intent quando o usuário clicar em uma sugestão.
android:searchSuggestThreshold: Número inteiro. Número mínimo de caracteres necessários para acionar uma pesquisa de sugestão. Só garante que o sistema não consultará seu provedor de conteúdo para algo menor que o limite. O valor padrão é 0.

Para saber mais sobre os atributos acima para sugestões de pesquisa, consulte os guias Como adicionar sugestões de consultas recentes e Como adicionar sugestões personalizadas.

Atributos da caixa de pesquisa rápida

Para disponibilizar suas sugestões de pesquisa personalizadas para a caixa de pesquisa rápida, você precisa de alguns destes atributos <searchable>:

android:includeInGlobalSearch: Booleano Obrigatório para fornecer sugestões na caixa de pesquisa rápida. Defina como "true" caso queira que suas sugestões sejam incluídas na caixa de pesquisa rápida acessível globalmente. O usuário ainda precisa ativar seu 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: String. Oferece uma breve descrição das sugestões que você fornece à caixa de pesquisa rápida, que é exibida na entrada de itens pesquisáveis do app. Sua descrição precisa descrever o conteúdo pesquisável de forma concisa. 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" caso queira que seu provedor de conteúdo seja invocado para grandes conjuntos de consultas que não retornaram nenhum resultado no passado. Por exemplo, caso seu provedor de conteúdo não tenha retornado nenhum resultado para "bo", ele deve ser obrigatório para "bob". Se definido como "false", os grandes conjuntos serão ignorados para uma única sessão ("bob" não invoca uma repetição da consulta). Permanece somente durante a vida útil da caixa de pesquisa ou da atividade ao usar o widget de pesquisa. Quando a caixa de diálogo ou atividade de pesquisa abrem novamente, "bo" consulta seu provedor de conteúdo mais uma vez. O valor padrão é "false".

Atributos de pesquisa por voz

Para ativar a pesquisa por voz, você precisará 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 nenhum 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 por uma barra vertical "\|").
`"launchWebSearch"`	O botão de pesquisa por voz leva o usuário diretamente a uma atividade de pesquisa por voz incorporada na Web. A maioria dos apps não precisa dessa sinalização, 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 da consulta resultante para a atividade de pesquisa, exatamente como se o usuário tivesse digitado na IU de pesquisa e clicado no botão de pesquisa.

android:voiceLanguageModel

Palavra-chave. Modelo do idioma a 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. É otimizado principalmente para o inglês. Esse é o padrão.
`"web_search"`	Usa reconhecimento de termos de pesquisa da Web para frases curtas, usadas em pesquisas. Está disponível em mais idiomas que "free_form".

Consulte também EXTRA_LANGUAGE_MODEL para saber mais.

android:voicePromptText

String. Uma mensagem complementar a ser exibida na caixa de diálogo de entrada de texto por voz.

android:voiceLanguage

String. Idioma falado esperado, expressado como o valor da string de uma constante em Locale (por exemplo, "de" para alemão ou "fr" para francês). Só é necessário caso seja diferente do valor atual de Locale.getDefault().

android:voiceMaxResults

Número inteiro. Força o número máximo de resultados a serem retornados, incluindo o “melhor” resultado, que é sempre fornecido como a principal consulta do intent ACTION_SEARCH. Precisa ser 1 ou mais. Use EXTRA_RESULTS para ver os resultados do 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 fornece um comportamento especial com o toque de um botão no dispositivo, com base na consulta atual ou na sugestão em foco. Por exemplo, o app Contatos oferece uma ação de pesquisa para iniciar uma chamada telefônica para a sugestão de contato em foco no momento ao pressionar o botão "CHAMAR".

Nem todas as teclas de ação estão disponíveis em todos os dispositivos, e nem todas as teclas podem ser substituídas dessa forma. Por exemplo, a tecla "Início" não pode ser usada e precisa sempre retornar à tela inicial. Lembre-se de não definir uma tecla de ação para uma tecla que é necessária para digitar uma consulta de pesquisa. Isso basicamente limita as teclas de ação disponíveis e razoáveis ao botão de chamada e ao botão de menu. Além disso, as teclas de ação geralmente não são detectáveis. Por esse motivo, elas não podem ser fornecidas como um recurso fundamental do usuário.

Você precisa definir o 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 ("KEYCODE_CALL", por exemplo). É adicionado ao intent ACTION_SEARCH que é transmitido para sua atividade de pesquisa. Para examinar o código da tecla, use getIntExtra(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 está inserindo o texto de uma consulta. É adicionado ao intent ACTION_SEARCH que o sistema passa para sua atividade de pesquisa. Para examinar a string, use getStringExtra(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 ao intent que o sistema transmite para sua atividade de pesquisa (usando a ação definida para a sugestão). Para examinar a string, use getStringExtra(SearchManager.ACTION_MSG). Só pode ser usado se todas as sugestões forem compatíveis com essa tecla de ação. Caso nem todas as sugestões possam processar a mesma tecla de ação, será necessário usar o atributo android:suggestActionMsgColumn a seguir.
android:suggestActionMsgColumn: String. Nome da coluna no seu provedor de conteúdo que define a mensagem 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 que você controle a tecla de ação com base em cada 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 provedor de conteúdo fornece a própria mensagem de ação.
Primeiramente, é necessário definir uma coluna no seu provedor de conteúdo para que cada sugestão forneça uma mensagem de ação e, então, colocar o nome dessa coluna no atributo. O sistema analisa seu cursor de sugestões, usando a string fornecida aqui para selecionar sua coluna de mensagem de ação e, em seguida, selecionar 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 existirem 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>