Ao usar a caixa de diálogo ou o widget de pesquisa do Android, é possível fornecer sugestões de pesquisa personalizadas criadas com base nos dados do seu app. Por exemplo, se o app for um dicionário, você poderá sugerir palavras desse dicionário que correspondam ao texto inserido no campo de pesquisa antes de o usuário terminar de digitar a consulta. Essas sugestões são valiosas porque podem prever com eficácia o que o usuário quer e fornecer acesso instantâneo a isso. A Figura 1 mostra um exemplo de uma caixa de diálogo de pesquisa com sugestões personalizadas.
Depois de fornecer sugestões personalizadas, você também pode disponibilizá-las para a caixa de pesquisa rápida do sistema, fornecendo acesso ao seu conteúdo de fora do app.
Antes de adicionar sugestões personalizadas, implemente a caixa de diálogo ou um widget de pesquisa do Android para buscas no seu app. Consulte Criar uma interface de pesquisa e Provedores de conteúdo.
Noções básicas
![](https://developer.android.google.cn/static/images/search/search-suggest-custom.png?authuser=5&hl=pt-br)
Figura 1. Captura de tela de uma caixa de diálogo de pesquisa com sugestões de pesquisa personalizadas.
Quando o usuário seleciona uma sugestão personalizada, o sistema envia um
Intent
para sua
atividade pesquisável. Ao contrário de uma consulta de pesquisa normal que envia uma intent com a ação
ACTION_SEARCH
, você pode definir suas sugestões personalizadas para usar
ACTION_VIEW
(ou
qualquer outra ação de intent) e também incluir dados relevantes para a
sugestão selecionada. No exemplo do dicionário, quando o usuário seleciona uma
sugestão, o app pode abrir imediatamente a definição dessa palavra em vez
de pesquisar correspondências no dicionário.
Para fornecer sugestões personalizadas, siga estas etapas:
- Implemente uma atividade básica de pesquisa, conforme descrito em Criar uma interface de pesquisa.
- Modificar a configuração pesquisável com informações sobre o provedor de conteúdo que fornece sugestões personalizadas.
- Crie uma tabela para suas sugestões, como em
SQLiteDatabase
, e a formate com as colunas obrigatórias. - Crie um provedor de conteúdo que tenha acesso à sua tabela de sugestões e declare o provedor no seu manifesto.
- Declare o tipo de
Intent
a ser enviado quando o usuário selecionar uma sugestão, incluindo uma ação e dados personalizados.
Assim como o sistema Android exibe a caixa de diálogo de pesquisa, ele também mostra suas sugestões de pesquisa. Você precisa de um provedor de conteúdo de onde o sistema possa extrair suas sugestões. Leia Provedores de conteúdo para saber como criar um provedor de conteúdo.
Quando o sistema identifica que sua atividade é pesquisável e fornece sugestões de pesquisa, o procedimento a seguir ocorre quando o usuário insere uma consulta:
- O sistema usa o texto da consulta de pesquisa, ou seja, o que foi inserido até o momento, e executa uma consulta ao provedor de conteúdo que gerencia suas sugestões.
- Seu provedor de conteúdo retorna um
Cursor
que aponta para todas as sugestões relevantes para o texto da consulta de pesquisa. - O sistema mostra a lista de sugestões fornecidas pelo
Cursor
.
Depois que as sugestões personalizadas são exibidas, pode ocorrer o seguinte:
- Se o usuário inserir outra letra ou mudar a consulta, as etapas anteriores serão repetidas, e a lista de sugestões será atualizada de acordo.
- Se o usuário executar a pesquisa, as sugestões serão ignoradas, e a pesquisa será entregue à atividade de pesquisa usando o intent
ACTION_SEARCH
normal. - Se o usuário selecionar uma sugestão, uma intent será enviada à sua atividade de pesquisa, carregando uma ação e dados personalizados para que seu app possa abrir o conteúdo sugerido.
Modificar a configuração pesquisável
Para adicionar suporte a sugestões personalizadas, adicione o
atributo android:searchSuggestAuthority
ao
elemento <searchable>
no arquivo de configuração pesquisável,
conforme mostrado no exemplo a seguir.
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"> </searchable>
Talvez sejam necessários outros atributos, dependendo do tipo de intent anexada a cada sugestão e de como você quer formatar consultas para seu provedor de conteúdo. Os outros atributos opcionais são discutidos nas seções a seguir.
Criar um provedor de conteúdo
Para criar um provedor de conteúdo para sugestões personalizadas, primeiro consulte
Provedores de conteúdo
para saber como criar um provedor de conteúdo. Um provedor de conteúdo para sugestões
personalizadas é semelhante a qualquer outro provedor de conteúdo. No entanto, para cada
sugestão que você fornecer, a respectiva linha no Cursor
precisa
incluir colunas específicas que o sistema entende e usa para formatar as
sugestões.
Quando o usuário insere texto na caixa de diálogo ou no widget de pesquisa, o sistema
consulta o provedor de conteúdo em busca de sugestões chamando
query()
sempre que uma letra é inserida. Na implementação de query()
,
seu provedor de conteúdo precisa pesquisar seus dados de sugestão e retornar um
Cursor
que aponte para as linhas que ele determinar que são boas
sugestões.
Os detalhes sobre a criação de um provedor de conteúdo para sugestões personalizadas são discutidos nas duas seções a seguir:
- Processar a consulta de sugestão
- Como o sistema envia solicitações para seu provedor de conteúdo e como lidar com elas.
- Criar uma tabela de sugestões
- Como definir as colunas que o sistema espera em
Cursor
retornadas com cada consulta.
Processar a consulta de sugestão
Quando o sistema solicita sugestões do seu provedor de conteúdo, ele chama
o método query()
do provedor. Implemente esse método para
pesquisar seus dados de sugestão e retornar um Cursor
que aponta para as
sugestões que você considera relevantes.
Confira um resumo dos parâmetros que o sistema transmite ao método
query()
, listados em ordem:
uri
Sempre um conteúdo
Uri
, formatado da seguinte maneira:content://your.authority/optional.suggest.path/
SUGGEST_URI_PATH_QUERY
O comportamento padrão é que o sistema transmita esse URI e anexe o texto da consulta a ele:
content://your.authority/optional.suggest.path/
SUGGEST_URI_PATH_QUERY
/puppiesO texto da consulta no final é codificado usando regras de codificação de URI. Portanto, talvez seja necessário decodificá-lo antes de realizar uma pesquisa.
A parte
optional.suggest.path
só vai ser incluída no URI se você definir esse caminho no arquivo de configuração pesquisável com o atributoandroid:searchSuggestPath
. Isso só é necessário se você usar o mesmo provedor de conteúdo para várias atividades de pesquisa. Se esse for o caso, remova a ambiguidade da origem da consulta de sugestão.projection
- Sempre nulo.
selection
- O valor fornecido no atributo
android:searchSuggestSelection
do seu arquivo de configuração pesquisável ou nulo se você não declarar o atributoandroid:searchSuggestSelection
. A seção a seguir discute esse assunto em mais detalhes.selectionArgs
- Contém a consulta de pesquisa como o primeiro e único elemento da matriz se você declarar o atributo
android:searchSuggestSelection
na sua configuração pesquisável. Se você não declararandroid:searchSuggestSelection
, esse parâmetro será nulo. A seção a seguir discute esse assunto em mais detalhes.sortOrder
- Sempre nulo.
O sistema pode enviar o texto da consulta de pesquisa de duas maneiras. A maneira padrão é
incluir o texto da consulta como o último caminho do URI de conteúdo transmitido
no parâmetro uri
. No entanto, se você incluir um valor de seleção no
atributo android:searchSuggestSelection
da sua configuração pesquisável, o texto da consulta vai ser transmitido como o primeiro elemento da
matriz de strings selectionArgs
. Essas duas opções são descritas a seguir.
Conseguir a consulta no URI
Por padrão, a consulta é anexada como o último segmento do parâmetro uri
, um objeto Uri
. Para recuperar o texto da consulta nesse
caso, use
getLastPathSegment()
,
como mostrado no exemplo a seguir:
Kotlin
val query: String = uri.lastPathSegment.toLowerCase()
Java
String query = uri.getLastPathSegment().toLowerCase();
Isso retorna o último segmento do Uri
, que é o texto de consulta que o usuário insere.
Conseguir a consulta nos argumentos de seleção
Em vez de usar o URI, faz mais sentido que o método
query()
receba tudo o que é necessário para realizar a
pesquisa. Talvez você queira que os parâmetros selection
e
selectionArgs
carreguem os valores apropriados. Nesse
caso, adicione o atributo android:searchSuggestSelection
à sua
configuração pesquisável com a string de seleção do SQLite. Na string de seleção, inclua um ponto de interrogação (?) como marcador para a consulta de pesquisa real. O sistema chama query()
com a string de seleção como
o parâmetro selection
e a consulta de pesquisa como o primeiro elemento
na matriz selectionArgs
.
Por exemplo, veja como formar o
atributo android:searchSuggestSelection
para criar uma instrução
de pesquisa de texto completo:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestSelection="word MATCH ?"> </searchable>
Com essa configuração, o método query()
entrega o
parâmetro selection
como "word MATCH ?"
e o
parâmetro selectionArgs
como a consulta de pesquisa. Quando você os transmite para
um método
query()
do SQLite, como os respectivos argumentos, eles são sintetizados
juntos, ou seja, o ponto de interrogação é substituído pelo texto da consulta. Se
você receber consultas de sugestão dessa maneira e precisar adicionar caracteres curinga ao texto da
consulta, anexe-os ou prefixe-os ao parâmetro selectionArgs
, porque
esse valor é colocado entre aspas e inserido no lugar do ponto de interrogação.
Outro atributo no exemplo anterior é
android:searchSuggestIntentAction
, que define a ação da intent
enviada com cada intent quando o usuário seleciona uma sugestão. Isso é discutido
mais adiante na seção Declarar uma intent para
sugestões.
Criar uma tabela de sugestões
Quando você retorna sugestões para o sistema com um Cursor
, ele
espera colunas específicas em cada linha. Independente de você armazenar
os dados de sugestão em um banco de dados SQLite no dispositivo, em um servidor
da Web ou em outro formato no dispositivo ou na Web, formate as sugestões como linhas
em uma tabela e as apresente com um Cursor
.
O sistema entende várias colunas, mas apenas duas delas são necessárias:
_ID
- Um ID único de linha de números inteiros para cada sugestão. O sistema exige isso para apresentar sugestões em um
ListView
. SUGGEST_COLUMN_TEXT_1
- A string que é apresentada como uma sugestão.
Todas as colunas a seguir são opcionais. Vamos falar mais sobre eles nas seções a seguir.
SUGGEST_COLUMN_TEXT_2
- Uma string. Se
Cursor
incluir essa coluna, todas as sugestões serão fornecidas em um formato de duas linhas. A string nessa coluna é exibida como uma segunda linha menor de texto, abaixo do texto de sugestão principal. Ela pode ser nula ou vazia para indicar que não há texto secundário. SUGGEST_COLUMN_ICON_1
- Uma string de recurso drawable, de conteúdo ou de URI de arquivo. Se o
Cursor
incluir essa coluna, todas as sugestões serão fornecidas em um formato de ícone mais texto, com o ícone do drawable no lado esquerdo. Pode ser nulo ou zero para indicar que não há ícone nessa linha. SUGGEST_COLUMN_ICON_2
- Uma string de recurso drawable, de conteúdo ou de URI de arquivo. Se o
Cursor
incluir essa coluna, todas as sugestões serão fornecidas em um formato de ícone mais texto, com o ícone ao lado direito. Pode ser nulo ou zero para indicar que não há ícone nessa linha. SUGGEST_COLUMN_INTENT_ACTION
- Uma string de ação de intent. Se essa coluna existir e incluir um valor na linha especificada, a ação definida aqui será usada ao formar o intent da sugestão. Se o elemento não for fornecido, a ação será extraída do campo
android:searchSuggestIntentAction
na sua configuração pesquisável. Se sua ação for a mesma para todas as sugestões, é mais eficiente especificar a ação usandoandroid:searchSuggestIntentAction
e omitir essa coluna. SUGGEST_COLUMN_INTENT_DATA
- String de URI de dados. Se essa coluna existir e incluir um valor na linha especificada, esses dados serão usados ao formar a intent da sugestão. Se o elemento não for fornecido, os dados serão extraídos do campo
android:searchSuggestIntentData
na sua configuração pesquisável. Se nenhuma das origens for informada, o campo de dados da intent será nulo. Se os dados forem os mesmos para todas as sugestões ou puderem ser descritos usando uma parte constante e um ID específico, será mais eficiente especificá-los usandoandroid:searchSuggestIntentData
e omitir essa coluna. SUGGEST_COLUMN_INTENT_DATA_ID
- String de caminho de URI. Se essa coluna existir e incluir um valor na linha especificada, "/" e esse valor serão anexados ao campo de dados na intent.
Use isso somente se o campo de dados especificado pelo
atributo
android:searchSuggestIntentData
na configuração pesquisável já estiver definido como uma string de base adequada. SUGGEST_COLUMN_INTENT_EXTRA_DATA
- Dados arbitrários. Se essa coluna existir e incluir um valor em uma determinada linha,
esses serão os dados extras usados ao formar o intent da sugestão.
Se não for fornecido, o campo de dados extra da intent será nulo. Essa coluna permite
que as sugestões forneçam outros dados incluídos como um extra na
chave
EXTRA_DATA_KEY
da intent. SUGGEST_COLUMN_QUERY
- Se essa coluna existir e esse elemento existir na linha especificada, esses serão
os dados usados ao formar a consulta da sugestão, incluídos como um
extra na chave
QUERY
da intent. Ele é necessário se a ação da sugestão éACTION_SEARCH
, mas é opcional se não for. SUGGEST_COLUMN_SHORTCUT_ID
- Só é usada ao fornecer sugestões para a caixa de pesquisa rápida. Essa coluna indica se uma sugestão de pesquisa precisa ser armazenada como um atalho e se precisa ser validada. Os atalhos geralmente são formados quando o usuário toca em uma sugestão da caixa de pesquisa rápida. Se estiver ausente, o resultado será armazenado como
um atalho e nunca será atualizado. Se definido como
SUGGEST_NEVER_MAKE_SHORTCUT
, o resultado não será armazenado como um atalho. Caso contrário, o ID do atalho será usado para conferir se há uma sugestão atualizada usandoSUGGEST_URI_PATH_SHORTCUT
. SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
- Só é usada ao fornecer sugestões para a caixa de pesquisa rápida. Essa coluna
especifica que um ícone de carregamento precisa ser mostrado em vez de um ícone de
SUGGEST_COLUMN_ICON_2
enquanto o atalho dessa sugestão é atualizado na caixa de pesquisa rápida.
A maioria dessas colunas é discutida em mais detalhes nas seções a seguir.
Declarar uma intent para sugestões
Quando o usuário seleciona uma sugestão da lista que aparece abaixo do widget ou da caixa de diálogo de pesquisa, o sistema envia uma Intent
personalizada para a atividade pesquisável. Você precisa definir a ação e os dados para a intent.
Declarar a ação da intent
A ação de intent mais comum para uma sugestão personalizada é
ACTION_VIEW
, que é adequada quando você quer abrir algo,
como a definição de uma palavra, os dados de contato de uma pessoa ou uma página da Web.
No entanto, a ação da intent pode ser qualquer outra ação e pode ser diferente para cada
sugestão.
Dependendo se você quer que todas as sugestões usem a mesma ação de intent, é possível definir a ação de duas maneiras:
- Use o atributo
android:searchSuggestIntentAction
do seu arquivo de configuração pesquisável para definir a ação para todas as sugestões, conforme mostrado no exemplo a seguir:<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" > </searchable>
- Use a coluna
SUGGEST_COLUMN_INTENT_ACTION
para definir a ação para sugestões individuais. Para fazer isso, adicione a colunaSUGGEST_COLUMN_INTENT_ACTION
à sua tabela de sugestões e, para cada sugestão, coloque-a na ação a ser usada, como"android.intent.action.VIEW"
.
Você também pode combinar essas duas técnicas. Por exemplo, você pode incluir o atributo
android:searchSuggestIntentAction
com uma ação a ser
usada com todas as sugestões por padrão e depois modificar essa ação para algumas
sugestões declarando uma ação diferente na
coluna SUGGEST_COLUMN_INTENT_ACTION
. Se você não incluir um valor
na coluna SUGGEST_COLUMN_INTENT_ACTION
, a intent
fornecida no atributo android:searchSuggestIntentAction
será
usada.
Declarar dados de intent
Quando o usuário seleciona uma sugestão, sua atividade de pesquisa recebe a
intent com a ação definida, conforme discutido na seção
anterior. No entanto, a intent também precisa transportar dados para a atividade a fim de identificar
qual sugestão está selecionada. Especificamente, os dados precisam ser algo único
para cada sugestão, como o ID da linha da sugestão na sua tabela SQLite.
Quando a intent for recebida, será possível recuperar os dados anexados com
getData()
ou
getDataString()
.
É possível definir os dados incluídos no intent de duas maneiras:
- Defina os dados para cada sugestão dentro da coluna
SUGGEST_COLUMN_INTENT_DATA
da sua tabela de sugestões.Forneça todas as informações de dados necessárias para cada intent na tabela de sugestões incluindo a coluna
SUGGEST_COLUMN_INTENT_DATA
e preenchendo-a com dados exclusivos para cada linha. Os dados dessa coluna são anexados ao intent exatamente como você o define nessa coluna. Depois, ela pode ser recuperada comgetData()
ougetDataString()
. - Fragmentar um URI de dados em duas partes: a parte comum a todas as sugestões
e a parte exclusiva a cada sugestão. Coloque essas partes no
atributo
android:searchSuggestintentData
da configuração pesquisável e na colunaSUGGEST_COLUMN_INTENT_DATA_ID
da tabela de sugestões, respectivamente.O exemplo a seguir mostra como declarar a parte do URI que é comum a todas as sugestões no atributo
android:searchSuggestIntentData
da sua configuração pesquisável:<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestIntentData="content://com.example/datatable" > </searchable>
Inclua o caminho final de cada sugestão (a parte única) na coluna
SUGGEST_COLUMN_INTENT_DATA_ID
da tabela de sugestões. Quando o usuário seleciona uma sugestão, o sistema usa a string deandroid:searchSuggestIntentData
, anexa uma barra (/) e adiciona o respectivo valor da colunaSUGGEST_COLUMN_INTENT_DATA_ID
para formar um URI de conteúdo completo. Depois, você pode recuperar oUri
comgetData()
.
Adicionar mais dados
Caso precise expressar mais informações com a intent, adicione outra
coluna da tabela, como SUGGEST_COLUMN_INTENT_EXTRA_DATA
, que pode
armazenar mais informações sobre a sugestão. Os dados salvos nessa coluna
são colocados no EXTRA_DATA_KEY
do pacote extra da intent.
Processar a intent
Depois de fornecer sugestões de pesquisa personalizadas com intents personalizadas, você precisa
da sua atividade de pesquisa para processar essas intents quando o usuário selecionar uma
sugestão. Além de processar a intent ACTION_SEARCH
, o que sua atividade de pesquisa já faz. Confira um exemplo de como
processar as intents durante o callback
onCreate()
da atividade:
Kotlin
when(intent.action) { Intent.ACTION_SEARCH -> { // Handle the normal search query case. intent.getStringExtra(SearchManager.QUERY)?.also { query -> doSearch(query) } } Intent.ACTION_VIEW -> { // Handle a suggestions click, because the suggestions all use ACTION_VIEW. showResult(intent.data) } }
Java
Intent intent = getIntent(); if (Intent.ACTION_SEARCH.equals(intent.getAction())) { // Handle the normal search query case. String query = intent.getStringExtra(SearchManager.QUERY); doSearch(query); } else if (Intent.ACTION_VIEW.equals(intent.getAction())) { // Handle a suggestions click, because the suggestions all use ACTION_VIEW. Uri data = intent.getData(); showResult(data); }
Nesse exemplo, a ação da intent é ACTION_VIEW
, e os dados
contêm um URI completo que aponta para o item sugerido, conforme sintetizado pela
string android:searchSuggestIntentData
e pela coluna
SUGGEST_COLUMN_INTENT_DATA_ID
. O URI é transmitido para o
método local showResult()
, que consulta o provedor de conteúdo em busca do
item especificado pelo URI.
Reescrever o texto da consulta
Por padrão, se o usuário navegar pela lista de sugestões usando controles direcionais, como com um trackball ou botão direcional, o texto da consulta não será atualizado. No entanto, é possível reescrever temporariamente o texto da consulta do usuário conforme ele aparece na caixa de texto com uma consulta que corresponda à sugestão em foco. Isso permite que o usuário veja a consulta que está sendo sugerida e pode selecionar a caixa de pesquisa e editá-la antes de enviá-la como uma pesquisa.
Você pode reescrever o texto da consulta das seguintes maneiras:
- Adicione o atributo
android:searchMode
à sua configuração pesquisável com o valor"queryRewriteFromText"
. Nesse caso, o conteúdo da colunaSUGGEST_COLUMN_TEXT_1
da sugestão é usado para reescrever o texto da consulta. - Adicione o atributo
android:searchMode
à configuração pesquisável com o valor"queryRewriteFromData"
. Nesse caso, o conteúdo da colunaSUGGEST_COLUMN_INTENT_DATA
da sugestão é usado para reescrever o texto da consulta. Use-o somente com URIs ou outros formatos de dados que precisam ser visíveis ao usuário, como URLs HTTP. Não use esquemas de URI internos para reescrever a consulta dessa maneira. - Forneça uma string de texto de consulta exclusiva na coluna
SUGGEST_COLUMN_QUERY
da sua tabela de sugestões. Se essa coluna estiver presente e contiver um valor para a sugestão atual, ela será usada para reescrever o texto da consulta e substituir qualquer uma das implementações anteriores.
Expor sugestões de pesquisa na caixa de pesquisa rápida
Depois de configurar o app para oferecer sugestões de pesquisa personalizadas, disponibilizá-las
para a caixa de pesquisa rápida acessível globalmente é tão fácil quanto modificar
sua configuração pesquisável para incluir
android:includeInGlobalSearch
com o valor
"true"
.
O único cenário em que mais trabalho é necessário é quando seu provedor
de conteúdo exige uma permissão de leitura. Nesse caso, é necessário adicionar um
elemento <path-permission>
para que o provedor conceda acesso de leitura da caixa de
pesquisa rápida ao seu provedor de conteúdo, conforme mostrado no exemplo
abaixo.
<provider android:name="MySuggestionProvider" android:authorities="com.example.MyCustomSuggestionProvider" android:readPermission="com.example.provider.READ_MY_DATA" android:writePermission="com.example.provider.WRITE_MY_DATA"> <path-permission android:pathPrefix="/search_suggest_query" android:readPermission="android.permission.GLOBAL_SEARCH" /> </provider>
Nesse exemplo, o provedor restringe o acesso de leitura e gravação ao conteúdo.
O elemento <path-permission>
altera a restrição concedendo acesso de leitura ao conteúdo dentro do prefixo de caminho "/search_suggest_query"
quando a permissão "android.permission.GLOBAL_SEARCH"
existe. Isso concede acesso à caixa de pesquisa rápida para que ela possa consultar sugestões do seu provedor
de conteúdo.
Se o provedor de conteúdo não impõe permissões de leitura, a caixa de pesquisa rápida faz a leitura por padrão.
Ativar sugestões em um dispositivo
Por padrão, os apps não estão ativados para oferecer sugestões na caixa de pesquisa rápida, mesmo que estejam configurados para isso. O usuário escolhe se quer incluir sugestões do app na caixa de pesquisa rápida abrindo Itens pesquisáveis (em Configurações > Pesquisa) e ativando o app como um item pesquisável.
Cada app disponível para a caixa de pesquisa rápida tem uma entrada na
página de configurações de Itens pesquisáveis. A entrada inclui o nome do app
e uma breve descrição do conteúdo que pode ser pesquisado no app e disponibilizado
para sugestões na caixa de pesquisa rápida. Para definir o texto de descrição
do app pesquisável, adicione o atributo android:searchSettingsDescription
à configuração pesquisável, conforme mostrado no exemplo
a seguir:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:includeInGlobalSearch="true" android:searchSettingsDescription="@string/search_description" > </searchable>
Torne a string de android:searchSettingsDescription
o mais concisa
possível e declare 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.
É importante fornecer essa descrição para que o usuário saiba que tipo de
sugestões são fornecidas. Sempre inclua esse atributo quando
android:includeInGlobalSearch
for verdadeiro.
Como o usuário precisa acessar o menu de configurações para ativar as sugestões de pesquisa para seu app, se a pesquisa for um aspecto importante do app, considere como transmitir isso aos usuários. Por exemplo, você pode fornecer uma observação na primeira vez que um usuário iniciar o app explicando como ativar as sugestões de pesquisa para a caixa de pesquisa rápida.
Gerenciar atalhos de sugestões da caixa de pesquisa rápida
As sugestões que o usuário seleciona na caixa de pesquisa rápida podem ser transformadas em atalhos automaticamente. Essas são sugestões que o sistema copia do provedor de conteúdo para acessar rapidamente a sugestão sem precisar consultar novamente.
Por padrão, isso é ativado para todas as sugestões recuperadas pela caixa de pesquisa
rápida, mas se os dados de sugestão mudarem com o tempo, você poderá solicitar que
os atalhos sejam atualizados. Por exemplo, se as sugestões se referirem a dados
dinâmicos, como o status de presença de um contato, solicite que os atalhos
de sugestão sejam atualizados quando forem mostrados ao usuário. Para fazer isso, inclua o
SUGGEST_COLUMN_SHORTCUT_ID
na sua tabela de sugestões. É possível usar
essa coluna para configurar o comportamento de atalho para cada sugestão de uma das
seguintes maneiras:
Faça com que a Caixa de pesquisa rápida consulte novamente o provedor de conteúdo para conseguir uma nova versão do atalho de sugestão.
Forneça um valor na coluna
SUGGEST_COLUMN_SHORTCUT_ID
para que a sugestão seja consultada novamente para uma nova versão sempre que o atalho for exibido. O atalho é exibido rapidamente com os dados disponíveis mais recentemente até que a consulta de atualização retorne. Nesse momento, a sugestão é atualizada com as novas informações. A consulta de atualização é enviada ao seu provedor de conteúdo com um caminho de URI deSUGGEST_URI_PATH_SHORTCUT
, em vez deSUGGEST_URI_PATH_QUERY
.Faça com que o
Cursor
retornado contenha uma sugestão usando as mesmas colunas da sugestão original ou esteja vazio, indicando que o atalho não é mais válido. Nesse caso, a sugestão desaparece e o atalho é removido.Se uma sugestão se referir a dados que podem levar mais tempo para serem atualizados, como uma atualização baseada em rede, também será possível adicionar a coluna
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
à sua tabela de sugestões com um valor verdadeiro para mostrar um ícone de carregamento do progresso do ícone à direita até que a atualização seja concluída. Qualquer valor diferente de "true" não mostra o ícone de carregamento de progresso.Impede que a sugestão seja copiada em um atalho.
Forneça um valor de
SUGGEST_NEVER_MAKE_SHORTCUT
na colunaSUGGEST_COLUMN_SHORTCUT_ID
. Nesse caso, a sugestão nunca é copiada em um atalho. Isso só é necessário se você não quiser que a sugestão copiada anteriormente apareça. Se você fornecer um valor normal para a coluna, o atalho de sugestão aparecerá somente até que a consulta de atualização retorne.Permita que o comportamento de atalho padrão seja aplicado.
Deixe
SUGGEST_COLUMN_SHORTCUT_ID
em branco para cada sugestão que não mudar e que possa ser salva como um atalho.
Se nenhuma de suas sugestões mudar, você não precisará da coluna SUGGEST_COLUMN_SHORTCUT_ID
.
Sobre a classificação de sugestões da caixa de pesquisa rápida
Depois de disponibilizar as sugestões de pesquisa do app para a caixa de pesquisa rápida, a classificação dela determina como as sugestões são exibidas ao usuário para uma consulta específica. Isso pode depender de quantos outros apps têm resultados para essa consulta e da frequência com que o usuário seleciona seus resultados em comparação com os de outros apps. Não há garantia sobre como as sugestões são classificadas ou se as sugestões do app são exibidas para uma determinada consulta. Em geral, fornecer resultados de qualidade aumenta a probabilidade de que as sugestões do app sejam fornecidas em uma posição de destaque, e os apps que fornecem sugestões de baixa qualidade têm mais chances de receber uma classificação mais baixa ou não serem exibidos.