创建搜索界面

当您准备好向您的应用添加搜索功能时，Android 可以帮助您使用出现在活动窗口顶部的搜索对话框或您可以插入布局中的搜索小部件来实现用户界面。搜索对话框和小部件都可以将用户的搜索查询传递到您应用中的特定活动。这样，用户可以从任何提供搜索对话框或小部件的活动启动搜索，系统会启动相应的活动来执行搜索并显示结果。

搜索对话框和小部件的其他可用功能包括：

  • 语音搜索
  • 基于最近查询的搜索建议
  • 与您应用数据中的实际结果匹配的搜索建议

本文档展示了如何设置您的应用以提供由 Android 系统辅助的搜索界面来传递搜索查询，可以使用搜索对话框或搜索小部件。

相关资源

基础知识

在开始之前，请确定您是想使用搜索对话框还是搜索小部件来实现搜索界面。它们提供相同的搜索功能，但方式略有不同。

  • **搜索对话框**是由 Android 系统控制的 UI 组件。当用户激活时，搜索对话框会出现在活动的顶部。

    Android 系统控制搜索对话框中的所有事件。当用户提交查询时，系统会将查询传递到您指定用于处理搜索的活动。在用户键入时，对话框还可以提供搜索建议。

  • **搜索小部件**是您可以放置在布局中任何位置的 SearchView 实例。默认情况下，搜索小部件的行为类似于标准的 EditText 小部件，并且不执行任何操作，但是您可以对其进行配置，以便 Android 系统处理所有输入事件，将查询传递到相应的活动，并提供搜索建议——就像搜索对话框一样。

当用户从搜索对话框或搜索小部件执行搜索时，系统会创建一个 Intent 并将用户查询存储在其中。然后，系统启动您声明用于处理搜索的活动——“可搜索活动”——并将其传递给它。要为这种辅助搜索设置您的应用，您需要以下内容：

  • 搜索配置
    配置搜索对话框或小部件某些设置的 XML 文件。它包括语音搜索、搜索建议和搜索框提示文本等功能的设置。
  • 可搜索活动
    接收搜索查询、搜索您的数据并显示搜索结果的 Activity。
  • 由以下任一提供的搜索界面：
    • 搜索对话框
      默认情况下，搜索对话框是隐藏的。当用户点击您的**搜索**按钮时，调用 onSearchRequested() 时，它会出现在屏幕顶部。
    • 一个 SearchView 小部件
      使用搜索小部件可以让您将搜索框放在活动的任何位置，包括应用栏中的操作视图。

本文档的其余部分将向您展示如何创建搜索配置和可搜索活动，以及如何使用搜索对话框或搜索小部件实现搜索界面。

创建可搜索配置

您首先需要一个名为 搜索配置 的 XML 文件。它配置搜索对话框或小部件的某些 UI 方面，并定义语音搜索和搜索建议等功能的行为。此文件传统上命名为 searchable.xml，必须保存在 res/xml/ 项目目录中。

搜索配置文件必须包含 <searchable> 元素作为其根节点，并指定一个或多个属性，如下例所示：

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint" >
</searchable>

android:label 属性是唯一必需的属性。它指向一个字符串资源，该资源必须是应用名称。此标签在您为快速搜索框启用搜索建议之前对用户不可见，此时该标签在系统设置中的“可搜索项目”列表中可见。

虽然不是必需的，但我们建议您始终包含 android:hint 属性，该属性在用户输入查询之前在搜索框中提供提示字符串。提示很重要，因为它为用户提供了关于他们可以搜索什么的重要的线索。

<searchable> 元素接受其他几个属性。但是，在您添加诸如 搜索建议 和 语音搜索 等功能之前，您不需要大多数属性。有关搜索配置文件的详细信息，请参阅 搜索配置 参考文档。

创建可搜索活动

可搜索活动是您应用中根据查询字符串执行搜索并显示搜索结果的 Activity。

当用户在搜索对话框或小部件中执行搜索时，系统会启动您的可搜索活动，并通过带有 Intent 的 ACTION_SEARCH 操作将搜索查询传递给它。您的可搜索活动从 intent 的 QUERY 附加信息中检索查询，然后搜索您的数据并显示结果。

因为您可以在应用程序中的任何其他活动中包含搜索对话框或小部件，所以系统必须知道哪个活动是您的可搜索活动，以便它能够正确地传递搜索查询。因此，首先在 Android 清单文件中声明您的可搜索活动。

声明可搜索活动

如果您还没有，请创建一个执行搜索并显示结果的 Activity。您现在不需要实现搜索功能——只需创建一个可以在清单中声明的活动。在清单的 <activity> 元素内，执行以下操作：

  1. 在 <intent-filter> 元素中声明活动以接受 ACTION_SEARCH intent。
  2. 在 <meta-data> 元素中指定要使用的搜索配置。

以下示例显示了这一点：

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

<meta-data> 元素必须包含值为 "android.app.searchable" 的 android:name 属性和一个指向可搜索配置文件的引用的 android:resource 属性。在前面的示例中，它指的是 res/xml/searchable.xml 文件。

执行搜索

在清单中声明您的可搜索活动后，请按照此过程在您的可搜索活动中执行搜索：

  1. 接收查询.
  2. 搜索您的数据.
  3. 显示结果.

接收查询

当用户从搜索对话框或小部件执行搜索时，系统会启动您的可搜索活动并向其发送 ACTION_SEARCH intent。此 intent 在 QUERY 字符串附加信息中携带搜索查询。在活动启动时检查此 intent 并提取字符串。例如，以下是如何在您的可搜索活动启动时获取搜索查询：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

QUERY 字符串始终包含在 ACTION_SEARCH intent 中。在前面的示例中，查询被检索并传递到一个本地 doMySearch() 方法，其中执行实际的搜索操作。

搜索您的数据

存储和搜索数据的过程是您应用程序特有的。您可以通过多种方式存储和搜索数据，本文档不会向您展示如何操作。请根据您的需求和数据格式考虑如何存储和搜索您的数据。以下是一些您可以应用的技巧：

  • 如果您的数据存储在设备上的 SQLite 数据库中，则执行全文搜索（使用 FTS3，而不是 LIKE 查询）可以提供更强大的文本数据搜索，并且可以显著加快结果速度。有关 FTS3 的信息，请参阅 sqlite.org；有关 Android 上 SQLite 的信息，请参阅 SQLiteDatabase 类。
  • 如果您的数据存储在线上，则用户的网络连接可能会影响感知到的搜索性能。您可能需要显示进度指示器，直到搜索返回结果。有关网络 API 的参考，请参阅 android.net；有关如何显示进度指示器的信息，请参阅 ProgressBar。

显示结果

无论您的数据存储在哪里以及如何搜索它，我们都建议您使用 Adapter 将搜索结果返回到您的可搜索活动。这样，您就可以在 RecyclerView 中显示所有搜索结果。如果您的数据来自 SQLite 数据库查询，则可以使用 CursorAdapter 将结果应用于 RecyclerView。如果您的数据采用不同的格式，则可以创建 BaseAdapter 的扩展。

Adapter 将一组数据中的每个项目绑定到 View 对象。当 Adapter 应用于 RecyclerView 时，每个数据片段都作为单个视图插入到列表中。Adapter 只是一个接口，因此需要诸如 CursorAdapter（用于绑定来自 Cursor 的数据）之类的实现。如果现有的实现都不适合您的数据，则可以从 BaseAdapter 实现自己的实现。

使用搜索对话框

搜索对话框在屏幕顶部提供一个浮动搜索框，左侧显示应用程序图标。搜索对话框可以在用户键入时提供搜索建议。当用户执行搜索时，系统会将搜索查询发送到执行搜索的可搜索活动。

默认情况下，搜索对话框始终隐藏，直到用户激活它为止。您的应用程序可以通过调用 onSearchRequested() 来激活搜索对话框。但是，此方法只有在您为活动启用搜索对话框后才能起作用。

要启用搜索对话框以执行搜索，请向系统指示哪个可搜索活动必须接收来自搜索对话框的搜索查询。例如，在前面关于 创建可搜索活动 的部分中，创建了一个名为 SearchableActivity 的可搜索活动。如果您希望另一个活动（例如名为 OtherActivity 的活动）显示搜索对话框并将搜索传递给 SearchableActivity，请在清单中声明 SearchableActivity 是要在 OtherActivity 中用于搜索对话框的可搜索活动。

要声明活动搜索对话框的可搜索活动，请在相应活动的 <activity> 元素内添加 <meta-data> 元素。<meta-data> 元素必须包含指定可搜索活动类名的 android:value 属性和值为 "android.app.default_searchable" 的 android:name 属性。

例如，以下是可搜索活动 SearchableActivity 和另一个活动 OtherActivity 的声明，后者使用 SearchableActivity 执行从其搜索对话框执行的搜索：

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

由于 OtherActivity 现在包含一个 <meta-data> 元素来声明要用于搜索的可搜索活动，因此该活动启用了搜索对话框。尽管用户在此活动中，但 onSearchRequested() 方法会激活搜索对话框。当用户执行搜索时，系统会启动 SearchableActivity 并向其传递 ACTION_SEARCH intent。

如果您希望应用程序中的每个活动都提供搜索对话框，请将前面的 <meta-data> 元素作为 <application> 元素的子元素插入，而不是每个 <activity> 元素。这样，每个活动都会继承该值，提供搜索对话框，并将搜索传递给同一个可搜索活动。如果您有多个可搜索活动，则可以通过在各个活动中放置不同的 <meta-data> 声明来覆盖默认的可搜索活动。

现在已为您的活动启用搜索对话框，您的应用程序已准备好执行搜索。

调用搜索对话框

虽然某些设备提供专用搜索按钮，但按钮的行为可能因设备而异，并且许多设备根本不提供搜索按钮。因此，在使用搜索对话框时，您必须在 UI 中提供一个搜索按钮，该按钮通过调用 onSearchRequested() 来激活搜索对话框。

例如，在您的 选项菜单 或 UI 布局中添加一个调用 onSearchRequested() 的搜索按钮。

您还可以启用“键入以搜索”功能，该功能在用户开始在键盘上键入时激活搜索对话框。击键将插入到搜索对话框中。您可以通过在活动的 onCreate() 方法期间调用 setDefaultKeyMode（或 DEFAULT_KEYS_SEARCH_LOCAL）来启用键入以搜索。

搜索对话框对您的活动生命周期的影响

搜索对话框是一个在屏幕顶部浮动的 Dialog。它不会导致活动堆栈发生任何更改，因此当搜索对话框出现时，不会调用任何生命周期方法（例如 onPause()）。您的活动会失去输入焦点，因为输入焦点会赋予搜索对话框。

如果您想在激活搜索对话框时收到通知，请重写 onSearchRequested() 方法。当系统调用此方法时，它表示您的活动将输入焦点丢失给搜索对话框，因此您可以执行适合该事件的任何工作，例如暂停游戏。除非您正在 传递搜索上下文数据（在本文档的另一部分中讨论），否则请通过调用超类实现来结束该方法。

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

如果用户点击后退按钮取消搜索，搜索对话框将关闭，并且活动将重新获得输入焦点。您可以注册以在搜索对话框关闭时收到通知，方法是使用setOnDismissListener()、setOnCancelListener()或两者兼用。您只需要注册OnDismissListener，因为它在每次搜索对话框关闭时都会被调用。OnCancelListener仅与用户显式退出搜索对话框的事件相关，因此在执行搜索时不会被调用。搜索执行后，搜索对话框会自动消失。

如果当前活动不是可搜索活动，则当用户执行搜索时，将触发正常的活动生命周期事件——当前活动将收到onPause()，如活动简介中所述。但是，如果当前活动是可搜索活动，则会发生以下两种情况之一：

  • 默认情况下，可搜索活动将通过调用onCreate()接收ACTION_SEARCH意图，并且活动的新实例将被置于活动堆栈的顶部。现在活动堆栈中有两个可搜索活动的实例，因此点击后退按钮将返回到可搜索活动的先前实例，而不是退出可搜索活动。
  • 如果将android:launchMode设置为"singleTop"，则可搜索活动将通过调用onNewIntent(Intent)接收ACTION_SEARCH意图，并传递新的ACTION_SEARCH意图。例如，以下是处理这种情况的方法，其中可搜索活动的启动模式为"singleTop"

    Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)
    handleIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    setIntent(intent)
    handleIntent(intent)
}

private fun handleIntent(intent: Intent) {
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

    Java

    @Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);
    handleIntent(getIntent());
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    handleIntent(intent);
}

private void handleIntent(Intent intent) {
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

    与关于执行搜索部分中的示例代码相比，处理搜索意图的所有代码现在都在handleIntent()方法中，以便onCreate()和onNewIntent()都可以执行它。

    当系统调用onNewIntent(Intent)时，活动不会重新启动，因此getIntent()方法返回与onCreate()一起接收的相同意图。这就是为什么必须在onNewIntent(Intent)内调用setIntent(Intent)：以便在将来调用getIntent()时更新活动保存的意图。

第二种方案（使用"singleTop"启动模式）通常更可取，因为在搜索完成之后，用户可能会执行其他搜索，而您不希望您的应用程序创建可搜索活动的多个实例。我们建议您在应用程序清单中将可搜索活动的启动模式设置为"singleTop"，如下例所示：

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

传递搜索上下文数据

在某些情况下，您可以针对每次进行的搜索，在可搜索活动中对搜索查询进行必要的细化。但是，如果您想根据用户执行搜索的活动来细化搜索条件，则可以在系统发送到可搜索活动的意图中提供其他数据。您可以将附加数据传递到APP_DATA Bundle中，该Bundle包含在ACTION_SEARCH意图中。

要将此类数据传递到可搜索活动，请覆盖用户可以从中执行搜索的活动的onSearchRequested()方法，创建一个包含附加数据的Bundle，并调用startSearch()以激活搜索对话框。例如：

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

返回true表示您已成功处理此回调事件并调用startSearch()以激活搜索对话框。用户提交查询后，它将与您添加的数据一起传递到您的可搜索活动。您可以从APP_DATA Bundle中提取额外数据以细化搜索，如下例所示：

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

使用搜索小部件

An image showing a search view in the app top bar

图1. SearchView小部件作为应用栏中的操作视图。

搜索小部件提供与搜索对话框相同的功能。当用户执行搜索时，它会启动相应的活动，并且它可以提供搜索建议和执行语音搜索。如果您无法将搜索小部件放在应用栏中，则可以将其放在活动的布局中的其他位置。

配置搜索小部件

创建搜索配置和可搜索活动后，通过调用setSearchableInfo()并向其传递表示可搜索配置的SearchableInfo对象，为每个SearchView启用辅助搜索。

您可以通过在SearchManager上调用getSearchableInfo()来获取对SearchableInfo的引用。

例如，如果您在应用栏中使用SearchView作为操作视图，请在onCreateOptionsMenu()回调期间启用该小部件，如下例所示：

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

现在搜索小部件已配置完成，系统会将搜索查询传递到您的可搜索活动。您还可以为搜索小部件启用搜索建议。

有关应用栏中操作视图的更多信息，请参阅使用操作视图和操作提供程序。

其他搜索小部件功能

SearchView小部件提供了一些您可能需要的其他功能：

提交按钮
默认情况下，没有提交搜索查询的按钮，因此用户必须按下键盘上的Return键才能启动搜索。您可以通过调用setSubmitButtonEnabled(true)来添加“提交”按钮。
搜索建议的查询细化
启用搜索建议时，您通常希望用户选择建议，但他们也可能希望细化建议的搜索查询。您可以通过调用setQueryRefinementEnabled(true)，在每个建议旁边添加一个按钮，该按钮将建议插入搜索框中，以便用户进行细化。
切换搜索框可见性的能力
默认情况下，搜索小部件是“图标化”的，这意味着它仅由搜索图标（放大镜）表示。当用户点击图标时，它会展开以显示搜索框。如前面的示例所示，您可以通过调用setIconifiedByDefault(false)来默认显示搜索框。您还可以通过调用setIconified()来切换搜索小部件的外观。

SearchView类中还有其他几个API可以让您自定义搜索小部件。但是，大多数 API 仅在您自己处理所有用户输入时才使用，而不是使用 Android 系统来传递搜索查询和显示搜索建议。

同时使用小部件和对话框

如果您将搜索小部件作为操作视图插入应用栏，并启用它在有空间时显示在应用栏中（通过设置android:showAsAction="ifRoom"），则搜索小部件可能不会显示为操作视图。相反，菜单项可能会出现在溢出菜单中。例如，当您的应用在较小的屏幕上运行时，应用栏中可能没有足够的空间来显示搜索小部件以及其他操作项或导航元素，因此菜单项将出现在溢出菜单中。当放置在溢出菜单中时，该项的工作方式类似于普通的菜单项，并且不显示操作视图，即搜索小部件。

为了处理这种情况，当用户从溢出菜单中选择“搜索”菜单项时，附加搜索小部件的菜单项必须激活搜索对话框。为此，请实现onOptionsItemSelected()以处理“搜索”菜单项，并通过调用onSearchRequested()打开搜索对话框。

有关应用栏中项目的工作方式以及如何处理这种情况的更多信息，请参阅添加应用栏。

添加语音搜索

您可以通过在可搜索配置中添加android:voiceSearchMode属性，为您的搜索对话框或窗口小部件添加语音搜索功能。这会添加一个语音搜索按钮，启动语音提示。用户说完话后，转录的搜索查询将发送到您的可搜索活动。

以下示例显示了这一点：

<?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:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

值为showVoiceSearchButton是启用语音搜索的必要条件。第二个值launchRecognizer指定语音搜索按钮必须启动一个返回转录文本到可搜索活动的 *识别器*。

您可以提供其他属性来指定语音搜索行为，例如预期的语言和要返回的最大结果数。有关可用属性的更多信息，请参阅搜索配置 参考。

添加搜索建议

搜索对话框和搜索窗口小部件都可以在用户键入时提供搜索建议，并借助 Android 系统。系统管理建议列表并处理用户选择建议时的事件。

您可以提供两种搜索建议

最近查询搜索建议
这些建议是用户以前在您的应用中用作搜索查询的词语。有关更多信息，请参阅添加自定义搜索建议。
自定义搜索建议
这些是您从自己的数据源提供的搜索建议，以帮助用户立即选择正确的拼写或他们正在搜索的项目。有关更多信息，请参阅添加自定义搜索建议。