搜索配置

如需在 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

搜索建议属性

如果您定义 content provider 以生成搜索建议,则需要定义其他属性来配置与 content provider 的通信。提供搜索建议时,您需要以下某些 <searchable> 属性:


android:searchSuggestAuthority
字符串。(提供搜索建议所必需的属性。)此值必须与 Android 清单 <provider> 元素的 android:authorities 属性中提供的授权方字符串匹配。
android:searchSuggestPath
字符串。此路径用作建议查询 Uri 的一部分,在前缀和授权方之后、标准建议路径之前。仅在以下情况下才需要此属性:单个 content provider 发出不同类型的建议(例如针对不同的数据类型),并且您需要在收到建议查询时消除这些查询的歧义。
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
整数。触发建议查询所需的最少字符数。这只能保证系统不会向 content provider 查询短于阈值的任何内容。默认值为 0。

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

快速搜索框属性

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


android:includeInGlobalSearch
布尔值。(在快速搜索框中提供搜索建议所必需的属性。)如果要将您的建议包含在可全局访问的快速搜索框中,请设置为 "true"。用户仍必须在系统搜索设置中将您的应用作为可搜索项启用,然后您的建议才会显示在快速搜索框中。
android:searchSettingsDescription
字符串资源。提供您向快速搜索框提供的搜索建议的简要说明,说明会显示在您应用的可搜索项条目中。说明必须简明扼要地描述可搜索的内容。例如,音乐应用的说明为“音乐人、专辑和曲目”,记事本应用的说明为“保存的记事”。
android:queryAfterZeroResults
布尔值。如果要为之前未返回任何结果的查询的超集调用 content provider,请将此属性设为 "true"。例如,如果 content provider 未针对“bo”返回任何结果,则必须针对“bob”重新查询该结果。如果设置为 "false",则系统会针对单个会话忽略超集,即“bob”不会调用重新查询。它仅在搜索对话框的生命周期内或使用搜索 widget 时的 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
字符串。content provider 中用于定义此操作键的操作消息的列的名称,当用户在建议获得焦点时按操作键时,系统就会发送该消息。通过此属性,您可以按建议控制操作键,因为 content provider 中的每个条目都提供自己的操作消息,而不是使用 android:suggestActionMsg 属性为所有建议定义操作消息。

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