Adicionar sugestões de pesquisa personalizadas

Você pode fornecer sugestões de pesquisa com base em consultas de pesquisa recentes na caixa de diálogo ou no widget de pesquisa do Android. Por exemplo, se um usuário consultar "filhotes", a consulta aparecerá como uma sugestão quando ele digitar a mesma consulta novamente. A Figura 1 mostra um exemplo de caixa de diálogo de pesquisa com sugestões de consulta recentes.

Antes de começar, implemente a caixa de diálogo ou o widget de pesquisa para fazer buscas básicas no app. Para saber como fazer isso, consulte Criar uma interface de pesquisa.

Noções básicas

Figura 1. Captura de tela de uma caixa de diálogo de pesquisa com sugestões de consulta recentes.

As sugestões de consulta recentes são pesquisas salvas. Quando o usuário seleciona uma sugestão, sua atividade de pesquisa recebe uma intent ACTION_SEARCH com a sugestão como a consulta de pesquisa que ela já processa.

Para fornecer sugestões de consultas recentes, você precisa:

  • Implemente uma atividade de pesquisa.
  • Crie um provedor de conteúdo que estenda SearchRecentSuggestionsProvider e o declare no manifesto do seu aplicativo.
  • Modificar a configuração pesquisável com informações sobre o provedor de conteúdo que fornece sugestões de pesquisa.
  • salvar consultas no seu provedor de conteúdo sempre que uma pesquisa é realizada.

Assim como o sistema Android exibe a caixa de diálogo de pesquisa, ele mostra as sugestões de pesquisa abaixo da caixa de diálogo ou do widget de pesquisa. Informe a fonte da qual o sistema recupera as sugestões.

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

  1. O sistema recebe o texto da consulta de pesquisa, ou seja, o que o usuário começa a digitar, e executa uma consulta ao provedor de conteúdo que contém suas sugestões.
  2. Seu provedor de conteúdo retorna um Cursor que aponta para todas as sugestões que correspondem ao texto da consulta de pesquisa.
  3. O sistema mostra a lista de sugestões fornecidas pelo Cursor.

Depois que as sugestões de consulta recentes são exibidas, pode ocorrer o seguinte:

  • Se o usuário digitar outra tecla 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 à atividade de pesquisa usando o intent ACTION_SEARCH normal.
  • Se o usuário selecionar uma sugestão, uma intent ACTION_SEARCH será entregue à sua atividade de pesquisa usando o texto sugerido como a consulta.

A classe SearchRecentSuggestionsProvider que você estende para seu provedor de conteúdo faz o trabalho automaticamente nas etapas anteriores. Portanto, há pouco código a ser programado.

Criar um provedor de conteúdo

O provedor de conteúdo necessário para sugestões de consulta recentes é uma implementação de SearchRecentSuggestionsProvider. Esta classe faz tudo por você. Você só precisa criar um construtor de classe que execute uma linha de código.

Por exemplo, veja uma implementação completa de um provedor de conteúdo para sugestões de consulta recentes:

Kotlin

class MySuggestionProvider : SearchRecentSuggestionsProvider() {
    init {
        setupSuggestions(AUTHORITY, MODE)
    }

    companion object {
        const val AUTHORITY = "com.example.MySuggestionProvider"
        const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
    }
}

Java

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
    public final static String AUTHORITY = "com.example.MySuggestionProvider";
    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {
        setupSuggestions(AUTHORITY, MODE);
    }
}

A chamada para setupSuggestions() transmite o nome da autoridade de pesquisa e um modo de banco de dados. A autoridade de pesquisa pode ser qualquer string exclusiva, mas a prática recomendada é usar um nome totalmente qualificado para seu provedor de conteúdo, como o nome do pacote seguido pelo nome da classe do provedor. Por exemplo: "com.example.MySuggestionProvider".

O modo de banco de dados precisa incluir DATABASE_MODE_QUERIES e pode incluir DATABASE_MODE_2LINES, que adiciona uma coluna à tabela de sugestões para que você possa fornecer uma segunda linha de texto a cada sugestão. Se você quiser fornecer duas linhas em cada sugestão, veja o exemplo a seguir:

Kotlin

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

Java

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

Declare o provedor de conteúdo no manifesto do aplicativo com a mesma string de autoridade usada na classe SearchRecentSuggestionsProvider e na configuração pesquisável. Por exemplo:

<application>
    <provider android:name=".MySuggestionProvider"
              android:authorities="com.example.MySuggestionProvider" />
    ...
</application>

Modificar a configuração pesquisável

Para configurar o sistema para usar seu provedor de sugestões, adicione os atributos android:searchSuggestAuthority e android:searchSuggestSelection ao elemento <searchable> no seu arquivo de configuração pesquisável. Por exemplo:

<?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.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

O valor de android:searchSuggestAuthority precisa ser um nome totalmente qualificado para seu provedor de conteúdo que corresponda exatamente à autoridade usada no provedor de conteúdo, como "com.example.MySuggestionProvider" nos exemplos anteriores.

O valor de android:searchSuggestSelection precisa ser um único ponto de interrogação precedido por um espaço: " ?". Esse é um marcador de posição para o argumento de seleção do SQLite e é substituído automaticamente pelo texto de consulta inserido pelo usuário.

Salvar consultas

Para preencher sua coleção de consultas recentes, adicione cada consulta recebida pela atividade de pesquisa ao SearchRecentSuggestionsProvider. Para fazer isso, crie uma instância de SearchRecentSuggestions e chame saveRecentQuery() sempre que sua atividade de pesquisa receber uma consulta. Por exemplo, veja como salvar a consulta durante o método onCreate() da sua atividade:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                    .saveRecentQuery(query, null)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent  = getIntent();

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
        suggestions.saveRecentQuery(query, null);
    }
}

O construtor SearchRecentSuggestionsProvider requer a mesma autoridade e modo de banco de dados declarados pelo provedor de conteúdo.

O método saveRecentQuery() usa a string de consulta de pesquisa como o primeiro parâmetro e, opcionalmente, uma segunda string a ser incluída como a segunda linha da sugestão ou nula. O segundo parâmetro será usado apenas se você ativar o modo de duas linhas para as sugestões de pesquisa com DATABASE_MODE_2LINES. Se você ativar o modo de duas linhas, o texto da consulta vai corresponder à segunda linha quando o sistema procurar sugestões correspondentes.

Limpar os dados de sugestão

Para proteger a privacidade do usuário, sempre ofereça uma maneira de limpar as sugestões de consulta recentes. Para limpar o histórico de consultas, chame clearHistory(). Por exemplo:

Kotlin

SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
        .clearHistory()

Java

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
        HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
suggestions.clearHistory();

Execute-o de sua escolha entre um item de menu, um item de preferência ou um botão "Limpar histórico de pesquisa". Forneça uma caixa de diálogo de confirmação para verificar se o usuário quer excluir o histórico de pesquisa.