搜索配置
通过收藏集保持井井有条 根据你的偏好保存和分类内容。
要借助 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
的字符串格式设置为“搜索 <内容或产品>”。例如,“搜索歌曲和艺术家”或“搜索 YouTube”。
android:searchMode
- 关键字。设置控制搜索界面的其他模式。可用模式定义了当自定义建议获得焦点时,查询文本需要如何重写。接受以下模式值
有关重写查询文本的更多信息,请参阅 添加自定义搜索建议 中的文档。
android:searchButtonText
- 字符串资源。在执行搜索的按钮中显示的文本。默认情况下,按钮显示搜索图标(放大镜),这非常适合国际化。因此,除非行为不是搜索,例如在网页浏览器中请求 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
- 字符串。当用户点击自定义搜索建议时使用的默认 intent 操作,例如
"android.intent.action.VIEW"
。如果选定的建议未使用 SUGGEST_COLUMN_INTENT_ACTION
列覆盖此值,则当用户点击建议时,此值会放置在 Intent
的操作字段中。
android:searchSuggestIntentData
- 字符串。当用户点击自定义搜索建议时使用的默认 intent 数据。如果选定的建议未通过
SUGGEST_COLUMN_INTENT_DATA
列覆盖此值,则当用户点击建议时,此值会放置在 Intent
的数据字段中。
android:searchSuggestThreshold
- 整数。触发建议查找所需的最小字符数。这仅保证系统不会查询你的内容提供程序,以获取短于阈值的任何内容。默认值为 0。
有关上述搜索建议属性的更多信息,请参阅关于 添加自定义搜索建议 和 添加自定义建议 的文档。
Quick Search Box 属性
要使自定义搜索建议可用于 Quick Search Box,你需要以下一些 <searchable>
属性
android:includeInGlobalSearch
- 布尔值。(在 Quick Search Box 中提供搜索建议所必需。)如果你希望将你的建议包含在全局可访问的 Quick Search Box 中,请将其设置为
"true"
。用户仍需要在系统搜索设置中启用你的应用作为可搜索的项目,你的建议才会出现在 Quick Search Box 中。
android:searchSettingsDescription
- 字符串资源。提供你为 Quick Search Box 提供的搜索建议的简要说明,该说明显示在应用的可搜索项目条目中。你的说明必须简洁地描述可搜索的内容。例如,音乐应用为“艺术家、专辑和曲目”,记事本应用为“保存的笔记”。
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>
- 定义搜索操作的设备按键和行为。搜索操作根据当前查询或聚焦的建议,在设备上轻触按钮时提供特殊行为。例如,Contacts 应用提供搜索操作,当轻触通话按钮时,可以向当前聚焦的联系人建议发起通话。
并非所有设备上都提供所有操作键,并且并非所有按键都可以通过这种方式覆盖。例如,“Home”键无法覆盖,必须始终返回主屏幕。此外,请务必不要为输入搜索查询所需的按键定义操作键。这将可用且合理的操作键限制为通话按钮和菜单按钮。
你必须定义 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
属性为所有建议定义操作消息。首先,你必须在内容提供程序中为每个建议定义一个列,以提供操作消息,然后在此属性中提供该列的名称。系统会查看你的建议游标,使用此处提供的字符串选择操作消息列,然后从游标中选择操作消息字符串。该字符串将添加到系统传递给你的可搜索 activity 的 intent 中,使用你为建议定义的操作。要检查字符串,请使用 getStringExtra(SearchManager.ACTION_MSG)
。如果选定的建议没有数据,则忽略该操作键。
- 示例
- XML 文件保存在
res/xml/searchable.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>
本页面上的内容和代码示例受 内容许可 中所述的许可限制。Java 和 OpenJDK 是 Oracle 和/或其关联公司的商标或注册商标。
最后更新时间:世界协调时 2024 年 2 月 22 日。
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂 / 步骤太多","tooComplicatedTooManySteps","thumb-down"],["已过时","outOfDate","thumb-down"],["示例 / 代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间:世界协调时 2024 年 2 月 22 日。"],[],[]]