Android官方文档—User Interface（Search）（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

字符串资源。 （必填。）您的申请名称。它应该与应用于<activity>或<application>清单元素的android：label属性的名称相同。当您将android：includeInGlobalSearch设置为“true”时，此标签仅对用户可见，在这种情况下，此标签用于将您的应用程序标识为系统搜索设置中的可搜索项。

android:hint

字符串资源。 （推荐。）未输入文本时在搜索文本字段中显示的文本。它向用户提供有关可搜索内容的提示。为了与其他Android应用程序保持一致，您应该将android：hint的字符串格式化为“Search <content-or-product>”。例如，“搜索歌曲和艺术家”或“搜索YouTube”。

android:searchMode

关键词。设置控制搜索演示文稿的其他模式。当前可用模式定义在自定义建议获得焦点时应如何​​重写查询文本。接受以下模式值：

Value	Description
"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。

搜索建议属性

如果已定义内容提供程序以生成搜索建议，则需要定义配置与内容提供程序通信的其他属性。提供搜索建议时，您需要以下一些<searchable>属性：

android:searchSuggestAuthority

string。 （需要提供搜索建议。）此值必须与Android清单<provider>元素的android：authorities属性中提供的权限字符串匹配。

android:searchSuggestPath

string。此路径用作建议查询Uri的一部分，在前缀和权限之后，但在标准建议路径之前。只有当您有一个内容提供商发布不同类型的建议（例如针对不同的数据类型）时，才需要这样做，并且您需要一种方法来在收到建议查询时消除歧义。

android:searchSuggestSelection

string。此值作为选择参数传递到查询函数中。通常，这是数据库的WHERE子句，并且应包含单个问号，该问号是用户键入的实际查询字符串的占位符（例如，“query =？”）。但是，您还可以使用任何非空值来触发通过selectionArgs参数传递查询文本（然后忽略选择参数）。

android:searchSuggestIntentAction

string。用户单击自定义搜索建议时使用的默认意图操作（例如“android.intent.action.VIEW”）。如果未被所选建议覆盖（通过SUGGEST_COLUMN_INTENT_ACTION列），则当用户单击建议时，此值将放置在Intent的操作字段中。

android:searchSuggestIntentData

string。用户单击自定义搜索建议时要使用的默认目标数据。如果未被所选建议覆盖（通过SUGGEST_COLUMN_INTENT_DATA列），则当用户单击建议时，此值将放置在Intent的数据字段中。

android:searchSuggestThreshold

整数。触发建议查找所需的最少字符数。仅保证系统不会向您的内容提供商查询任何短于阈值的内容。默认值为0。

有关搜索建议的上述属性的详细信息，请参阅添加最近查询建议和添加自定义建议的指南。

快速搜索框属性

要使快速搜索框可以使用自定义搜索建议，您需要以下一些<searchable>属性：

android:includeInGlobalSearch

布尔。 （需要在快速搜索框中提供搜索建议。）如果您希望将建议包含在全局可访问的快速搜索框中，请设置为“true”。在您的建议出现在快速搜索框中之前，用户仍必须将您的应用程序作为系统搜索设置中的可搜索项目启用。

android:searchSettingsDescription

string。提供您提供给快速搜索框的搜索建议的简要说明，该搜索建议显示在应用程序的可搜索项目条目中。您的描述应简明扼要地描述可搜索的内容。例如，音乐应用程序的“艺术家，专辑和曲目”，或记事本应用程序的“已保存的音符”。

android:queryAfterZeroResults

布尔。如果希望为过去返回零结果的查询的超集调用内容提供程序，请设置为“true”。例如，如果您的内容提供商为“bo”返回零结果，则应该要求“bob”。如果设置为“false”，则单个会话将忽略超集（“bob”不会调用requery）。这仅在搜索对话框的生命周期或使用搜索窗口小部件时的活动时间内持续（当重新打开搜索对话框或活动时，“bo”会再次查询您的内容提供商）。默认值为false。

语音搜索属性

要启用语音搜索，您需要以下一些<searchable>属性：

android:voiceSearchMode

关键词。 （需要提供语音搜索功能。）启用语音搜索，使用特定的语音搜索模式。 （设备可能不提供语音搜索，在这种情况下，这些标志无效。）接受以下模式值：

Value	Description
"showVoiceSearchButton"	如果设备上有语音搜索，则显示语音搜索按钮。如果设置，则还必须设置“launchWebSearch”或“launchRecognizer”（由管道|字符分隔）。
"launchWebSearch"	语音搜索按钮将用户直接带入内置语音Web搜索活动。大多数应用程序不需要此标志，因为它使用户远离调用搜索的活动。
"launchRecognizer"	语音搜索按钮将用户直接带入内置的录音活动。此活动提示用户说话，转录口头文本，并将生成的查询文本转发到可搜索的活动，就像用户将其键入搜索UI并单击搜索按钮一样。

android:voiceLanguageModel

关键词。语音识别系统应使用的语言模型。接受以下值：

Value	Description
"free_form"	使用自由格式语音识别来指示查询。这主要针对英语进行了优化。这是默认值。
"web_search"	对较短的类似搜索的短语使用网络搜索术语识别。它提供的语言多于“free_form”。

有关更多信息，另请参阅EXTRA_LANGUAGE_MODEL。

android:voicePromptText

string。要在语音输入对话框中显示的其他消息。

android:voiceLanguage

string。预期的口语，表示为Locale中常量的字符串值（例如德语为“de”或法语为“fr”）。仅当它与Locale.getDefault（）的当前值不同时才需要它。

android:voiceMaxResults

整数。强制返回最大结果数，包括始终作为ACTION_SEARCH目标主查询提供的“最佳”结果。必须是1或更高。使用EXTRA_RESULTS从意图中获取结果。如果未提供，识别器将选择返回多少结果。

<actionkey>

定义搜索操作的设备密钥和行为。根据当前查询或重点建议，搜索操作在触摸设备上的按钮时提供特殊行为。例如，“联系人”应用程序提供搜索操作，以便在按下“呼叫”按钮时启动对当前关注的联系人建议的电话呼叫。

并非所有操作键都可用于每个设备，并且不允许以这种方式覆盖所有键。例如，“Home”键无法使用，必须始终返回主屏幕。另外，请确保不要为键入搜索查询所需的键定义操作键。这实际上限制了可用和合理的操作键到呼叫按钮和菜单按钮。另请注意，操作键通常不可发现，因此您不应将其作为核心用户功能提供。

您必须定义android：keycode以定义密钥，并定义其他三个属性中的至少一个以定义搜索操作。

属性：

android:keycode

string。 （必需。）来自KeyEvent的键代码，表示您希望响应的操作键（例如“KEYCODE_CALL”）。这将添加到传递给您的可搜索活动的ACTION_SEARCH目标中。要检查密钥代码，请使用getIntExtra（SearchManager.ACTION_KEY）。并非所有键都支持搜索操作，因为其中许多键用于键入，导航或系统功能。

android:queryActionMsg

string。如果在用户输入查询文本时按下操作键，则要发送的操作消息。这将添加到系统传递给您的可搜索活动的ACTION_SEARCH目标中。要检查字符串，请使用getStringExtra（SearchManager.ACTION_MSG）。

android:suggestActionMsg

string。如果在建议处于焦点时按下操作键，则要发送的操作消息。这被添加到系统传递给您的可搜索活动的意图中（使用您为建议定义的操作）。要检查字符串，请使用getStringExtra（SearchManager.ACTION_MSG）。只有在您的所有建议都支持此操作键时才应使用此选项。如果不是所有建议都可以处理相同的操作键，那么您必须使用以下android：suggestActionMsgColumn属性。

android:suggestActionMsgColumn

string。内容提供程序中列的名称，用于定义此操作键的操作消息，如果用户在建议处于焦点时按下操作键，则会发送该列。此属性允许您在建议的基础上控制操作键，因为您的内容提供程序中的每个条目都提供了自己的操作消息，而不是使用android：suggestActionMsg属性来定义所有建议的操作消息。

首先，您必须在内容提供程序中为每个建议定义一列以提供操作消息，然后在此属性中提供该列的名称。系统查看您的建议光标，使用此处提供的字符串选择您的操作消息列，然后从Cursor中选择操作消息字符串。该字符串将添加到系统传递给您的可搜索活动的意图中（使用您为建议定义的操作）。要检查字符串，请使用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>