Question

增加最近查询的建议项

译者微博： http://weibo.com/popapa

版本：Android 4.0 r1

原文

http://developer.android.com/guide/topics/search/adding-recent-query-suggestions.html

快速查看

· Android 系统把搜索请求从搜索对话框或 widget 发送给执行搜索并显示结果的 activity

· 可以把搜索 widget 作为“action view”放入 Action Bar 中，用于快速访问

在本文中

简介

创建 Content Provider

修改搜索配置文件

保存搜索请求

清除建议项数据

关键类

SearchRecentSuggestions

SearchRecentSuggestionsProvider

参阅

搜索配置文件

使用 Android 的搜索对话框或者搜索 widget 时，可能需要根据最近的搜索请求提供搜索建议项。比如，假设用户以前搜索过“puppies”，那么一旦他开始键入同样的请求时，这就可以作为建议项显示出来。图 1 展示了带有最近求建议的搜索对话框。

图 1. 带有最近请求建议的搜索对话框截屏

在开始前，需要为应用程序基本的搜索功能实现搜索对话框或搜索 widget。如果没有，请参阅 创建搜索界面 。

简介

最近请求建议项只是简单地保存了搜索文本。当用户选中一个建议项时，搜索 activity 会收到一个 ACTION_SEARCH intent，其中附带了作为搜索请求的建议项，该请求以前已经由搜索 activity 处理过的（如 创建搜索界面 所述)。

要提供最近请求建议功能，需要：

· 实现一个搜索 activity，如 创建搜索界面 中所述。

· 创建一个继承自 SearchRecentSuggestionsProvider 的 content provider，并在 manifest 中进行声明。

· 修改搜索配置文件中有关提供搜索建议项的 content provider 配置。

· 每次执行搜索后把请求保存到 content provider 中。

Android 系统显示搜索对话框时，也就会把搜索建议项显示在对话框或搜索 widget 下面。所有需要做的事情就是提供数据源，系统能够从中获取建议项。

如果系统识别出 activity 是支持搜索功能并提供搜索建议的，则用户一旦开始键入搜索请求，就会触发以下动作：

1. 系统读取搜索请求文本（输入多少读取多少）并在存放建议项的 content provider 中进行检索。

2. content provider 返回一个 Cursor ，它指向匹配搜索文本的全部建议项。

3. 系统显示该 Cursor 提供的建议项列表。

一旦最近请求建议项显示完毕，将发生以下事情：

· 如果用户键入其它字符，或者以其它任何方式修改了请求文本，则上述步骤会重复执行，建议项列表将同步更新。

· 如果用户执行了搜索，建议项将被忽略，搜索文本将用正常的 ACTION_SEARCH intent 发送给搜索 activity。

· 如果用户选中了某个建议项， ACTION_SEARCH intent 将把建议项文本作为请求发送给搜索 activity。

作为 content provider 使用的 SearchRecentSuggestionsProvider 类会自动处理上述工作的，因此实际上只需要编写很少量的代码即可。

创建 Content Provider

最近请求建议项需要用到的 content provider 必须是 SearchRecentSuggestionsProvider 的实现。该类几乎处理了所有的事情，必需实现的只是编写一个包含一行代码的类构造方法。

以下是一个最近请求建议项所需的 content provider 完整的实现示例：

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);

}

}

setupSuggestions() 调用参数为搜索 authority 和数据库模式。搜索 authority 可以是任何唯一的字符串，但最好是用 content provider 的完全限定名称（包名加 provider 类名；比如“com.example.MySuggestionProvider”）。数据库模式必须包括 DATABASE_MODE_QUERIES ，可选项 DATABASE_MODE_2LINES 会在建议项列表中添加一列，使得每个建议项能提供两条文本。例如，要为每个建议项提供两行文本：

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

下面在 manifest 文件中声明 content provider，authority 串是与 SearchRecentSuggestionsProvider 类中（及搜索配置文件中）的相同：

<application>

<provider android:name=".MySuggestionProvider"

android:authorities="com.example.MySuggestionProvider" />

...

</application>

修改搜索配置文件

为了能够使用建议项 provider，需要对系统进行配置，在搜索配置文件的<searchable>元素中添加 android:searchSuggestAuthority 和 android:searchSuggestSelection 属性。例如：

<?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>

android:searchSuggestAuthority 的值必须是 content provider 的完全限定名称，它必须与 content provider 使用的 authority 完全一致（上例中是 AUTHORITY 字符串）。

android:searchSuggestSelection 的值必须是空格加问号（" ?"），这只是一个 SQLite 查询参数的占位符（将自动替换为用户录入的搜索请求文本）。

保存搜索请求

为了构建最近搜索请求的集合，需把搜索 activity 收到的所有请求都添加到 SearchRecentSuggestionsProvider 中去。要实现这一目标，请创建一个 SearchRecentSuggestions 的实例，每当搜索 activity 接受到请求时都调用一次 saveRecentQuery() 方法。下面是如何在 activity 的 onCreate() 方法中保存搜索请求的示例：

@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);

}

}

SearchRecentSuggestionsProvider 构造方法需要用到与 content provider 定义相同的 authority 和数据库模式。

saveRecentQuery() 方法的第一个参数是搜索关键字，第二个参数包含建议项的第二行文本（或为空）。第二个参数只有用 DATABASE_MODE_2LINES 启用两行模式（two-line mode）时才会用到。如果启用了两行模式（two-line mode），系统在检索建议项时，会同时把请求文本与第二行文本进行匹配。

清除建议项数据

为了保护用户隐私，应该确保向用户提供清除最近搜索建议项的功能。要清除搜索历史记录，调用 clearHistory() 即可。例如：

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,

HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);

suggestions.clearHistory();

可以选择在“清除搜索历史”菜单项、个人设置项或按钮中执行此操作。还应该提供确认对话框来验证用户真的是需要删除搜索历史记录。

补充

文章精选

Searchable 之 Recent Query Suggestions（上）

Searchable 之 Recent Query Suggestions（下）