Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configuração da pesquisa

Para implementar a pesquisa com 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 saber mais sobre como implementar recursos de pesquisa para seu app, 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. O nome do seu aplicativo. Precisa ser o mesmo que o nome aplicado ao atributo android:label do seu <activity> ou <application> elemento do manifesto. 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. Ele fornece uma dica ao usuário sobre o conteúdo pesquisável. Para manter a consistência com outros aplicativos Android, formate a string para 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 o foco. São aceitos os seguintes valores de modo:

Valor	Descrição
`"queryRewriteFromData"`	Use o valor da `SUGGEST_COLUMN_INTENT_DATA` coluna para reescrever o texto da consulta. Isso só pode ser usado quando os valores em `SUGGEST_COLUMN_INTENT_DATA` são adequados para inspeção e edição do usuário, como URIs HTTP.
`"queryRewriteFromText"`	Use o valor da `SUGGEST_COLUMN_TEXT_1` coluna 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, 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 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" no lugar de um retorno de carro no teclado de software. Consulte imeOptions para 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, é 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 android:authorities atributo do manifesto do Android <provider> elemento.
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.Uri 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 receber elas.
android:searchSuggestSelection: String. Esse valor é transmitido para sua função de consulta como o selection parâmetro. Normalmente, essa é uma cláusula WHERE para o banco de dados e precisa conter um único ponto de interrogação como um marcador 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 selectionArgs parâmetro e ignorar o selection parâmetro).
android:searchSuggestIntentAction: String. A ação da intent padrão a ser usada quando um usuário clica 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 SUGGEST_COLUMN_INTENT_ACTION coluna, o valor será colocado no campo de ação do 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 clica em uma sugestão de pesquisa personalizada. Se não for substituído pela sugestão selecionada (pela SUGGEST_COLUMN_INTENT_DATA coluna), esse valor será colocado no campo de dados do 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. 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 saber mais sobre os atributos acima para sugestões de pesquisa, consulte a documentação para adicionar sugestões de pesquisa personalizadas e 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" 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: 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 de forma concisa o conteúdo pesquisável. Por exemplo, "Artistas, álbuns e faixas" para um aplicativo de música ou "Notas salvas" para um aplicativo 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 <searchable> atributos:

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, então `"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 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 da consulta resultante para a atividade de pesquisa, exatamente como se o usuário tivesse digitado na interface de pesquisa e clicado no botão de pesquisa.

android:voiceLanguageModel

Palavra-chave. O modelo de linguagem 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. Ele é 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. Ele está disponível em mais idiomas do 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 de string de uma constante em Locale, como "de" para alemão ou "fr" para francês. Isso só é necessário 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 ACTION_SEARCH consulta principal do intent. Precisa ser 1 ou mais. Use EXTRA_RESULTS para receber 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 comportamento com o toque de um botão no dispositivo, com base na consulta atual ou na sugestão em foco sugestão. Por exemplo, o aplicativo de 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 "Home" não pode ser substituída 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 limita as teclas de ação disponíveis e razoáveis ao botão de chamada e ao botão de menu botão.

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". Ele é adicionado ao ACTION_SEARCH intent transmitido à 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. Ela é adicionada ao ACTION_SEARCH intent que o sistema transmite à 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. Ela é adicionada ao intent que o sistema transmite à sua atividade de pesquisa, usando a ação definida para a sugestão. Para examinar a string, use getStringExtra(SearchManager.ACTION_MSG). Isso só pode 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 android:suggestActionMsgColumn atributo.
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 android:suggestActionMsg atributo 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, seleciona a string da mensagem de ação do cursor. Essa string é adicionada ao intent que o sistema transmite à sua atividade de pesquisa, usando a ação que você define 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