Question

搜索配置文件

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

版本：Android 4.0 r1

原文

http://developer.android.com/guide/topics/search/searchable-config.html

参阅

创建搜索界面

添加最近请求建议项

添加自定义建议项

为了能在 Android 系统的辅助下（发送搜索请求到 activity 并提供搜索建议项）实现搜索功能，应用程序必须提供一个 XML 格式的搜索配置文件。

本文描述了搜索配置文件的语法和使用方式。关于应用程序如何实现搜索特性的详细信息，在开发者指南的 创建搜索界面 中进行描述。

文件位置：

res/xml/ filename .xml
Android 用文件名作为资源 ID。

语法：

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

< searchable xmlns:android="http://schemas.android.com/apk/res/android"

android:label=" string resource "

android:hint=" string resource "

android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]

android:searchButtonText=" string resource "

android:inputType=" inputType "

android:imeOptions=" imeOptions "

android:searchSuggestAuthority=" string "

android:searchSuggestPath=" string "

android:searchSuggestSelection=" string "

android:searchSuggestIntentAction=" string "

android:searchSuggestIntentData=" string "

android:searchSuggestThreshold=" int "

android:includeInGlobalSearch=["true" | "false"]

android:searchSettingsDescription=" string resource "

android:queryAfterZeroResults=["true" | "false"]

android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]

android:voiceLanguageModel=["free-form" | "web_search"]

android:voicePromptText=" string resource "

android:voiceLanguage=" string "

android:voiceMaxResults=" int "

>

< actionkey

android:keycode=" KEYCODE "

android:queryActionMsg=" string "

android:suggestActionMsg=" string "

android:suggestActionMsgColumn=" string " >

</searchable>

元素：

<searchable>

定义了 Android 系统为了支持搜索所需的全部搜索配置信息。

属性：

android:label

字符串资源 。（必填项。）应用程序的名称。应该是与 <activity> 或 manifest 中 <application> 元素的 android:label 属性相一致。仅当 android:includeInGlobalSearch 设为“true”时，用户才能看见本文本标签。这时标签用于标识本应用程序，并作为可搜索项显示在系统的搜索设置菜单中。

android:hint

字符串资源 。（建议项。）在没有录入文字时，显示在搜索文本框中的文本。它向用户提示了可搜索的内容。为了与其它 Android 应用保持一致，应该把 android:hint 定义的文本写成“搜索< 内容 - 或 - 产品 > ”的格式。例如，“搜索歌曲和艺术家”或“搜索 YouTube”。

android:searchMode

关键字 。设置控制搜索显示的其它模式。目前可用的模式定义了自定义建议项获得焦点时搜索文本的改写方式。以下列出了可用的模式：

值	描述
"queryRewriteFromText"	用 SUGGEST_COLUMN_TEXT_1 列中的值改写查询请求文本。
"queryRewriteFromData"	用 SUGGEST_COLUMN_INTENT_DATA 列中的值改写查询请求文本。仅当 SUGGEST_COLUMN_INTENT_DATA 中的值符合用户的要求并开始编辑时才会用到，典型的场合是 HTTP URI 。

详情请参阅 添加自定义建议项 中关于改写请求文本的部分。

android:searchButtonText

字符串资源 。显示在执行搜索按钮上的文本。默认情况下，按钮上会显示一个搜索图标（放大镜），这是理想的国际化方案。除非某些时候不是要执行搜索操作（比如 Web 浏览器中的 URL 请求），否则不应该使用本属性来改变按钮的显示。

android:inputType

关键字。 定义了要使用的录入方式（比如软键盘）。大多数搜索都需要能录入任意字符，也就不必用到本属性。本属性可用值的清单请参阅 inputType 。

android:imeOptions

关键字。 提供录入方式的其它选项。大多数搜索都需要能录入任意字符，也就不必用到本属性。缺省的 IME 是“actionSearch”（在软键盘上提供“搜索”按钮并取代回车）。本属性可用值的清单请参阅 imeOptions 。

搜索建议项的属性

如果定义了 content provider 来提供搜索建议项，则需要定义更多的属性来对 content provider 的交互进行配置。当提供自定义建议项时，需要以下<searchable>属性：

android:searchSuggestAuthority

字符串 。（提供搜索建议项时需要。）本属性值必须符合 Android manifest 文件中<provider>元素的 android:authorities 属性所提供的权限。

android:searchSuggestPath

字符串 。该路径用作建议项请求 Uri 的组成部分，位于前缀和权限之后，但在标准建议项路径之前。仅当只有一个 content provider 来提供多种建议项时（比如不同数据类型），才需要用到该属性，并且需要采取必要措施来消除歧义的建议项请求（区分出不同的建议项请求）。

android:searchSuggestSelection

字符串 。该值将作为 selection 参数传给查询函数。典型的情况是一个数据库 WHERE 语句，并应包含一个问号作为用户录入的实际查询字符的占位符（比如"query=?"）。当然也可以通过在 selectionArgs 参数中指定任何非空值来触发查询文本的传递（这样就会忽略 selection 参数）。

android:searchSuggestIntentAction

字符串。 用户点击自定义搜索建议项时（比如"android.intent.action.VIEW"）默认使用的 intent action。如果未被选中建议项覆盖（通过 SUGGEST_COLUMN_INTENT_ACTION 列），则用户点击建议项时本属性值将被放入 Intent 的 action 部分。

android:searchSuggestIntentData

字符串。 用户点击自定义搜索建议项时默认使用的 intent data。如果未被选中建议项覆盖（通过 SUGGEST_COLUMN_INTENT_DATA 列），则用户点击建议项时本属性值将被放入 Intent 的 data 部分。

android:searchSuggestThreshold

整数 。请求文本的字符数量至少要大于该数值才会触发建议项的查询。系统只保证不会向 content provider 提交任何短于该阈值的查询请求。默认值是 0。

关于以上搜索建议项属性的详情，请参阅开发者指南的 添加最近请求建议项 和 添加自定义建议项 部分。

“ 快速搜索框 ” 的属性

为了让自定义建议项能被用于“快速搜索框”，需要以下<searchable> 属性：

android:includeInGlobalSearch

布尔值。 （在“快速搜索框”中提供搜索建议项时需要。）如果建议项需被用于全局访问的“快速搜索框”，则设为“true”。用户还是必须先在系统的搜索配置菜单中启用应用程序对应的可搜索项，然后建议项才能出现在“快速搜索框”中。

android:searchSettingsDescription

字符串 。为提交给“快速搜索框”的搜索建议项提供简要描述信息，这些信息将显示在应用程序对应的可搜索项条目中（搜索配置菜单内）。描述信息应该简要描述可搜索的内容。比如：音乐程序可以是“艺术家、专辑名和音轨”，记事本程序则可以是“已保存的记录”。

android:queryAfterZeroResults

布尔值。 如果需要让 content provider 能够接受搜索请求的超集，则设置为“true”，这些请求在以前搜索时返回结果为零。比如，如果 content provider 对“bo”返回 0 个结果，则应该要搜索“bob”。如果设为“false”，同一个会话中将忽略超集（“bob”将不会再次发起请求）。不过这只会维持至搜索对话框生命周期结束，如果使用搜索 widget 则是到 activity 生命周期结束（当搜索对话框或 activity 重新被打开时，“bo”会再次向 content provider 提交请求）。默认值是 false。

语音搜索的属性

为了启用语音搜索功能，需要以下<searchable>属性中的一些：

android:voiceSearchMode

关键字 。（提供语音搜索功能时需要。）启用语音搜索功能，并同时指定搜索模式。 （某些设备可能不支持语音搜索，那这些标记就无效。）可以接受以下模式值：

值	描述
"showVoiceSearchButton"	如果设备支持语音搜索，则显示一个语音搜索按钮。如果设置此值，则必须同时设置"launchWebSearch"或"launchRecognizer"（用管道符“|”分隔）。
"launchWebSearch"	语音搜索按钮让用户直接使用内置的语音 web 搜索 activity。绝大部分应用程序不需要用到本标记，因为它会使得用户离开提交搜索的当前 activity。
"launchRecognizer"	语音搜索按钮让用户直接使用内置的录音 activity。该 activity 将会引导用户说话，把语音转译为文本，并把结果作为请求文本提交给搜索 activity，就如同用户在搜索界面录入并点击搜索按钮一样。

android:voiceLanguageModel

关键字 。语音识别系统使用的语言模式。可接受以下值：

值	描述
"free_form"	语音识别使用自由模式（free-form）。这种模式主要是为英语优化的。 这是缺省值。
"web_search"	语音识别使用 web 检索词（web-search-term）模式，用于简短的、类似检索关键词的短语。 该模式可用的语言比上述自由模式“free_form”多一些。

详情请参阅 EXTRA_LANGUAGE_MODEL 。

android:voicePromptText

字符串。 显示在语音输入对话框中的其它信息。

android:voiceLanguage

字符串。 期望的语言，用 Locale 中的字符串常量表示（比如“de”表示德语，“”表示法语）。仅当所用语言与 Locale.getDefault() 获得的当前值不同时，才需要用到本值。

android:voiceMaxResults

整数。 指定最多返回几个结果，其中的“最佳”结果将用于 ACTION_SEARCH intent 的主要请求文本。本值必须大于等于 1。用 EXTRA_RESULTS 可以从 intent 获取这些结果。如果未提供本值，则语音识别程序将会确定返回结果的数量。

<actionkey>

为搜索 action 指定一个设备上的按键及动作。在触摸屏幕按钮时，根据当前搜索请求或当前获得焦点的建议项，搜索 action 将能执行设定的操作。比如，联系人应用程序在按下通话按钮时能够执行启动电话的搜索 action，与当前获得焦点的联系人建议项进行通话。

并不是每台设备都支持全部的 action 键，也不是所有键都允许用这种方式覆盖。比如，“Home”键就不行，它必须保证能返回初始屏幕。还必须确保不要指定为录入搜索请求时可能会用到的键。本属性基本上仅限于指定为通话按钮和菜单按钮。请记住 action 键通常不是很显眼，因此不应该把它作为核心功能来提供给用户。

必须定义 android:keycode 来指定键，并至少要同时指定另外三个属性中的一个，才能完成搜索 action 的定义。

属性：

android:keycode

字符串。 （必填项） KeyEvent 中定义的键值，代表所响应的 action 键（比如“KEYCODE_CALL”）。 本值将附在 ACTION_SEARCH intent 中传递给搜索 activity。用 getIntExtra(SearchManager.ACTION_KEY) 可以获取本值。并非所有键都可用于搜索 action，多数键是用于录入键盘或者系统功能键的。

android:queryActionMsg

字符串。 在用户录入搜索请求文本时，按下 action 键所附带的 action 信息。本值将附在 ACTION_SEARCH intent 中传递给搜索 activity。用 getStringExtra(SearchManager.ACTION_MSG) 可以获取本值。

android:suggestActionMsg

字符串。 在建议项获得焦点时，按下 action 键所附带的 action 信息。本值将附在系统传递给搜索 activity 的 intent 中（使用预先定义的建议项对应的 action）。用 getStringExtra(SearchManager.ACTION_MSG) 可以获取本值。仅当所有建议项都支持本 action 键时才能使用本属性。如果不是所有建议项都能处理同一个 action 键，必须换用下面的 android:suggestActionMsgColumn 属性。

android:suggestActionMsgColumn

字符串。 content provider 中的数据列名，用于提供本 action 键对应的 action 信息，在建议项获得焦点时，按下 action 键将发送该 action 信息。本属性可以控制每个建议项各自的 action 键，content provider 中的每一条数据都有自己的 action 信息。本属性可以取代 android:suggestActionMsg 属性，因为它为所有建议项指定相同的 action 信息。

首先，必须在 content provider 中为每个建议项定义数据列，用于提供 action 信息，然后在本属性中给出列名。系统会用本属性给出的字符串在建议项 cursor 中查找，选中 action 信息列，并读取 Cursor 中的 action 信息。本值将附在系统传递给搜索 activity 的 intent 中（使用预先定义的建议项对应的 action）。用 getStringExtra(SearchManager.ACTION_MSG) 可以获取本值。如果选定建议项对应的数据不存在，action 键将被忽略。

示例：

保存于 res/xml/searchable.xml 的 XML 文件：

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

<searchable xmlns:android="http://schemas.android.com/apk/res/android"

android:label="@string/search_label"

android:hint="@string/search_hint"

android:searchSuggestAuthority="dictionary"

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

android:includeInGlobalSearch="true"

android:searchSettingsDescription="@string/settings_description" >

</searchable>