Question

添加自定义建议项

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

版本：Android 4.0 r1

原文

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

在本文中

简介

修改搜索配置文件

创建 Content Provider

处理建议项请求

建立建议项数据表

声明建议项所需的 Intent

声明 intent 的 action

声明 intent 的 data

处理 Intent

改写查询请求文本

向快速搜索框提供搜索建议项

关键类

SearchManager

SearchRecentSuggestionsProvider

ContentProvider

相关示例

支持检索的字典

参阅

搜索配置文件

Content Providers

利用 Android 的搜索对话框或搜索 widget，可以提供自定义搜索建议项，它的数据来源于应用程序自身。比如，假设应用程序是一个字典应用，可以把字典中最匹配已录入文本的单词作为建议项。由于能有效预测用户所查文本并能让用户直接获得字典中的释义，这种建议项是最有价值的。图 1 展示了使用自定义建议项的搜索对话框示例：

图 1. 使用自定义对话框的搜索对话框截屏

一旦提供了自定义建议项，就可以同时让它应用于系统级的“快速搜索框”，从应用程序之外访问搜索内容。

在添加自定义建议项之前，需要先在应用程序中实现一个 Android 搜索对话框或搜索 widget。如果还没有的话，请参阅 创建搜索界面 。

简介

如果用户选中了某个自定义建议项，Android 系统将向搜索 activity 发送一个 Intent 。标准的搜索请求将会发送一个附带 ACTION_SEARCH action 的 intent，不过仍可让自定义建议项使用 ACTION_VIEW （或者任何其它 action），并放入相应的选中建议项数据。接着上面的字典应用示例，用户选中一个建议项时，应用程序可以立即显示单词的释义，而不是去字典检索匹配项。

为了提供自定义建议项功能，请按以下步骤操作：

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

· 修改搜索配置文件中有关 content provider 的信息，用于提供自定义建议项的数据。

· 建立存放建议项的数据表（比如在 SQLiteDatabase 库中），根据所需数据列定义表结构。

· 创建访问建议项数据表的 Content Provider ，并在 manifest 文件中声明 provider。

· 声明 Intent 的类型，用户选中某个建议项时可用于发送数据（包括自定义 action 和自定义数据）。

当搜索对话框显示出来时，Android 系统同时也会显示搜索建议项。需要提供的只是系统能从中读取建议项的 content provider。如果对创建 content provider 还不很熟悉，请先阅读 Content Providers 开发者指南再往下继续吧。

一旦系统识别出 activity 支持搜索功能且已提供搜索建议项，用户键入搜索请求时会执行以下步骤：

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

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

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

显示完毕，将发生以下事情：

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

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

· 如果用户选中了某个建议项，带有自定义 action 和自定义数据的 intent 将会发送给搜索 activity，应用程序可以打开建议项内容。

修改搜索配置文件

要加入对自定义建议项的支持，请在搜索配置文件的<searchable>元素中添加 android:searchSuggestAuthority 属性。例如：

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

根据建议项相关的 intent 类型，以及如何组织提交给 content provider 的请求文本，可能还需要用到其它一些属性。其它可选的属性将在后续章节中讨论。

创建 Content Provider

要为自定义建议项创建 content provider，需要具备 content provider 的相关知识，这在 Content Provider 开发者指南中描述。自定义建议项所需的 content provider 绝大部分都与其它 content provider 相同。不过， Cursor 中对应每个建议项的数据行都必须包含系统可解析的数据列，用于组织建议项数据。

用户开始在搜索对话框或搜索 widget 里输入文本时，每键入一个字符，系统都将调用一次 query() ，并在 content provider 中检索建议项。在 query() 中，必须实现对 content provider 建议项数据的检索，并返回一个指向最佳建议项数据行的 Cursor 。

关于为自定义建议项创建 content provider 的详情，将在以下章节讨论：

处理建议项请求

系统如何向 content provider 发送请求及如何处理。

建立建议项数据表

如何定义数据列，系统用于在每次搜索时返回 Cursor 。

处理建议项请求

当系统向 content provider 发送建议项检索请求时，将会调用 content provider 的 query() 方法。必须在该方法中实现搜索建议项数据并返回指向最匹配建议项的 Cursor 。

以下是系统传给 query() 方法的所有参数（按照调用顺序排列）：

uri

通常是 content Uri ，格式如下：

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

系统的默认行为是传递 URI 并后跟搜索请求文本。例如：

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

末尾的请求文本是用 URI 编码规则编码过的，因此可能要在执行搜索前进行解码。

仅当搜索配置文件中用 android:searchSuggestPath 属性设置了路径时，URI 中才要包含 optional.suggest.path 部分。只有多个搜索 activity 需共用同一个 content provider 时，才需要用到该配置。在这种情况下，需要解析建议项请求的来源。

注意：SUGGEST_URI_PATH_QUERY 并不属于 URI 的一部分，而应是用于指向此路径的常量。

projection

总为 null

selection

该值由搜索配置文件中的 android:searchSuggestSelection 属性提供，如果未声明 android:searchSuggestSelection 属性则为 null。更多使用信息请参见下文 读取请求 。

selectionArgs

如果已在搜索配置文件中声明了 android:searchSuggestSelection 属性，那么数组的第一个（也只有一个）元素包含了搜索请求。如果未声明 android:searchSuggestSelection，则本参数将为 null。更多使用信息请参见下文 读取请求 。

sortOrder

总为 null。

系统可以用两种方式发送搜索请求文本。默认的方式是作为 content URI 路径的末尾部分（last segment）在 uri 参数中传递。不过，假如在搜索配置文件的 android:searchSuggestSelection 属性中包含了选项值，那么请求文本将作为字符串数组 selectionArgs 的第一个元素传递。这两种方式将在下文中一起讨论。

读取 Uri 中的搜索请求

默认情况下，请求文本是附加在 uri 参数（ Uri 对象）的末尾的。这时只要简单地用 getLastPathSegment() 即可读取请求文本了。例如：

String query = uri.getLastPathSegment().toLowerCase();

这将返回 Uri 的末尾部分（last segment），也就是用户录入的请求文本。

读取 selection 参数中的搜索请求

与 URI 不同，还可以采用更智能的方式， query() 方法能够接收执行搜索所需的任何信息，selection 和 selectionArgs 属性也能够传递合适的值。这种情况下，只要把 SQLite 查询语句作为 android:searchSuggestSelection 属性加入到搜索配置文件中去即可。在查询语句中，问号用作占位符，代表实际的查询请求。系统将用该查询语句作为 selection 参数，搜索请求作为 selectionArgs 数组的第一个元素，对 query() 进行调用。

以下是如何定义 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.MyCustomSuggestionProvider"

android:searchSuggestIntentAction="android.intent.action.VIEW"

android:searchSuggestSelection = "word MATCH ?" >

</searchable>

通过以上配置， query() 方法会把 selection 参数赋为"word MATCH ?" ，selectionArgs 参数赋为搜索请求。当这些信息作为参数传给 SQLite query() 方法时，会被组合在一起（问号由搜索请求文本代替）。如果选择以这种方式接收建议项请求并需要在请求文本中加入通配符，可以在 selectionArgs 参数的后面（或前面）加入即可，因为该值将用引号包裹并整体插入到问号所在位置。

以上例子中新出现的属性是 android:searchSuggestIntentAction，用于定义用户每次选中建议项时所发送 intent 的 action。这将在后续章节 为建议项声明 Intent 讨论。

提示： 如果不需要在 android:searchSuggestSelection 属性中定义查询语句，但还要在 selectionArgs 参数中接收请求文本，则只要简单地把 android:searchSuggestSelection 属性赋成非空值即可。这将导致请求文本传递给 selectionArgs，并且 selection 参数可被忽略。这样就可以不用定义实际的底层查询语句，content provider 也不必再对其进行处理。

建立建议项数据表

创建脱离数据库表的 Cursor

如果搜索建议项不是按照系统要求的数据列存储在数据库表中的（比如 SQLite 表），那可以在每次发起请求时检索匹配的建议项数据并把它们格式化后保存到必要的表中。要实现这一目标，用系统要求的列名创建一个 MatrixCursor ，并用 addRow(Object[]) 为每个建议项创建一行数据。Content Provider 的 query() 方法将返回最终结果。

用 Cursor 向系统返回建议项时，每一行数据的列格式都是系统规定的。因此，无论是要把建议项数据存储在本地或 Web 服务器的 SQLite 数据库中，还是要以本地或 web 的其它格式存储，都必须把建议项格式化为表的一行数据，并用 Cursor 来表示。系统可以识别多个列，但有两列是必需的：

ID

整数类型的行 ID，唯一标识建议项。在 ListView 中显示建议项时，系统会用到该值。

SUGGEST_COLUMN_TEXT_1

代表建议项的字符串。

以下各列是可选的（大部分都会在后续章节中讨论）：

SUGGEST_COLUMN_TEXT_2

字符串。如果 Cursor 包含该列，那么所有的建议项都提供两行模式。本列中的字符串将会显示为第二行，它的字体较小并显示主建议项文本的下方。也可以为 null 或空串，表示没有第二行文本。

SUGGEST_COLUMN_ICON_1

drawable 资源、content 或文件 URI 串。如果 Cursor 包含该列，那么所有建议项都提供图标加文字模式，图标居左显示。该项可以为 null 或 0，表示本行没有图标。

SUGGEST_COLUMN_ICON_2

drawable 资源、content 或文件 URI 串。如果 Cursor 包含该列，那么所有建议项都提供图标加文本模式，图标居右显示。该项可以为 null 或 0，表示本行没有图标。

SUGGEST_COLUMN_INTENT_ACTION

intent action 字符串。如果给定行中存在本列并且有值，那么此处定义的 action 将用于格式化建议项的 intent。如果未提供本值，则会采用搜索配置文件中的 android:searchSuggestIntentAction 部分。如果所有建议项的 action 都是相同的，则更有效的方式是用 android:searchSuggestIntentAction 指定 action 并省略本列。

SUGGEST_COLUMN_INTENT_DATA

数据 URI 字符串。如果给定行中存在本列并且有值，那么此值在格式化建议项时将作为 intent 的 data 部分来使用。如果未提供本值，则会采用搜索配置文件中的 android:searchSuggestIntentData 部分。如果前面两处都未提供值，则 intent 的 data 部分将为 null。如果所有建议项的数据都是相同的，或者能用固定部分+ID 来描述的，那么更有效的的方式是用 android:searchSuggestIntentData 指定，并省略本列。

SUGGEST_COLUMN_INTENT_DATA_ID

URI 路径字符串。如果给定行中存在本列并且有值，那么“/”加上本值将会添加到 intent 的 data 之后。仅当搜索配置文件中的 android:searchSuggestIntentData 属性已经设置了适当的基础数据字符串时，本项才会用到。

SUGGEST_COLUMN_INTENT_EXTRA_DATA

任何数据。如果给定行中存在本列并且有值，则表示格式化建议项 intent 时需要用到的 extra data。如果未提供本值，则 intent 的 extra data 部分为 null。本列允许建议项附带额外的数据，包含于 intent 的 EXTRA_DATA_KEY 键内。

SUGGEST_COLUMN_QUERY

如果给定行中存在本列并且有值，则为格式化建议项请求时需要用到的数据，包含于 intent 的 QUERY 键内。当建议项的 action 是 ACTION_SEARCH 时需要用到本值，否则则是可选列。

SUGGEST_COLUMN_SHORTCUT_ID

仅当向“快速搜索框”提供建议项时才会用到。本列标明了搜索建议项是否要存储为快捷方式，以及是否需要验证有效性。快捷方式一般是在用户从“快速搜索框”中点击建议项时生成。如果本 ID 缺失的话，结果将会存储为快捷方式且不再会更新。如果设置为 SUGGEST_NEVER_MAKE_SHORTCUT ，结果将不会存储为快捷方式。否则，快捷方式的 ID 将用于检查并更新建议项，这时还会用到 SUGGEST_URI_PATH_SHORTCUT .。

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

仅用于向“快速搜索框”提供建议项。本列指明当“快速搜索框”内建议项的快捷方式更新后，是否用进度滚轮（spinner）替代 SUGGEST_COLUMN_ICON_2 所设的图标。

以上各列中的一部分将会在后续章节中继续讨论。

声明建议项所需的 Intent

当用户在搜索对话框或 widget 下方的列表内选中某个建议项时，系统会向搜索 activity 发送一个自定义的 Intent 。intent 必须定义好 action 和 data 部分。

声明 intent 的 action

自定义建议项最常用的 intent action 是 ACTION_VIEW ，适用于要启动某些应用的场合，类似单词的释义、联系人信息、网页等。当然，intent action 也可以是其它任何 action，甚至每个建议项的 action 都可以不同。

根据全部建议项是否共用同一种 intent action，可以用以下两种方式来定义 action：

a. 利用搜索配置文件的 android:searchSuggestIntentAction 属性来定义所有建议项的 action。

例如：

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

b. 利用 SUGGEST_COLUMN_INTENT_ACTION 列来定义单个建议项的 action。

在建议项表中添加 SUGGEST_COLUMN_INTENT_ACTION 列，并把每个建议项所用到的 action 放入其中（类似"android.Intent.action.VIEW"）。

也可以混合使用以上两种方式。比如，可以包含 android:searchSuggestIntentAction 属性，为所有建议项提供默认 action。然后在某些建议项的 SUGGEST_COLUMN_INTENT_ACTION 列中声明另一个 action，以覆盖默认 action。如果 SUGGEST_COLUMN_INTENT_ACTION 列中未包含值，将会采用 android:searchSuggestIntentAction 属性提供的 intent。

注意： 如果搜索配置文件中未包含 android:searchSuggestIntentAction 属性，则 必须 为每个建议项的 SUGGEST_COLUMN_INTENT_ACTION 列指定值，否则，intent 将会启动失败。

声明 intent 的 data

当用户选中一个建议项时，搜索 activity 将会接收到附带指定 action（如上节所述）的 intent，但该 intent 还必须同时携带 data 才行，这样搜索 activity 才能识别出选中的建议项。有一点尤为重要，data 应该是能唯一标识每个建议项的信息，比如 SQLite 表中的行 ID。在收到 intent 时，可以利用 getData() 或 getDataString() .来读取附带的 data。

可以用以下两种方式来定义 intent 中的 data：

a. 在建议项表的 SUGGEST_COLUMN_INTENT_DATA 列中为每个建议项都定义一个 data。

在建议项表中包含 SUGGEST_COLUMN_INTENT_DATA 列，以便为每个 intent 都提供必要的 data 信息，然后把每行的唯一信息填入。该列中的值将会原封不动地附加到 intent 中。可以利用 getData() 或 getDataString() 来读取它们。

提示： 通常表的行 ID 最容易被用作 Intent data，因为它总是唯一的。最简便的方式就是用 SUGGEST_COLUMN_INTENT_DATA 列名作为行 ID 的别名。具体示例请参阅 支持检索的字典例程 ，其中 SQLiteQueryBuilder 创建了一个列名和别名的映射关系。

b. 把 data URI 分解为两部分：所有建议项公共的部分和每个建议项唯一的部分。把这两部分分别放入搜索配置文件的 android:searchSuggestintentData 属性和建议项表的 SUGGEST_COLUMN_INTENT_DATA_ID 列中。

在搜索配置文件的 android:searchSuggestIntentData 属性中声明全部建议项公共的 URI 部分。例如：

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

然后在建议项表中的 SUGGEST_COLUMN_INTENT_DATA_ID 列中放入每个建议项的 final path（唯一部分）。用户选中建议项后，系统会把 android:searchSuggestIntentData 中指定的字符串加上斜杠 ("/")，再加入各自 SUGGEST_COLUMN_INTENT_DATA_ID 列中的值，组成一个完整的 content URI。然后就可以用 getData() 读取 Uri 了。

附加更多的数据

如果需要在 intent 中表示更多信息，可以添加另一列 SUGGEST_COLUMN_INTENT_EXTRA_DATA 来存放与建议项相关的附加数据。在此列中存放的数据将被置于 intent 附带 Bundle 的 EXTRA_DATA_KEY 部分中。

处理 Intent

现在已经能利用自定义 intent 提供自定义的搜索建议项，用户选中某建议项时，需要用搜索 activity 来处理这些 intent。在这之前，搜索 activity 已经对 ACTION_SEARCH intent 进行了处理。下面是如何在 activity 的 onCreate() 回调方法中处理 intent 的示例：

Intent intent = getIntent();

if (Intent.ACTION_SEARCH.equals(intent.getAction())) {

// 处理正常的搜索请求

String query = intent.getStringExtra(SearchManager.QUERY);

doSearch(query);

} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {

// 处理对建议项的点击操作（因为建议项都是使用 ACTION_VIEW 的）

Uri data = intent.getData();

showResult(data);

}

在上例中，intent action 是 ACTION_VIEW ，并且通过组合 android:searchSuggestIntentData 字符串和 SUGGEST_COLUMN_INTENT_DATA_ID 列，数据已包含了指向建议项的完整 URI。该 URI 传给本地的 showResult() 方法，对 URI 指定的建议项在 content provider 中执行查询。

注意： 在 Android manifest 文件中， 不需要 对 android:searchSuggestIntentAction 属性或 SUGGEST_COLUMN_INTENT_ACTION 列设定的 intent action 添加 intent 过滤器。系统将根据名称启动搜索 activity 并传递建议项的 intent，因此 activity 不需要对可接受的 action 进行声明。

改写搜索请求文本

如果用户使用方向控制设备（比如轨迹球或 d-pad）来浏览建议项列表，则默认情况下搜索请求文本不会被更新。不过可以暂时用当前焦点所在的建议项来改写用户请求文本，让它显示在搜索文本框中。这样就能让用户看到建议的请求文本（假如合适的话）并能在发送请求之前选中搜索框来编辑请求文本。

可以通过以下方式来改写搜索请求文本：

a. 在搜索配置文件中添加 android:searchMode 属性，并赋值为"queryRewriteFromText" 。这种情况下，建议项表的 SUGGEST_COLUMN_TEXT_1 列中的内容将会用于改写请求文本。

b. 在搜索配置文件中添加 android:searchMode 属性，并赋值为"queryRewriteFromData" 。这种情况下，建议项表的 SUGGEST_COLUMN_INTENT_DATA 列中的内容将会用于改写请求文本。这只适用于用户需要能看见 URI 或其它格式数据的场合，比如 HTTP URL。内部的 URI 格式不应该使用这种方式来改写请求文本。

c. 在建议项表的 SUGGEST_COLUMN_QUERY 列内提供唯一的请求文本串。如果当前建议项的该列存在并且包含值，将被用于改写请求文本（并且覆盖上面的两种方式）。

向 “ 快速搜索框 ” 提供搜索建议项

一旦把应用程序配置成提供自定义搜索建议项的话，让它适用于全局访问的“快速搜索框”是很容易的，只要修改一下搜索配置文件，让其包含值为"true"的 android:includeInGlobalSearch 属性即可。

唯一要进行额外工作的情况，就是需要向 content provider 请求读权限的时候。这种情况下，需要添加<path-permission>元素，赋予“快速搜索框”对 content provider 的读权限。例如：

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

在上例中，provider 先规定了对 content 的读和写权限。<path-permission>元素修改了这个规定，当存在"android.permission.GLOBAL_SEARCH"权限时，允许对路径前缀为"/search_suggest_query"的内容进行读取访问。这样就对“快速搜索框”赋予向 content provider 查询建议项的权限。

如果 content provider 未明确指定读权限，默认情况下“快速搜索框”是可以读取其中内容的。

启用设备上的建议项

即使已经把应用程序配置为向“快速搜索框”提供建议项，缺省情况下也不会真正生效。是否要在“快速搜索框”中包含应用程序所提供的建议项，是需要由用户选择的。为了启用应用程序提供的搜索建议项，必须打开“可搜索的项”（在“搜索”的“搜索设置”菜单中）并指定应用程序为可搜索项。

每个可用于“快速搜索框”的应用程序都会在“可搜索的项”设置页面中有一个条目。条目中包含了应用程序名称和简要描述信息，这些信息描述了应用程序能够搜索并提交给“快速搜索框”作为建议项的内容。通过在搜索配置文件中添加 android:searchSettingsDescription 属性，可以定义可搜索应用程序的这些描述文字信息。例如：

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

android:searchSettingsDescription 的值应该尽可能地简明扼要，能表明可搜索的内容即可。比如：音乐程序可以用“艺术家、专辑和音轨”，记事本程序则可用“已保存的记录”。提供这些描述信息是非常重要的，这样用户就知道有哪些建议项可用。当 android:includeInGlobalSearch 的值为“true”时，应该确保能包含该属性。

请记住，用户必须访问设置菜单并为应用程序启用搜索建议项，然后搜索建议项才能出现在“快速搜索框中”。因此，假如搜索是应用程序的重要特性之一，则可能需要考虑通过某种方式提醒用户进行设置——可以在第一次启动应用程序时提醒一下，告诉用户如何启用“快速搜索框”中的搜索建议项。

管理 “ 快速搜索框 ” 建议项的快捷方式

用户在“快速搜索框”选中的建议项可以自动变为快捷方式。这些快捷方式是系统从 content provider 中复制过来的建议项，这样就能快速访问建议项，而不必再次查询 content provider。

默认情况下，“快速搜索框”所读取的全部建议项都能启用快捷方式。如果建议项数据经过一段时间后发生了变化，可以发起刷新快捷方式的请求。举例来说，如果建议项指向动态数据，比如联系人的在线状态，那就应该在显示给用户的时候刷新建议项的快捷方式。只要在建议项表中包含 SUGGEST_COLUMN_SHORTCUT_ID 列即可实现这一目标。利用该列可以把每个建议项的快捷方式配置为以下动作：

a. 让“快速搜索框”重新查询 content provider ，以获取建议项快捷方式的最新版本。
在 SUGGEST_COLUMN_SHORTCUT_ID 列中指定一个值，每次显示快捷方式时都会去查询建议项的最新版本。刷新请求返回后，快捷方式将会与最新数据一起显示出来，这时建议项已经用最新信息刷新。刷新请求利用 SUGGEST_URI_PATH_SHORTCUT 的 URI 路径发送至 content provider，（而不是 SUGGEST_URI_PATH_QUERY ）。
返回的 Cursor 应该包含数据列与原来相同的一条建议项，或者为空——表示快捷方式不可用了（这时，建议项将会消失，快捷方式也会被删除）。
如果建议项指向数据的刷新可能需要耗费很长时间，比如基于网络的的刷新，则可以在建议项表中添加 SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING 列并赋值为“true”，这样刷新时就会显示为进度滚轮图标。除“true”以外的任何值都不会显示进度滚轮。

b. 完全阻止把建议项复制为快捷方式。
把 SUGGEST_COLUMN_SHORTCUT_ID 列赋值为 SUGGEST_NEVER_MAKE_SHORTCUT 。这时，建议项就不会复制为快捷方式了。仅当确实不想让以前复制过的建议项显示出来，才会这么做。（如果在该列中提供正常的值并重新调用的话，建议项快捷方式将在刷新请求返回后才显示出来。）

c. 使用默认的快捷方式动作。

建议项不会变化且可以保存为快捷方式，则保持 SUGGEST_COLUMN_SHORTCUT_ID 列为空即可。

如果建议项全都不会发生变化，那就根本不需要 SUGGEST_COLUMN_SHORTCUT_ID 列。

注意： 上述值只是被视作应用程序的需求而已，“快速搜索框”有权最终确定是否建立建议项的快捷方式，它并不保证指定的建议项快捷方式动作一定会实现。

关于 “ 快速搜索框 ” 建议项的级别

一旦应用程序的搜索建议项能够用于“快速搜索框”，则“快速搜索框”将会对其评级，并确定如何根据请求把建议项展现给用户。这可能会依赖于有多少其它应用程序也对该请求返回了结果，也可能会根据用户选中哪个应用程序来返回结果的频度。建议项的评级并没有固定的规则，对于给定的搜索请求是否显示应用程序的建议项也是不能保证的。可以大致这么认为，高质量的结果会增加建议项显示在显著位置的可能性，而低质的建议项则更可能会获得较低的级别或者干脆就不会显示。

关于自定义搜索建议项的完整范例，请参阅 支持检索的字典例程 。