此页面由 Cloud Translation API 翻译。

搜索配置

在 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

字符串资源。（必需）。您的应用的名称。该名称必须与应用于应用的 android:label 属性的名称， <activity> 或 <application> 清单元素。只有当您设置了 android:includeInGlobalSearch 到 "true"，在这种情况下，使用此标签在系统搜索设置中将您的应用标识为可搜索项。

android:hint

字符串资源。（建议）。当搜索文字字段出现时，未输入任何文字。它可向用户提供关于哪些内容可搜索的提示。保持一致性对于其他 Android 应用，请将 android:hint 的字符串的格式设置为“Search <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 获取适合该属性的值的列表。

搜索建议属性

如果您要定义一个 content provider 来生成搜索建议，则需要定义用于配置与 content provider 的通信的其他属性。提供搜索功能时您需要以下某些 <searchable> 属性：

android:searchSuggestAuthority: 字符串。（提供搜索建议所必需的属性）。该值必须与 android:authorities 中提供的授权方字符串属性。<provider>
android:searchSuggestPath: 字符串。此路径用作建议的一部分在前缀后面加上“Uri” 并放在标准建议路径之前只有当您拥有一个内容提供程序发出不同类型的建议，例如针对不同的因此，您需要在收到查询时，。
android:searchSuggestSelection: 字符串。该值会传递到查询函数作为 selection 参数。这通常是一个 WHERE 子句并且必须包含一个问号，作为用户输入的实际查询字符串，例如 "query=?"。不过，您还可以使用任何非 null 值，通过 selectionArgs 参数，然后忽略 selection 参数）。
android:searchSuggestIntentAction: 字符串。用户点按自定义搜索建议（例如 "android.intent.action.VIEW"）。如果该值未被所选建议替换，请使用 SUGGEST_COLUMN_INTENT_ACTION 列中，该值会放置在当用户点按时 Intent 提供建议。
android:searchSuggestIntentData: 字符串。用户。如果未覆盖所选建议，则使用 SUGGEST_COLUMN_INTENT_DATA 列—该值放置在当用户点按时 Intent 提供建议。
android:searchSuggestThreshold: 整数。输入所需的最少字符数触发查找建议。这只能保证系统不会查询您的内容提供程序。默认值为 0。

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

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

android:includeInGlobalSearch: 布尔值。（在快速搜索框。）如果您想让系统显示建议，请将此项设为 "true" 。用户必须在系统搜索设置中将您的应用作为可搜索项启用，您的建议会显示在快速搜索框中。
android:searchSettingsDescription: 字符串资源。简要说明快速搜索框会显示在您的应用。说明必须简明扼要地描述可供搜索的内容。对于例如，“音乐人、专辑和曲目”或“已保存的记事”针对记事本应用程序。
android:queryAfterZeroResults: 布尔值。如果您要将内容提供方设为 "true"，请将为先前返回零结果的查询的超集调用。例如，如果对于“bob”，您的内容提供程序会返回零个结果，必须查询“bob”。如果设为 "false"，系统会忽略单个会话“bob”的超集不会调用重新查询。此设置仅在搜索对话框的生命周期或使用搜索微件时，与 Activity 相关联。重新打开搜索对话框或 activity 时， “bo”再次查询内容提供程序默认值为 false。

语音搜索属性

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

android:voiceSearchMode

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

值	说明
`"showVoiceSearchButton"`	如果可在设备上使用语音搜索，则显示语音搜索按钮。如果已设置，则还必须设置 `"launchWebSearch"` 或 `"launchRecognizer"`。使用竖线 (`\|`) 字符分隔。
`"launchWebSearch"`	语音搜索按钮可将用户直接转到。大多数应用都不会使用此标记，因为它会让用户离开调用搜索的 activity。
`"launchRecognizer"`	使用语音搜索按钮时，将用户直接转到内置的录音 activity。此活动提示用户说话、转录所说的文字，然后将生成的译文将查询文本添加到可搜索 Activity，就好像用户在搜索界面并点按搜索按钮。

android:voiceLanguageModel

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

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

请参阅 EXTRA_LANGUAGE_MODEL了解详情信息。

android:voicePromptText

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

android:voiceLanguage

字符串。预期的母语，表示为 Locale 中的一个常量，例如 "de" 表示德语，"fr" 表示法语。仅当与当前 ID 值的 ID 不同时，才需要指定此字段 Locale.getDefault() 的当前值。

android:voiceMaxResults

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

<actionkey>

定义搜索操作的设备键和行为。搜索操作提供了一种特殊的点按设备上的按钮时的行为（基于当前查询或聚焦的行为）建议。例如，“通讯录”应用提供用于发起通话的搜索操作当用户点按“呼叫”按钮时，呼叫当前聚焦的联系人建议。

并非所有操作键都适用于所有设备，也并非所有操作键都可在。例如，“首页”且必须始终返回主屏幕屏幕。此外，切勿为输入搜索内容所需的键定义操作键查询。这会将可用且合理的操作键限制为通话按钮和菜单按钮。

您必须定义 android:keycode 才能定义键和至少一个其他三个属性来定义搜索操作

属性：

android:keycode: 字符串。（必需）。来自 KeyEvent，表示您要响应的操作键（例如 "KEYCODE_CALL"）。这个会添加到 ACTION_SEARCH 传递给可搜索 activity 的 intent。要检查该键码，请使用 getIntExtra(SearchManager.ACTION_KEY)。搜索操作并不支持所有键，因为很多键用于输入内容，导航或系统功能。
android:queryActionMsg: 字符串。按下操作键后要发送的操作消息用户输入查询文本。该 ID 会添加到 ACTION_SEARCH intent。要检查该字符串，请使用 getStringExtra(SearchManager.ACTION_MSG)。
android:suggestActionMsg: 字符串。在获得焦点。这会添加到系统传递给您的可搜索 activity - 使用您为建议定义的操作。要检查字符串，使用 getStringExtra(SearchManager.ACTION_MSG)。仅当您的所有建议都支持此操作键时，才需要使用此选项。如果不是全部建议可以处理相同的操作键，那么您必须改用以下 android:suggestActionMsgColumn 属性。
android:suggestActionMsgColumn: 字符串。内容提供程序中用于定义此操作键的操作消息，将在用户按下操作键时发送。通过此属性，您可以控制而不是使用 android:suggestActionMsg 属性，用于定义所有操作消息内容提供程序中的每个条目都会提供自己的操作消息。
首先，您必须在 content provider 中定义一列，以便提供每条建议的操作消息，然后在此属性中提供该列的名称。系统看着您的建议游标，并使用此处提供的字符串选择您的操作 message 列，然后从光标中选择操作消息字符串。该字符串是添加到系统传递给可搜索 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>

搜索配置

搜索建议属性

快速搜索框属性

语音搜索属性