Configuração de pesquisa

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ê define android: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:
ValorDescriçã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 em SUGGEST_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. Consulte imeOptions 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âmetro selectionArgs e ignorar o parâmetro selection.
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 coluna SUGGEST_COLUMN_INTENT_ACTION, o valor será colocado no campo de ação de Intent 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 de Intent 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:
ValorDescriçã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:
ValorDescriçã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 de Locale.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. Use EXTRA_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 à intent ACTION_SEARCH que é transmitida para sua atividade de pesquisa. Para examinar o código de 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 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, 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 à 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 atributo android: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>