Adicionar sugestões de pesquisa personalizadas

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

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:

  1. 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.
  2. Seu provedor de conteúdo retorna um Cursor que aponta para todas as sugestões relevantes para o texto da consulta de pesquisa.
  3. 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:

  1. 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/puppies
    

    O 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 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, remova a ambiguidade da origem da consulta de sugestão.

  2. projection
    Sempre nulo.
  3. 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 esse assunto em mais detalhes.
  4. 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 declarar android:searchSuggestSelection, esse parâmetro será nulo. A seção a seguir discute esse assunto em mais detalhes.
  5. 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 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 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 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 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 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 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 coluna SUGGEST_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 com getData() ou getDataString().

  • 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 coluna SUGGEST_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 de android:searchSuggestIntentData, anexa uma barra (/) e adiciona o respectivo valor da coluna SUGGEST_COLUMN_INTENT_DATA_ID para formar um URI de conteúdo completo. Depois, você pode recuperar o Uri com getData().

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 coluna SUGGEST_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 coluna SUGGEST_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 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 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 coluna SUGGEST_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.