Esta página foi traduzida pela API Cloud Translation.

Adicionar sugestões de pesquisa personalizadas

Ao usar a caixa ou o widget de pesquisa do Android, você pode fornecer sugestões personalizadas criadas com base nos dados do app. Por exemplo, se o app for um dicionário, você pode sugerir palavras que correspondam ao texto inserido no campo de pesquisa antes que o usuário termine de digitar a consulta. Essas sugestões são valiosas porque podem prever com eficiência o que o usuário quer e fornecer acesso instantâneo a isso. A Figura 1 mostra um exemplo de uma caixa 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, oferecendo acesso ao seu conteúdo a partir de áreas fora do app.

Antes de adicionar sugestões personalizadas, implemente a caixa de diálogo de pesquisa do Android ou um widget de pesquisa para pesquisas no seu app. Consulte Criar uma interface de pesquisa e Provedores de conteúdo.

Noções básicas

Figura 1. Captura de tela de uma caixa de pesquisa com sugestões de pesquisa personalizadas.

Quando o usuário seleciona uma sugestão personalizada, o sistema envia um Intent à sua atividade de pesquisa. Ao contrário de uma consulta de pesquisa normal que envia um 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 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 da palavra, em vez de pesquisar correspondências no dicionário.

Para fornecer sugestões personalizadas, siga estas etapas:

Implemente uma atividade de pesquisa básica, conforme descrito em Criar uma interface de pesquisa.
Modifique a configuração pesquisável com informações sobre o provedor de conteúdo que oferece sugestões personalizadas.
Crie uma tabela, como em um SQLiteDatabase, para suas sugestões e formate-a com as colunas obrigatórias.
Crie um provedor de conteúdo com acesso à sua tabela de sugestões e declare-o no manifesto.
Declare o tipo de Intent a ser enviado quando o usuário selecionar uma sugestão, incluindo uma ação personalizada e dados personalizados.

Além de exibir a caixa de pesquisa, o Android também mostra suas sugestões de pesquisa. Você precisa de um provedor de conteúdo de onde o sistema possa recuperar suas sugestões. Leia Provedores de conteúdo para saber como criar um.

Quando o sistema identifica que sua atividade é pesquisável e fornece sugestões de pesquisa, o procedimento a seguir ocorre quando o usuário digita uma consulta:

O sistema usa o texto da consulta (digitado até então) para consultar o provedor de conteúdo que processa 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 exibe 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 digitar outra letra ou mudar a consulta de alguma forma, as etapas anteriores serão repetidas, e a lista de sugestões será atualizada.
Se o usuário executar a pesquisa, as sugestões serão ignoradas, e a pesquisa será entregue à sua atividade de pesquisa usando o intent ACTION_SEARCH normal.
Se o usuário selecionar uma sugestão, um intent será enviado à sua atividade de pesquisa, com uma ação personalizada e dados personalizados, para que o app possa abrir o conteúdo sugerido.

Modificar a configuração pesquisável

Para adicionar compatibilidade com 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>

Você pode precisar de outros atributos, dependendo do tipo de intent que você anexa a cada sugestão e de como pretende 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. Um provedor de conteúdo para sugestões personalizadas é semelhante a qualquer outro provedor de conteúdo. No entanto, para cada sugestão oferecida, a respectiva linha no Cursor precisa incluir colunas específicas que o sistema entenda e use para formatar as sugestões.

Quando o usuário digita um texto na caixa ou no widget de pesquisa, o sistema consulta seu provedor de conteúdo para buscar sugestões chamando query() cada vez que uma letra é digitada. Na implementação de query(), seu provedor de conteúdo precisa pesquisar os dados de sugestão e retornar um Cursor que aponte para as linhas que ele determina serem boas sugestões.

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ões: Como o sistema envia solicitações para seu provedor de conteúdo e como processá-las.
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ões

Quando o sistema solicita sugestões do seu provedor de conteúdo, ele chama o método query() do provedor de conteúdo. Implemente esse método para pesquisar seus dados de sugestão e retornar um Cursor que aponte para as sugestões consideradas relevantes.

Este é um resumo dos parâmetros que o sistema transmite para o método query(), listados em ordem:

uri: Sempre um Uri de conteúdo, formatado da seguinte maneira:
content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

O comportamento padrão é o sistema transmitir esse URI e anexar o texto da consulta a ele:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

O texto da consulta no final é codificado usando regras de codificação de URI. Por isso, talvez seja necessário decodificá-lo antes de realizar uma pesquisa.

A parte optional.suggest.path só será incluída no URI se esse caminho tiver sido definido no arquivo de configuração pesquisável com o atributo android: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, diferencie a origem da consulta de sugestão.

Observação:SUGGEST_URI_PATH_QUERY não é a string literal fornecida no URI, mas uma constante. Use-o se precisar consultar esse caminho.
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 atributo android:searchSuggestSelection. A seção a seguir discute isso 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 configuração pesquisável. Se você não declarar android:searchSuggestSelection, esse parâmetro será nulo. A seção a seguir discute isso com 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 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(), conforme 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 inserido pelo usuário.

Conseguir a consulta nos argumentos de seleção

Em vez de usar o URI, pode ser mais adequado que seu método query() receba tudo o que precisa para realizar a pesquisa, e talvez você queira que os parâmetros selection e selectionArgs carreguem os valores adequados. Nesse caso, adicione o atributo android:searchSuggestSelection à sua configuração pesquisável com sua string de seleção SQLite. Na string de seleção, inclua um ponto de interrogação (?) como marcador para a consulta de pesquisa. 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 você pode 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, seu método query() entrega o parâmetro selection como "word MATCH ?" e o parâmetro selectionArgs como a consulta de pesquisa. Quando esses parâmetros são transmitidos para um método query() do SQLite como argumentos respectivos, eles são sintetizados juntos. Isso significa que o ponto de interrogação é substituído pelo texto da consulta. Se você receber consultas de sugestão dessa maneira e precisar adicionar caracteres curingas ao texto da consulta, anexe-os ou use-os como prefixo 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 de intent enviada com cada intent quando o usuário seleciona uma sugestão. Isso é discutido mais adiante na seção Declarar um intent para sugestões.

Dica:se você não quiser definir uma cláusula de seleção no atributo android:searchSuggestSelection, mas ainda quiser receber o texto da consulta no parâmetro selectionArgs, forneça um valor não nulo para o atributo android:searchSuggestSelection. Isso aciona a consulta a ser transmitida em selectionArgs, e você pode ignorar o parâmetro selection. Dessa forma, você pode definir a cláusula de seleção real em um nível inferior para que o provedor de conteúdo não precise processá-la.

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 seus dados de sugestão em um banco de dados SQLite no dispositivo, um banco de dados em um servidor da Web ou outro formato no dispositivo ou na Web, formate as sugestões como linhas em uma tabela e apresente-as com um Cursor.

Observação:se suas sugestões de pesquisa não estiverem armazenadas em um formato de tabela, como uma tabela SQLite, usando as colunas exigidas pelo sistema, pesquise os dados de sugestões para buscar correspondências e formate-as na tabela necessária para cada solicitação. Para fazer isso, crie um MatrixCursor usando os nomes de coluna obrigatórios e adicione uma linha para cada sugestão usando addRow(Object[]). Retorne o produto final do método query() do seu provedor de conteúdo.

O sistema entende várias colunas, mas só duas são obrigatórias:

_ID: Um ID único de linha de números inteiros para cada sugestão. O sistema exige isso para apresentar sugestões em uma ListView.
SUGGEST_COLUMN_TEXT_1: A string que é apresentada como uma sugestão.

As colunas a seguir são opcionais. A maioria é discutida em mais detalhes nas seções a seguir.

SUGGEST_COLUMN_TEXT_2: Uma string. Se o 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 ao lado esquerdo. Ela pode ser nula 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. Ela pode ser nula 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 usando android: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 o 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 fornecida, o campo de dados do 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 usando android: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 no intent. Use isso apenas se o campo de dados especificado pelo atributo android:searchSuggestIntentData na configuração pesquisável já estiver definido como uma string 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 do intent será nulo. Essa coluna permite que as sugestões forneçam dados complementares incluídos como um extra na chave EXTRA_DATA_KEY do 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 do intent. É obrigatório se a ação da sugestão for ACTION_SEARCH, mas opcional caso contrário.
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 ela 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 faltando, o resultado será armazenado como um atalho e nunca será atualizado. Se definida como SUGGEST_NEVER_MAKE_SHORTCUT, o resultado não será armazenado como um atalho. Caso contrário, o ID do atalho será usado para verificar se há uma sugestão atualizada usando SUGGEST_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 será exibido, em vez de um ícone de SUGGEST_COLUMN_ICON_2, enquanto o atalho dessa sugestão estiver sendo atualizado na Caixa de pesquisa rápida.

A maioria dessas colunas é discutida em mais detalhes nas seções a seguir.

Declarar um intent de sugestões

Quando o usuário seleciona uma sugestão na lista que aparece abaixo da caixa ou do widget de pesquisa, o sistema envia um Intent personalizado à sua atividade de pesquisa. É necessário definir a ação e os dados para o intent.

Declarar a ação de 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, as informações de contato de uma pessoa ou uma página da Web. No entanto, a ação de intent pode ser qualquer outra ação e pode ser diferente para cada sugestão.

Dependendo se você quer ou não 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 isso, adicione a coluna SUGGEST_COLUMN_INTENT_ACTION à tabela de sugestões e, em cada sugestão, coloque a ação a ser usada, como "android.intent.action.VIEW".

Você também pode combinar essas duas técnicas. Por exemplo, é possível incluir o atributo android:searchSuggestIntentAction com uma ação a ser usada com todas as sugestões por padrão e, em seguida, substituir essa ação por 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, será usado o intent fornecido no atributo android:searchSuggestIntentAction.

Observação:se você não incluir o atributo android:searchSuggestIntentAction na sua configuração pesquisável, será necessário incluir um valor na coluna SUGGEST_COLUMN_INTENT_ACTION para cada sugestão; caso contrário, o intent vai falhar.

Declarar dados de intent

Quando o usuário seleciona uma sugestão, sua atividade de pesquisa recebe o intent com a ação definida, conforme discutido na seção anterior. No entanto, o intent também precisa transportar dados para que sua atividade identifique qual sugestão foi selecionada. Especificamente, os dados precisam ser algo exclusivo para cada sugestão, como o ID da linha da sugestão na tabela SQLite. Quando o intent for recebido, você poderá 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 conforme definido nessa coluna. É possível recuperar com getData() ou getDataString().

Dica: geralmente é mais fácil usar o ID da linha da tabela como os dados do intent, porque ele é sempre exclusivo. A maneira mais fácil de fazer isso é usando o nome da coluna SUGGEST_COLUMN_INTENT_DATA como um alias para a coluna de IDs de linhas.
Fragmente um URI de dados em duas partes: a parte comum a todas as sugestões e a parte exclusiva de cada sugestão. Coloque essas partes no atributo android:searchSuggestintentData da configuração pesquisável e na coluna SUGGEST_COLUMN_INTENT_DATA_ID da sua 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 exclusiva) na coluna SUGGEST_COLUMN_INTENT_DATA_ID da tabela de sugestões. Quando o usuário seleciona uma sugestão, o sistema pega a string de android:searchSuggestIntentData, anexa uma barra (/) e adiciona o valor correspondente da coluna SUGGEST_COLUMN_INTENT_DATA_ID para formar um URI de conteúdo completo. Então, você pode recuperar o Uri com getData().

Adicionar mais dados

Se você precisar expressar mais informações com seu intent, adicione outra coluna da tabela, como SUGGEST_COLUMN_INTENT_EXTRA_DATA, que pode armazenar informações complementares sobre a sugestão. Os dados salvos nessa coluna são colocados em EXTRA_DATA_KEY do pacote extra do intent.

Processar a intent

Depois de fornecer sugestões de pesquisa personalizadas com intents personalizados, você precisa que sua atividade de pesquisa processe esses intents quando o usuário selecionar uma sugestão. É necessário também processar o intent ACTION_SEARCH, o que já é feito pela atividade de pesquisa. Confira um exemplo de como processar os intents durante o callback onCreate() da sua 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);
}

Neste exemplo, a ação de intent é ACTION_VIEW, e os dados transportam um URI completo que aponta para o item sugerido, como sintetizado pela string android:searchSuggestIntentData e coluna SUGGEST_COLUMN_INTENT_DATA_ID. O URI é então transferido para o método local showResult(), que consulta o provedor de conteúdo para buscar o item especificado pelo URI.

Observação:não é necessário adicionar um filtro de intent ao arquivo de manifesto do Android para a ação de intent definida com o atributo android:searchSuggestIntentAction ou a coluna SUGGEST_COLUMN_INTENT_ACTION. O sistema abre sua atividade de pesquisa por nome para exibir o intent da sugestão. Portanto, a atividade não precisa declarar a ação aceita.

Reescrever o texto da consulta

Por padrão, se o usuário navegar pela lista de sugestões usando controles direcionais, como um trackball ou botão direcional, o texto da consulta não será atualizado. No entanto, é possível reescrever temporariamente o texto de consulta do usuário conforme ele aparece na caixa de texto com uma consulta que corresponde à sugestão em foco. Isso permite que o usuário veja a consulta sugerida, selecione a caixa de pesquisa e edite a consulta 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 coluna SUGGEST_COLUMN_TEXT_1 da sugestão é usado para reescrever o texto da consulta.
Adicione o atributo android:searchMode à sua configuração pesquisável com o valor "queryRewriteFromData". Nesse caso, o conteúdo da coluna SUGGEST_COLUMN_INTENT_DATA da sugestão é usado para reescrever o texto da consulta. Use somente com URIs ou outros formatos de dados que sejam visíveis ao usuário, como URLs HTTP. Não use esquemas URI internos para reescrever a consulta dessa maneira.
Forneça uma string de texto de consulta única 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 para a caixa de pesquisa rápida

Depois de configurar seu app para fornecer 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 mais trabalhoso é 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 a seguir:

<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> corrige 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, por padrão, a caixa de pesquisa rápida tem permissão de leitura.

Ativar sugestões em um dispositivo

Por padrão, os apps não estão ativados para fornecer sugestões na caixa de pesquisa rápida, mesmo que estejam configurados para isso. O usuário escolhe se quer incluir sugestões do seu app na caixa de pesquisa rápida. Para isso, ele abre Itens pesquisáveis, localizado em Configurações > Pesquisa, e ativa 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 da descrição do seu 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>

Faça com que a string de android:searchSettingsDescription seja o mais concisa possível e indique 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. Fornecer essa descrição é importante 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 do seu app, se a pesquisa for um aspecto importante, considere como transmitir isso aos usuários. Por exemplo, você pode exibir uma observação na primeira vez que um usuário inicia 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

Sugestões que o usuário seleciona na caixa de pesquisa rápida podem ser transformadas automaticamente em atalhos. Essas são as sugestões que o sistema copia do seu provedor de conteúdo para poder acessar rapidamente a sugestão sem precisar consultar novamente o provedor de conteúdo.

Por padrão, isso é ativado para todas as sugestões recuperadas pela caixa de pesquisa rápida, mas se os dados de sugestões forem alterados com o tempo, você poderá solicitar que os atalhos sejam atualizados. Por exemplo, se suas sugestões se referem a dados dinâmicos, como o status de presença de um contato, solicite que os atalhos de sugestão sejam atualizados quando exibidos ao usuário. Para isso, inclua o SUGGEST_COLUMN_SHORTCUT_ID na tabela de sugestões. É possível usar essa coluna para configurar o comportamento de atalho para cada sugestão, de uma das seguintes maneiras:

Peça à Caixa de pesquisa rápida que consulte novamente seu 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 buscar 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 para seu provedor de conteúdo com um caminho de URI de SUGGEST_URI_PATH_SHORTCUT, em vez de SUGGEST_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 com base na rede, também é possível adicionar a coluna SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING à tabela de sugestões com o valor "true" para mostrar um ícone de carregamento de progresso do ícone do lado direito até que a atualização seja concluída. Qualquer valor diferente de "true" não mostra o ícone de carregamento de progresso.
Impeça que a sugestão seja copiada em um atalho.

Forneça um valor de SUGGEST_NEVER_MAKE_SHORTCUT na coluna SUGGEST_COLUMN_SHORTCUT_ID. Nesse caso, a sugestão nunca é copiada em um atalho. Isso só será necessário se você realmente 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 muda e que pode ser salva como um atalho.

Se nenhuma das duas 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 da caixa de pesquisa rápida 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 com que frequência o usuário seleciona seus resultados em comparação com os de outros apps. Não existe nenhuma garantia sobre a forma como suas sugestões serão classificadas ou se as sugestões do seu app serão exibidas para uma determinada consulta. Em geral, fornecer resultados de qualidade aumenta a probabilidade de que as sugestões do seu app sejam fornecidas em uma posição de destaque. Apps que fornecem sugestões de baixa qualidade são mais propensos a ter uma classificação inferior ou a não exibi-la.

Adicionar sugestões de pesquisa personalizadas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Noções básicas

Modificar a configuração pesquisável

Criar um provedor de conteúdo

Processar a consulta de sugestões

Conseguir a consulta no URI

Kotlin

Java

Conseguir a consulta nos argumentos de seleção

Criar uma tabela de sugestões

Declarar um intent de sugestões

Declarar a ação de intent

Declarar dados de intent

Adicionar mais dados

Processar a intent

Kotlin

Java

Reescrever o texto da consulta

Expor sugestões de pesquisa para a caixa de pesquisa rápida

Ativar sugestões em um dispositivo

Gerenciar atalhos de sugestões da caixa de pesquisa rápida

Sobre a classificação de sugestões da caixa de pesquisa rápida

Adicionar sugestões de pesquisa personalizadas