Searchable Configuration

译者署名：呆呆大虾

译者链接：

版本：Android 4.0 r1

参阅

创建搜索界面

添加最近请求建议项

添加自定义建议项

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

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

文件位置：

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

语法：

元素：

<searchable>

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

属性：

android:label

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

android:hint

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

android:searchMode

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

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

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”，同一个session中将忽略超集（“bob”将不会再次发起请求）。不过这只会维持至搜索对话框生命周期结束，如果使用搜索widget则是到activity生命周期结束（当搜索对话框或activity重新被打开时，“bo”会再次向content provider提交请求）。默认值是false。

语音搜索的属性

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

android:voiceSearchMode

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

android:voiceLanguageModel

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

详情请参阅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文件：