搜索配置

为了在 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"
    >
    <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 字符串的格式设为“搜索 <content-or-product>”。例如，“搜索歌曲和音乐人”或“搜索 YouTube”。

android:searchMode

关键字。设置用于控制搜索呈现的其他模式。可用模式定义了当自定义建议获得焦点时，需要如何重新编写查询文本。接受以下模式值：

值	说明
"queryRewriteFromData"	使用 SUGGEST_COLUMN_INTENT_DATA 列中的值重新编写查询文本。只有在 SUGGEST_COLUMN_INTENT_DATA 中的值（例如 HTTP URI）适合用户检查和修改时，才应使用此项。
"queryRewriteFromText"	使用 SUGGEST_COLUMN_TEXT_1 列中的值重新编写查询文本。

如需了解详情，请参阅添加自定义搜索建议中有关重新编写查询文本的文档。

android:searchButtonText

字符串资源。要显示在用于执行搜索的按钮中的文本。默认情况下，按钮会显示搜索图标（放大镜），这是国际化的理想选择。因此，您不应使用此属性来更改按钮，除非行为不是搜索（如网络浏览器中的网址请求）。

android:inputType

关键字。定义要使用的输入法的类型，例如软键盘的类型。对于大多数搜索（需要自由格式文本）来说，您不需要此属性。 如需查看适合此属性的值的列表，请参阅 inputType。

android:imeOptions

关键字。提供输入法的其他选项。对于大多数搜索（需要自由格式文本）来说，您不需要此属性。默认 IME 为 actionSearch，它在软键盘中提供“搜索”按钮，而不是回车键。如需查看适合此属性的值的列表，请参阅 imeOptions。

搜索建议属性

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

android:searchSuggestAuthority

字符串。（提供搜索建议所必需的属性）。此值必须与 Android 清单 <provider> 元素的 android:authorities 属性中提供的授权方字符串相符。

android:searchSuggestPath

字符串。此路径用作建议查询 Uri 的一部分，在前缀和授权方之后，但在标准建议路径之前。只有在单个内容提供程序发出不同类型的建议（例如，针对不同的数据类型），而您在收到建议查询后需要一种方法来消除它们的歧义时，才需要此属性。

android:searchSuggestSelection

字符串。此值作为 selection 参数传递给查询函数。通常，这是数据库的 WHERE 子句，并且必须包含一个问号作为用户输入的实际查询字符串的占位符，例如 "query=?"。不过，您也可以使用任何非 null 值通过 selectionArgs 参数触发查询文本的传递，然后忽略 selection 参数。

android:searchSuggestIntentAction

字符串。当用户点按自定义搜索建议（例如 "android.intent.action.VIEW"）时要使用的默认 intent 操作。如果此值未被所选建议使用 SUGGEST_COLUMN_INTENT_ACTION 列替换，则当用户点按建议时，系统会将此值放在 Intent 的操作字段中。

android:searchSuggestIntentData

字符串。当用户点按自定义搜索建议时要使用的默认 intent 数据。如果未由选定的建议替换（通过 SUGGEST_COLUMN_INTENT_DATA 列），则当用户点按建议时，系统会将此值放在 Intent 的数据字段中。

android:searchSuggestThreshold

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

如需详细了解搜索建议的上述属性，请参阅添加自定义搜索建议和添加自定义建议的相关文档。

快速搜索框属性

要将自定义搜索建议提供给快速搜索框，您需要以下某些 <searchable> 属性：

android:includeInGlobalSearch

布尔值。（在快速搜索框中提供搜索建议所必需的属性）。如果您希望自己的建议包含在全局可访问的快速搜索框中，请将其设为 "true"。用户仍必须先在系统搜索设置中将您的应用作为可搜索项启用，然后您的建议才会显示在快速搜索框中。

android:searchSettingsDescription

字符串资源。提供一段简短说明来概括您向快速搜索框提供的搜索建议，这段说明会显示在您的应用的可搜索项条目中。说明必须简洁地描述可搜索的内容。例如，音乐应用的说明为“音乐人、专辑和曲目”，记事本应用的说明为“保存的记事”。

android:queryAfterZeroResults

布尔值。如果您希望针对之前返回了零个结果的查询的超集调用内容提供程序，请将其设为 "true"。例如，如果内容提供程序针对“bo”返回了零个结果，则必须针对“bob”进行重新查询。如果设为 "false"，则会针对单个会话忽略超集，“bob”不会调用重新查询。此设置只在搜索对话框的生命周期内或 Activity 的生命周期内（使用搜索微件时）有效。重新打开搜索对话框或 activity 后，“bo”会再次查询内容提供程序。默认值为 false。

语音搜索属性

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

android:voiceSearchMode

关键字。（提供语音搜索功能所必需的属性）。以特定的语音搜索模式启用语音搜索。设备可能不提供语音搜索，在这种情况下，这些标志不起作用。接受以下模式值：

值	说明
"showVoiceSearchButton"	如果可在设备上使用语音搜索，则显示语音搜索按钮。如果设置了此项，则还必须设置 "launchWebSearch" 或 "launchRecognizer"（以竖线 [|] 字符分隔）。
"launchWebSearch"	语音搜索按钮会使用户直接进入内置的语音网页搜索 activity。大多数应用都不使用此标志，因为它会使用户离开调用搜索的 activity。
"launchRecognizer"	语音搜索按钮会使用户直接进入内置的录音 activity。此 activity 会提示用户说话，转录所说的文本，并将生成的查询文本转发给可搜索 activity，就像用户在搜索界面中输入文本并点按搜索按钮一样。

android:voiceLanguageModel

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

值	说明
"free_form"	对口述查询使用自由格式语音识别。这主要针对英语进行了优化。这是默认值。
"web_search"	对较短的搜索式短语使用网页搜索字词识别。此值支持的语言比 "free_form" 要多。

如需了解详情，请参阅 EXTRA_LANGUAGE_MODEL。

android:voicePromptText

字符串资源。要显示在语音输入对话框中的附加消息。

android:voiceLanguage

字符串。预期的口述语言，表示为 Locale 中常量的字符串值，例如 "de" 表示德语，"fr" 表示法语。仅当此值与 Locale.getDefault() 的当前值不同时，才需要此值。

android:voiceMaxResults

整数。设置要返回的结果数上限，包括始终作为 ACTION_SEARCH intent 的主要查询提供的“最佳”结果。必须等于或大于 1。使用 EXTRA_RESULTS 可从 intent 获取结果。 如果未提供，将由识别程序选择要返回多少结果。

<actionkey>

定义搜索操作的设备键和行为。搜索操作根据当前的查询或获得焦点的建议，在用户点按设备上的按钮时提供一种特殊的行为。例如，“通讯录”应用提供了一项搜索操作，可以在用户点按“通话”按钮时向当前获得焦点的建议联系人发起通话。

并非所有操作键在每个设备上都可用，也不是所有键都可以以这种方式替换。例如，“主屏幕”键无法被替换，按该键时必须始终返回到主屏幕。此外，确保不要为输入搜索查询所需的键定义操作键。因此，可用且合理的操作键被限定为通话按钮和菜单按钮。

您必须定义 android:keycode 以定义键以及其他三个属性中的至少一个，才能定义搜索操作。

属性：

android:keycode

字符串。（必需）。来自 KeyEvent 的键码，表示您希望响应的操作键，例如 "KEYCODE_CALL"。它会被添加到传递给可搜索 activity 的 ACTION_SEARCH intent。如需检查键码，请使用 getIntExtra(SearchManager.ACTION_KEY)。 搜索操作并非对所有键都适用，因为其中许多键用于输入、导航或执行系统功能。

android:queryActionMsg

字符串。在用户输入查询文本时按操作键后要发送的操作消息。它会被添加到系统传递给可搜索 activity 的 ACTION_SEARCH intent。如需检查该字符串，请使用 getStringExtra(SearchManager.ACTION_MSG)。

android:suggestActionMsg

字符串。在建议获得焦点时按操作键后要发送的操作消息。它会被添加到系统传递给可搜索 activity 的 intent 中，使用您为建议定义的操作。如需检查该字符串，请使用 getStringExtra(SearchManager.ACTION_MSG)。 仅当所有建议都支持此操作键时，才应使用此属性。如果并非所有建议都能处理同一操作键，则必须改用以下 android:suggestActionMsgColumn 属性。

android:suggestActionMsgColumn

字符串。内容提供程序中用于定义此操作键的操作消息（即，在建议获得焦点时用户按操作键后要发送的操作消息）的列的名称。通过此属性，您可以分别针对每条建议控制操作键，因为内容提供程序中的每个条目都会提供其自己的操作消息，而不是使用 android:suggestActionMsg 属性为所有建议定义操作消息。

首先，您必须在内容提供程序中为每条建议定义用来提供操作消息的一列，然后在此属性中提供该列的名称。系统会查看建议 Cursor，使用此处提供的字符串来选择操作消息列，然后从该 Cursor 中选择操作消息字符串。该字符串会被添加到系统传递给可搜索 activity 的 intent（使用您为建议定义的操作）。如需检查该字符串，请使用 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>