搜索配置

要使用 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 的字符串格式化为“搜索 <content-or-product>”。例如，“搜索歌曲和艺术家”或“搜索 YouTube”。

android:searchMode

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

值	描述
`"queryRewriteFromData"`	使用来自 `SUGGEST_COLUMN_INTENT_DATA` 列的值重写查询文本。这仅在 `SUGGEST_COLUMN_INTENT_DATA` 中的值适合用户检查和编辑时（例如 HTTP URI）才使用。
`"queryRewriteFromText"`	使用来自 `SUGGEST_COLUMN_TEXT_1` 列的值重写查询文本。

有关更多信息，请参阅添加自定义搜索建议中关于重写查询文本的文档。

android:searchButtonText

字符串资源。在执行搜索的按钮中显示的文本。默认情况下，该按钮显示一个搜索图标（放大镜），这非常适合国际化。因此，除非行为不是搜索，例如 Web 浏览器中的 URL 请求，否则不要使用此属性更改按钮。

android:inputType

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

android:imeOptions

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

搜索建议属性

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

android:searchSuggestAuthority: 字符串。（提供搜索建议所需。）此值必须与 Android 清单 <provider> 元素的 android:authorities 属性中提供的权限字符串匹配。
android:searchSuggestPath: 字符串。此路径用作建议查询 Uri 的一部分，位于前缀和权限之后，标准建议路径之前。仅当您有一个发出不同类型建议（例如，针对不同数据类型）的内容提供程序，并且您需要一种方法在收到建议查询时消除歧义时，才需要此功能。
android:searchSuggestSelection: 字符串。此值作为 selection 参数传递到您的查询函数中。通常，这是数据库的 WHERE 子句，并且必须包含一个问号作为用户输入的实际查询字符串的占位符，例如 "query=?"。但是，您也可以使用任何非空值来触发使用 selectionArgs 参数传递查询文本，然后忽略 selection 参数）。
android:searchSuggestIntentAction: 字符串。用户点击自定义搜索建议时要使用的默认意图操作，例如 "android.intent.action.VIEW"。如果此值未被选定的建议使用 SUGGEST_COLUMN_INTENT_ACTION 列覆盖，则当用户点击建议时，该值将放置在 Intent 的 action 字段中。
android:searchSuggestIntentData: 字符串。用户点击自定义搜索建议时要使用的默认意图数据。如果未被选定的建议（通过 SUGGEST_COLUMN_INTENT_DATA 列）覆盖，则当用户点击建议时，此值将放置在 Intent 的 data 字段中。
android:searchSuggestThreshold: 整数。触发建议查找所需的最小字符数。这仅保证系统不会查询您的内容提供程序以获取短于阈值的任何内容。默认值为 0。

有关上述搜索建议属性的更多信息，请参阅添加自定义搜索建议和添加自定义建议的文档。

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

android:includeInGlobalSearch: 布尔值。（在快速搜索框中提供搜索建议所需。）如果希望您的建议包含在全局可访问的快速搜索框中，请将其设置为 "true"。用户必须仍在系统搜索设置中启用您的应用程序作为可搜索项目，然后您的建议才会出现在快速搜索框中。
android:searchSettingsDescription: 字符串资源。提供您提供给快速搜索框的搜索建议的简要说明，该说明显示在您的应用程序的可搜索项目条目中。您的描述必须简洁地描述可搜索的内容。例如，音乐应用程序的“艺术家、专辑和曲目”，或记事本应用程序的“保存的笔记”。
android:queryAfterZeroResults: 布尔值。如果希望您的内容提供程序被调用以获取先前返回零结果的查询的超集，请将其设置为 "true"。例如，如果您的内容提供程序针对“bo”返回零结果，则必须针对“bob”重新查询它。如果设置为 "false"，则在单个会话中会忽略超集 - “bob”不会调用重新查询。这仅在搜索对话框的生存期内或使用搜索窗口小部件时活动的生存期内有效。重新打开搜索对话框或活动时，“bo”会再次查询您的内容提供程序。默认值为 false。

语音搜索属性

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

android:voiceSearchMode

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

值	描述
`"showVoiceSearchButton"`	如果设备上可用，则显示语音搜索按钮。如果设置，则还必须设置 `"launchWebSearch"` 或 `"launchRecognizer"`，并用管道 (`\|`) 字符分隔。
`"launchWebSearch"`	语音搜索按钮会将用户直接带到内置的语音网页搜索活动。大多数应用程序都不会使用此标志，因为它会将用户从调用搜索的活动中带走。
`"launchRecognizer"`	语音搜索按钮会将用户直接带到内置的语音录制活动。此活动会提示用户说话，转录口语文本，并将生成的查询文本转发到可搜索活动，就像用户在搜索 UI 中输入文本并点击搜索按钮一样。

android:voiceLanguageModel

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

值	描述
`"free_form"`	使用自由格式语音识别来听写查询。这主要针对英语进行了优化。这是默认值。
`"web_search"`	使用网页搜索词识别来识别更短的类似搜索的短语。这在比 `"free_form"` 更多的语言中可用。

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

android:voicePromptText

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

android:voiceLanguage

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

android:voiceMaxResults

整数。设置要返回的结果最大数量，包括始终作为 ACTION_SEARCH 意图的主要查询提供的“最佳”结果。必须为 1 或更大。使用 EXTRA_RESULTS 从意图获取结果。如果未提供，识别器将选择要返回的结果数量。

<actionkey>

定义设备按键和搜索操作的行为。搜索操作在设备上点击按钮时提供特殊行为，基于当前查询或聚焦的建议。例如，通讯录应用程序提供了一个搜索操作，在点击“呼叫”按钮时启动对当前聚焦的联系人建议的电话呼叫。

并非所有操作键在所有设备上都可用，并且并非所有键都可以通过这种方式覆盖。例如，“主页”键无法覆盖，并且必须始终返回到主屏幕。此外，请确保不要为需要键入搜索查询的键定义操作键。这将可用的和合理的动作键限制为呼叫按钮和菜单按钮。

必须定义 android:keycode 以定义键，并至少定义其他三个属性之一以定义搜索操作。

属性

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>

搜索配置

搜索建议属性

快速搜索框属性

语音搜索属性