Android开发者指南-添加最近请求建议项-Adding Recent Query Suggestions[原创译文]

Adding Recent Query Suggestions

版本：Android 4.0 r1

快速查看

·           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完整的实现示例：

publicclassMySuggestionProviderextendsSearchRecentSuggestionsProvider{ 

    publicfinalstaticString AUTHORITY ="com.example.MySuggestionProvider"; 

    publicfinalstaticint MODE = DATABASE_MODE_QUERIES; 

 

    publicMySuggestionProvider(){ 

        setupSuggestions(AUTHORITY, MODE); 

    } 

}

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

publicfinalstaticint MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

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

<application> 

    <providerandroid:name=".MySuggestionProvider" 

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

    ... 

</application>

 

修改搜索配置文件

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

<?xml version="1.0" encoding="utf-8"?> 

<searchablexmlns: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 

publicvoid 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 =newSearchRecentSuggestions(this, 

                MySuggestionProvider.AUTHORITY,MySuggestionProvider.MODE); 

        suggestions.saveRecentQuery(query,null); 

    } 

}

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

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

 

清除建议项数据

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

SearchRecentSuggestions suggestions =newSearchRecentSuggestions(this, 

        HelloSuggestionProvider.AUTHORITY,HelloSuggestionProvider.MODE); 

suggestions.clearHistory();

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