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
关键词。设置用于控制搜索介绍附加模式。目前可用的模式定义如何当一个自定义的建议获得焦点的查询文本应该改写。下面的模式值被接受：

ValueDescription"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
字符串资源。该文在执行搜索按钮显示。默认情况下，该按钮会显示一个搜索图标（放大镜），这是理想的国际化，所以除非行为是其他东西比搜索（如在Web URL请求，你不应该使用这个属性来更改按钮浏览器）。

android:inputType
关键词。定义输入方法的类型（如软键盘的类型）使用。对于大多数的搜索，其中自由格式文本的预期，则不需要此属性。见inputType下针对此属性合适的值的清单。
android：imeOptions
关键词。耗材为输入法的附加选项。对于大多数的搜索，其中自由格式文本的预期，则不需要此属性。默认的输入法是“actionSearch”（提供了“搜索”按钮，而不是在软键盘回车）。见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
关键词。 （需提供语音搜索功能。）启用语音搜索，为语音搜索一个特定的模式。 （语音搜索可能无法通过该设备，在这种情况下，这些标志没有任何效果来提供。）以下模式值被接受：

值说明
“秀语音搜索键”查看语音搜索按钮，如果语音搜索可在设备上。如果设置，则要么“launchWebSearch”或“launchRecognizer”也必须设置（通过管道|分隔符）。
“launchWebSearch”语音搜索按钮，直接将用户带到一个内置语音网络搜索活动。大多数应用程序并不需要这个标志，因为它需要用户远离其中搜索被调用的活动。
“launchRecognizer”语音搜索按钮，直接将用户带到一个内置的录音活动。该活动提示用户说话，录制口述文本，并将由此形成的查询文本的搜索活动，就如同如果用户键入它进入搜索界面，并点击搜索按钮。

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

ValueDescription"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>
定义为搜索动作的装置密钥和行为。一个搜索行动在按钮的设备上的触摸提供了一个特殊的行为，基于当前的查询或集中的建议。例如，联系人应用程序提供了搜索行动在CALL按下按钮启动一个电话给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>

ValueDescription"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".