搜索

为什么搜索不只是"一个输入框"？

你用手机 App 时几乎每天都在用它：微信搜聊天记录、设置里搜 Wi-Fi、地图搜地址。看起来只是一个输入框，但背后的用户期待远超一个普通的输入框——它应该在应用栏的位置、有语音输入按钮、输入时弹出历史建议、点击搜索后键盘自动收起且显示结果。

如果不用专门为搜索设计的控件，这些效果你都得自己造轮子：监听输入变化、维护历史列表、弹出建议弹窗、处理键盘收起……这就是为什么 Android 提供了一个完整的搜索框架——SearchView、SearchManager、建议提供器三者配合，把上面这些需求包装成一套开箱即用的方案。

这章要解决的核心问题：怎么给你的 App 加一个专业级的搜索功能，而不是只扔一个 EditText 了事。

SearchView 与搜索框架

SearchView：应用栏里的专业搜索框

是 Android 为搜索场景深度定制的一个控件。它比普通 EditText 多了这些能力：

• 搜索建议下拉列表（自动弹出、自动消失）
• 语音搜索按钮（如果你的设备支持）
• 与键盘的自动配合（提交后收起，不影响返回栈）
• 可配置的外观（图标化/展开、提示文字、搜索图标）

searchable.xml：搜索配置宣言

Android 的搜索框架通过一个 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/app_name"
    android:hint="搜索联系人..."
    android:searchSuggestAuthority="com.example.app.SearchSuggestionProvider"
    android:searchSuggestSelection=" ?" />

这个文件告诉系统：这个 App 支持搜索、搜索建议由哪个 ContentProvider 提供、提示文字是什么。

处理搜索查询：onQueryTextSubmit

SearchView 通过 OnQueryTextListener 回调通知你搜索事件：

searchView.setOnQueryTextListener(object : SearchView.OnQueryTextListener {
    override fun onQueryTextSubmit(query: String?): Boolean {
        // 用户按下"搜索"按钮（键盘上的回车或放大镜图标）
        performSearch(query ?: "")
        return true
    }
 
    override fun onQueryTextChange(newText: String?): Boolean {
        // 用户每输入一个字符就回调一次——适合做即时过滤
        filterData(newText ?: "")
        return true
    }
})

onQueryTextSubmit 只在用户确认搜索时触发一次。onQueryTextChange 每次输入变化都触发——如果你的数据集很大，不要在这里做全量查询。

代码逐段拆解：完整的搜索功能

第一步：在菜单中放置 SearchView

<!-- res/menu/fragment_main.xml -->
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item
        android:id="@+id/menu_item_search"
        android:title="搜索"
        app:actionViewClass="android.widget.SearchView"
        app:showAsAction="ifRoom|collapseActionView" />
</menu>

app:actionViewClass="android.widget.SearchView" 是关键——它告诉系统这个菜单项不是一个普通按钮，而是展开为一个 SearchView 控件。

第二步：在代码中获取并配置 SearchView

override fun onCreateOptionsMenu(menu: Menu, inflater: MenuInflater) {
    super.onCreateOptionsMenu(menu, inflater)
    inflater.inflate(R.menu.fragment_main, menu)
 
    val searchItem = menu.findItem(R.id.menu_item_search)
    val searchView = searchItem.actionView as SearchView
 
    searchView.apply {
        queryHint = "搜索联系人..."
        setOnQueryTextListener(object : SearchView.OnQueryTextListener {
            override fun onQueryTextSubmit(query: String?): Boolean {
                query?.let { performSearch(it) }
                return true
            }
            override fun onQueryTextChange(newText: String?): Boolean {
                newText?.let { filterList(it) }
                return true
            }
        })
    }
}

第三步：用 SharedPreferences 保存搜索历史

class SearchHistoryManager(context: Context) {
    private val prefs = context.getSharedPreferences("search_history", Context.MODE_PRIVATE)
    private val maxHistory = 10
 
    fun addQuery(query: String) {
        val currentList = getHistory().toMutableList()
        currentList.remove(query)  // 去重：已存在的先删掉
        currentList.add(0, query)  // 最新的放最前面
        if (currentList.size > maxHistory) {
            currentList.removeAt(currentList.lastIndex)
        }
        // 序列化为 JSON 字符串存入 SharedPreferences
        prefs.edit().putString(KEY_HISTORY, Gson().toJson(currentList)).apply()
    }
 
    fun getHistory(): List<String> {
        val json = prefs.getString(KEY_HISTORY, "[]") ?: "[]"
        val type = object : TypeToken<List<String>>() {}.type
        return Gson().fromJson(json, type)
    }
 
    companion object {
        private const val KEY_HISTORY = "queries"
    }
}

搜索历史的本质：一个去重 + 限制条数 + 按时间排序的列表，用 SharedPreferences 持久化。Gson 做序列化比手动拼接分隔符更可靠——你不会被用户输入的逗号或换行符搞崩解析逻辑。

容易踩的坑

小结

• SearchView 是 Android 为搜索定制的控件，通过菜单配置 app:actionViewClass 集成到应用栏
• searchable.xml 声明搜索元数据（提示文字、建议提供器），OnQueryTextListener 处理查询提交和输入变化
• 搜索建议通过 ContentProvider 提供，SearchRecentSuggestionsProvider 可快速实现最近搜索记录
• SharedPreferences + Gson 序列化是一种轻量级的搜索历史存储方案——去重 + 限制条数 + 时间排序
• onQueryTextChange 回调频率极高，需要防抖或异步处理避免阻塞主线程

名词解释

“搜索”不使用未获授权的纸书正文；InformIT出版信息与授权电子版完整目录只用于确认第四版32章、269个正式目录节点和时代语境，第四版官方勘误用于识别工具链变更。下列中文解释、图示、交互、代码与练习均为独立教学重写，平台行为再以Android Developers的一手文档复核。

为什么“搜索”必须回到可观察状态

“搜索”的学习结果不是记住类名，而是能预测“在 App 中添加搜索功能：使用 SearchView 控件、搜索建议提供器和 SharedPreferences 持久化搜索历史。”在一次输入、一次重建和一次失败中的不同状态，并指出哪条Android合同产生差异。

第四版机制逐项深读

26. SearchView and SharedPreferences

在“搜索”中，“26. SearchView and SharedPreferences”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

Searching Flickr

在“搜索”中，“Searching Flickr”的API密钥与用户数据不得进入仓库或截图；测试使用受控fixture并记录服务合同版本。

Using SearchView

在“搜索”中，“Using SearchView”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

Simple Persistence with SharedPreferences

在“搜索”中，“Simple Persistence with SharedPreferences”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

Polishing Your App

在“搜索”中，“Polishing Your App”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

Editing SharedPreferences with Android KTX

在“搜索”中，“Editing SharedPreferences with Android KTX”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

Challenge: Polishing Your App Some More

在“搜索”中，“Challenge: Polishing Your App Some More”把查询输入、提交事件和轻量偏好持久化分开；防抖、空查询、进程重建与旧响应竞争都要用可重放事件序列验证。

“搜索”验收回顾

“搜索”只有在请求或消息时间线、取消、乱序与失败恢复能够从相同基线再次得到相同断言时才通过；第四版机制与现代平台政策分别记录，不用新API名称掩盖旧行为。

← 上一页：Looper、Handler和HandlerThread · 下一页：WorkManager →

章专属可重放状态实验

先预测“输入、提交、清空、旋转、冷启动和旧响应返回”发生后，查询状态所有者、偏好存储与 PhotoGallery Repository应怎样改变编辑文本、已提交查询、持久偏好、请求 ID 和结果；再操作三个实验。第四版示例与当前 Android 政策分别记录，实验不把新 API 名称倒填为原书内容。

实验一：所有者—状态—结果合同

选择任一正式目录节点和正常/边界场景，检查它是否真的进入本章状态合同。目录标题只有同时出现在解释、可视状态和交付证据中才算覆盖。

实验二：事件与生命周期轨迹

沿五次转换逐步执行“输入、提交、清空、旋转、冷启动和旧响应返回”。每一步只允许查询状态所有者、偏好存储与 PhotoGallery Repository按职责提交状态，并持续核对“轻量偏好只保存已确认查询，当前结果对应最新有效请求”。

实验三：章专属反例与同输入恢复

注入“每个字符都立即写偏好并发请求，旧响应覆盖新输入”，保存第一个偏离点；撤销后以完全相同的 SDK、设备状态和用户事件重放。只有输入事件、提交时刻、preference 值、请求 ID 和结果断言一起恢复才算修复。