Esta página foi traduzida pela API Cloud Translation.

Configuração da pesquisa

Para implementar a pesquisa com assistência do sistema Android (ou seja, 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 aplicativo, consulte Criar uma interface de pesquisa.

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. O 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 definem como o texto da consulta precisa ser reescrito quando uma sugestão personalizada recebe o 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 da consulta. Isso só deve ser usado 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. Por isso, 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 maioria das pesquisas em que o 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 IME padrão é actionSearch, que fornece o botão "Pesquisar" em vez 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ê 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ê 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 da consulta de sugestões Uri, depois do prefixo e da autoridade, e antes do caminho de sugestões padrão. Isso só é necessário se você tiver um único provedor de conteúdo que emite diferentes tipos de sugestões, como para diferentes tipos de dados, e precisar 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 seu banco de dados e precisa conter um único ponto de interrogação como marcador de posição para a string de consulta real inserida 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 usando o parâmetro selectionArgs e ignorar o parâmetro selection.
android:searchSuggestIntentAction: String. A ação do 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, ele 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 tocar 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 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 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.

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" se quiser 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: Recurso de 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" se quiser que seu provedor de conteúdo seja invocado para grandes conjuntos de consultas que não retornaram nenhum resultado antes. Por exemplo, se seu provedor de conteúdo não retornar nenhum resultado para "bo", ele deverá 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. Isso dura apenas 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 é 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 flags 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 pelo caractere de 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 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 da consulta resultante para a atividade de pesquisa, exatamente como se o usuário tivesse digitado na IU de pesquisa e tocado no botão de pesquisa.

android:voiceLanguageModel

Palavra-chave. O modelo de idioma que deve 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. Ele está disponível em mais idiomas que `"free_form"`.

Consulte EXTRA_LANGUAGE_MODEL para mais informações.

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 da string de uma constante em Locale, como "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. Define o número máximo de resultados a serem retornados, incluindo o "melhor" resultado, que é sempre fornecido como a consulta principal do 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 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 tocar no 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 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.

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, por exemplo, "KEYCODE_CALL". Isso é 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. Ele é 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. O 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.
Primeiro, defina uma coluna no seu provedor de conteúdo para cada sugestão que vai fornecer uma mensagem de ação e, em seguida, coloque 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, 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 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>

Configuração da pesquisa Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Atributos de sugestão de pesquisa

Atributos da caixa de pesquisa rápida

Atributos de pesquisa por voz

Configuração da pesquisa