Android API Guides---Searchable Configuration

Searchable Configuration

为了实现与Android系统（提供搜索查询到活动中，并提供搜索建议）协助搜索，应用程序必须提供一个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
字符串资源。 （必需的）应用程序的名称。它应该是一样适用于Android的名字：您<活动>或<应用> manifest元素的标签属性。 includeInGlobalSearch为“true”。在这样的情况下。这个标签是用来识别您的应用程序在系统中的搜索设置一个可搜索项：当你设置的android这个标签是唯一对用户可见。
android:hint
字符串资源。 （推荐）。文字在搜索文本字段时未输入文本显示。

它提供了一个提示。关于哪些内容是搜索的用户。

为了与其它Android应用程序的一致性。你应该格式化为Android字符串：提示为“搜索<内容或产品>”。

比如。“搜索歌曲和艺术家”或“搜索YouTube”的视频。

android:searchMode
关键词。设置用于控制搜索介绍附加模式。

眼下可用的模式定义怎样当一个自己定义的建议获得焦点的查询文本应该改写。

以下的模式值被接受：

Value	Description
"queryRewriteFromText"	Use the value from the SUGGEST_COLUMN_TEXT_1 column to rewrite the query text.
"queryRewriteFromData"	Use the value from the SUGGEST_COLUMN_INTENT_DATAcolumn to rewrite the query text. This should only be used when the values in SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing, typically HTTP URI's.

值说明
“queryRewriteFromText”从SUGGEST_COLUMN_TEXT_1列使用值重写查询文本。

“queryRewriteFromData”从SUGGEST_COLUMN_INTENT_DATA列使用值重写查询文本。当SUGGEST_COLUMN_INTENT_DATA的数值适用于用户检查和编辑。典型的HTTP URI的这应该仅仅被使用。

了解很多其它信息，请參阅关于加入自己定义建议重写查询文本的讨论。

android:searchButtonText
字符串资源。该文在运行搜索button显示。

默认情况下。该button会显示一个搜索图标（放大镜），这是理想的国际化。所以除非行为是其它东西比搜索（如在Web URL请求。你不应该使用这个属性来更改button浏览器）。

android:inputType
关键词。定义输入方法的类型（如软键盘的类型）使用。

对于大多数的搜索。当中自由格式文本的预期，则不须要此属性。

见inputType下针对此属性合适的值的清单。
android：imeOptions
关键词。耗材为输入法的附加选项。

对于大多数的搜索，当中自由格式文本的预期，则不须要此属性。默认的输入法是“actionSearch”（提供了“搜索”button，而不是在软键盘回车）。见imeOptions针对此属性合适的值的清单。

搜索建议属性


假设您已经定义了一个内容提供商生成的搜索建议。你须要定义配置与内容提供商通信的附加属性。在提供搜索建议。你须要一些以下<搜索>属性：




android：searchSuggestAuthority
串。 （需提供搜索建议。

）该值必须在android规定的权限匹配字符串：Android清单<provider>元素的authorities属性。
android：searchSuggestPath
串。此路径用作建议查询URI的一部分，前缀和权威之后，但在标准的建议路径之前。

这个，假设你有一个单一的内容提供商发出不同类型的建议（如不同的数据类型）时。才须要，你须要一种方式。当您收到他们歧义的建议查询。
android：searchSuggestSelection
串。

这个值被传递到你的查询功能作为选择參数。

通常，这是为你的数据库中的WHERE子句。而且应该包括一个问号，这对于已输入的用户（比如，“查询=？”）的实际查询字符串的占位符。可是，您也能够使用不论什么非空值通过selectionArgs两个參数触发查询文本交付（然后忽略选择參数）。
android：searchSuggestIntentAction
串。

当用户点击自己定义搜索建议。能够使用默认的意图动作（如“android.intent.action.VIEW”）。假设没有被选中的建议（通过SUGGEST_COLUMN_INTENT_ACTION列）覆盖。当用户点击一个建议，这个值被放在意向的行动领域。
android：searchSuggestIntentData
串。当用户点击自己定义搜索建议。使用默认意图数据。

假设没有选择的建议（通过SUGGEST_COLUMN_INTENT_DATA列）覆盖，当用户点击一个建议，这个值被放置在Intent的数据字段。
android：searchSuggestThreshold
整数。所需的最小字符数来触发一个建议查询。仅仅有保证系统不会询问您的内容提供商以外的不论什么阈值短。

缺省值是0。
有关搜索建议上述属性的具体信息，请參阅指南为近期查询建议添加和加入自己定义建议。


高速搜索框属性


为了使您的自己定义搜索建议提供给高速搜索框，你须要一些以下<搜索>属性：




android：includeInGlobalSearch
布尔。 （需提供在高速搜索框的搜索建议。）设置为“true”，假设你想被列入全球訪问高速搜索框您的建议。用户仍然必须启用您的应用程序在系统中搜索设置一个可搜索的项目之前。您的建议将出如今高速搜索框。
android：searchSettingsDescription
串。提供了您提供高速搜索框，它会显示在搜索项的条目为您的应用搜索建议的简要说明。

你的描写叙述应该简明地描写叙述就是搜索的内容。比如，“艺术家，专辑和曲目”的音乐应用程序，或记事本应用“保存笔记”。
android：queryAfterZeroResults
布尔。设置为“真”，假设你想你的内容提供商调用对于已在过去的返回结果为零查询的超集。比如。假设你的内容提供商返回零结果“博”。应为requiried“鲍勃”。假设设置为“假”，超集是为单个会话忽略（“鲍勃”不会调用又一次查询）。

这仅持续了搜索对话框的生命或使用搜索窗体小部件（当搜索对话框或活动被又一次打开。“博”再次查询内容提供商）时。活动的生活。默认值是假的。
语音搜索属性


要启用语音搜索，你须要一些以下的<搜索>属性：




android：voiceSearchMode
关键词。 （需提供语音搜索功能。）启用语音搜索，为语音搜索一个特定的模式。

（语音搜索可能无法通过该设备，在这样的情况下。这些标志没有不论什么效果来提供。）下面模式值被接受：

值说明
“秀语音搜索键”查看语音搜索button，假设语音搜索可在设备上。

假设设置。则要么“launchWebSearch”或“launchRecognizer”也必须设置（通过管道|分隔符）。

“launchWebSearch”语音搜索button。直接将用户带到一个内置语音网络搜索活动。

大多数应用程序并不须要这个标志，由于它须要用户远离当中搜索被调用的活动。
“launchRecognizer”语音搜索button。直接将用户带到一个内置的录音活动。该活动提示用户说话，录制口述文本，并将由此形成的查询文本的搜索活动，就如同假设用户键入它进入搜索界面。并点击搜索button。

android:voiceLanguageModel
关键词。语言模型应该由语音识别系统中使用。以下的值被接受：

Value	Description
"free_form"	Use free-form speech recognition for dictating queries. This is primarily optimized for English. This is the default.
"web_search"	Use web-search-term recognition for shorter, search-like phrases. This is available in more languages than "free_form".

另请參阅EXTRA_LANGUAGE_MODEL以获取很多其它信息。


机器人：voicePromptText
串。

另外一个消息，在语音输入对话框显示。
机器人：voiceLanguage
串。能够预料的口语，表现为常数的语言环境的字符串值（如“德”为德语或“FR”的法语）。这是必要的，仅仅有当它是从Locale.getDefault的当前值不同（）。
机器人：voiceMaxResults
整数。

强制结果的最大数量返回，当中包含“最佳”的结果它总是作为ACTION_SEARCH意图的主要查询提供。必须大于或等于1。使用EXTRA_RESULTS来从意图的结果。

假设没有提供，识别器选择多少的成绩来回报。
<actionkey>
定义为搜索动作的装置密钥和行为。一个搜索行动在button的设备上的触摸提供了一个特殊的行为。基于当前的查询或集中的建议。

比如。联系人应用程序提供了搜索行动在CALL按下button启动一个电话给currenly集中接触的建议。
并不是全部的操作键都能够在每一个设备上，而且不是全部的键被同意以这样的方式被重写。比如。“Home”键不能使用，必须总是返回到主屏幕。

此外，一定不要定义该公司须要键入搜索查询一键操作键。这基本上限制了可用的和合理的操作键来调用键和菜单键。

还要注意的是操作键都没有发现一般。所以你不应该为他们提供作为核心用户功能。


必须定义机器人：键码来定义。以确定在搜索行动的密钥和其他三个属性中的至少一个。


属性：
android:keycode
串。

（必需）从KeyEvent的关键代码。表示要到（比如，“KEYCODE_CALL”），响应操作键。

这是加入到传递到你的搜索活动ACTION_SEARCH意图。

要检查钥匙代码，使用getIntExtra（SearchManager.ACTION_KEY）。

不是全部的按键，支持的搜索行动。由于当中很多是用于打字，导航，或系统功能。
android：queryActionMsg
串。假设在用户输入查询文本按下操作键要发送的操作信息。此被增加到该系统传递到您的搜索活动ACTION_SEARCH意图。要检查字符串。请使用getStringExtra（SearchManager.ACTION_MSG）。
android：suggestActionMsg
串。假设按下了操作键。而一个建议是在焦点要被发送的动作信息。这是加入到系统传递给你的搜索活动（使用你的建议定义的操作）的意图。要检查字符串，请使用getStringExtra（SearchManager.ACTION_MSG）。

假设您的建议支持此操作键这应该仅仅被使用。

假设不是全部的建议，能够处理同样的操作键，则必须改用下面的android：suggestActionMsgColumn属性。

android：suggestActionMsgColumn
串。

在内容提供商定义此操作键，也就是当用户按下操作键时一个建议是在焦点要发送的动作信息的列的名称。

这个属性能够让你控制一条建议按建议的基础操作键。是由于。而是採用了android：suggestActionMsg属性来定义全部建议的行动信息，在内容提供商的每一个条目提供自己的行动的消息。
首先，你必须在你的内容提供商将列定义为每一个建议提供一个动作消息，然后提供此属性的列的名称。

该系统着眼于你的建议光标，使用这里提供的选择行动的消息栏。然后选择从光标动作消息字符串字符串。该字符串被加入到该系统传递给你的搜索活动（使用你的建议定义的动作）的意图。

要检查字符串，请使用getStringExtra（SearchManager.ACTION_MSG）。假设该数据不为选定建议存在，则操作键被忽略。


例：
在保存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>

Value	Description
"free_form"	Use free-form speech recognition for dictating queries. This is primarily optimized for English. This is the default.
"web_search"	Use web-search-term recognition for shorter, search-like phrases. This is available in more languages than "free_form".