Android开发指南(41) —— Searchable Configuration
前言
本章内容为 Android开发者指南的 Framework Topics/Search/Searchable Configuration章节，译为"搜索配置文件"，版本为Android 4.0 r1，翻译来自："呆呆大虾"，欢迎访问他的微博："http://weibo.com/popapa"，再次感谢"呆呆大虾" ！期待你一起参与翻译Android的相关资料，联系我over140@gmail.com。
搜索配置文件
译者署名： 呆呆大虾
译者微博： 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"
>
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>
