买家具的时候拍胸脯，记账的时候拍脑袋。我自己的情况是：餐桌、柜子、几把椅子分散在三个电商平台，保修卡可能夹在抽屉，或者早被扔掉。真到了“这把椅子什么时候买的、还能不能保修”的时候，我翻聊天记录和相册翻了二十分钟。后来逼自己做了个家具购买记录App，用Flutter跑在OpenHarmony设备上，核心需求除了录入、分类、到期提醒，就剩一个“想找什么直接搜”。本来以为搜索功能是最简单的，写个输入框，再加个List遍历，两晚上能完事。结果真上手之后发现，搜索这个功能做得好不好，跟数据模型、交互细节、跨端适配、性能取舍全都挂钩，光是“怎么搜、搜什么、排序怎么排、中文分词要不要做”这四个问题就够喝一壶的。这篇就把我实现搜索功能的完整过程写出来，包括踩过的坑和最后改了三版才定下来的搜索策略。适合打算用Flutter给OpenHarmony做应用、或者想把自己的工具类App搜索体验做扎实的开发者参考。

1. 为什么“搜索”值得单独设计：需求拆解与技术选型

1.1 用户到底会怎么搜：先搞清楚搜索词长什么样

做搜索功能之前，最忌讳的就是一上来写代码。我把自己关在房间里，模拟了一个真实的“找记录”场景：半年前买过一张升降桌，想查保修期，我脑子里浮现出的第一个词是“桌子”还是“升降桌”？是品牌名“乐歌”还是“升降桌”？都可能。更麻烦的是，我可能根本不记得品牌名，只记得“那是家京东买的”“花了大概两千三”。你看，用户搜索的入口是极度模糊的，不是数据库查询那种“输入完整字段名再匹配”的逻辑。

同理，搜索还得考虑中英文混合的情况。比如我买过一把“Herman Miller”椅子，记录里的名称是英文，但我可能输入“赫曼米勒”或者“人体工学椅”，甚至还可能输入“HM”——这就是多语言、多维度匹配的问题。我当时把搜索场景拆成了几类：按物品名称搜索、按品牌搜索、按购买渠道搜索、按金额范围搜索、按日期范围搜索，以及“不知道字段只知道大概语义”的模糊搜索。前几个是硬条件过滤，最后一个是真正的“搜索”。这些需求直接决定了后面的数据模型怎么设计。

1.2 技术方案选型：内存过滤还是数据库全文检索

这个项目的数据量不会特别大，撑死几千条购买记录，所以我首先排除了上重量级全文检索引擎的方案。很多技术团队一提到搜索就想到 Elasticsearch、SQLite FTS5、分词器，其实在小规模个人数据场景下属于过度设计。但我也没打算用最无脑的for循环遍历匹配，因为搜索体验不只是“找得到”，还要“找得快、排得准”。

我对比了三种方案：

• 方案A：每次搜索实时遍历内存中的List<PurchaseRecord>，对每个字段做contains判断。优点是实现简单；缺点是字段一多、每次搜索都重复扫描，数据到上万条后帧率会明显掉。
• 方案B：在启动时预计算一个“可搜索字段缓存”，把名称、品牌、备注等字段拼成一个长字符串，搜索时统一匹配这一个字段。优点是快，缺点是丢失了“哪个字段命中了”的信息，不好做高亮和排序。
• 方案C：数据量再大一点时直接上 SQLite FTS5，用数据库索引来做。

最终我选了方案B的改进版：预计算缓存的同时，保留每个字段独立的可搜索项和命中权重。这个决定在后面排序打分章节会详细讲。搜索本身在内存里完成，但排序、高亮、状态恢复这些体验细节可以做得非常精致。

1.3 为什么选Flutter而不是原生开发

项目跑在OpenHarmony上，很多人会问为什么不直接用ArkTS开发原生应用？这其实是个务实的选择：Flutter生态我已经积累了很多组件和经验，而且跨平台意味着后续如果我想把App搬到Android、iOS上，UI逻辑能复用八成以上。OpenHarmony目前对Flutter的官方适配已经比较成熟，常见的基础Widget、列表、动画、事件通道都有对应的实现，项目跑通没问题。

不过也得说清楚，Flutter跑在OpenHarmony上跟跑在Android上并不是百分之百一致，尤其是底层系统能力调用、输入法行为、文件路径这些地方，坑不少。后面我会专门用一整章来讲我在OpenHarmony真机上踩到的适配问题。这也是为什么我把这个项目定位成“实战”——不是官方Demo跑通了就算完，是要真正去解决业务需求里的各种边界情况。

2. 数据模型与可搜索字段设计：先把地基打结实

2.1 核心字段设计：不能只存“名字和价格”

家具购买记录如果只是存个名称、价格、日期，那搜索功能做上天也搜不出花来。我设计数据模型时参考了电商订单和资产管理系统的做法，每个购买记录包含以下字段：

class PurchaseRecord { final String id; // 唯一ID，用于编辑和状态恢复 final String name; // 物品名称，比如“升降桌”“人体工学椅” final String brand; // 品牌，可能为空 final String category; // 分类：桌、椅、柜、床、灯…… final String channel; // 购买渠道：京东、淘宝、线下门店 final double price; // 成交价格 final DateTime purchaseDate; final DateTime? warrantyEnd; // 保修截止日期，可能为空 final String notes; // 备注：颜色、尺寸、订单号等自由文本 final String imagePath; // 本地凭证截图路径 }

这个模型最核心的点是notes字段不能小看。很多时候用户真正能搜到东西的关键词就在备注里，比如“那款在宜家试过后来网购的白色桌面”。把这些自由文本纳入搜索范围，召回率会显著提升。图像路径我单独放了一个字段，是为了搜索结果显示缩略图时不必再去查文件系统。

2.2 搜索索引缓存：空间换时间的经典用法

每次搜索时实时遍历所有记录的每个字段，不是不能跑，但体验不够干净。我的解决思路是：启动时构建一份“搜索专用缓存”，只做一次全量拼接，之后所有搜索都在这份缓存上操作。

class SearchIndex { final String recordId; final String allText; // 所有可搜索字段的小写拼接 final String nameLower; final String brandLower; final String channelLower; final String notesLower; final num price; final DateTime date; }

构建这份索引后，搜索时先快速用allText.contains(keyword)筛掉完全无关的记录，然后再对命中者逐字段计算权重和得分。这比直接遍历原始对象快，也方便排序。索引构建有个细节：toLowerCase()必须预先做，避免搜索时对每个字符串反复调用，这个操作在大量数据时相当浪费。中文不受大小写影响，但品牌、渠道、备注里都可能混着英文，所以统一归一化处理准没错。

2.3 模拟数据与真实数据的一致性问题

开发搜索功能时我一开始用模拟数据测试，生成的家具名称集中在“沙发”“桌子”“椅子”几个词，结果搜索一切正常。上了真机录入真实数据后，出现了两个问题：一是备注里出现了我没准备的分词，比如“西昊 M18 人体工学椅 黑色”，用户可能搜“西昊”“M18”甚至“工学椅”；二是同一个物品，我在两个平台都买过，名称记录方式不一样，一个叫“书柜”，一个叫“收纳柜”。

这两个问题的教训是：测试搜索功能时，模拟数据一定要包含“脏数据”——拼写混写、中英混排、字段缺失、分类口径不一致。后来我把真实数据的脱敏版本导进了开发机，搜索逻辑才算经得起考验。所以数据模型设计好后，第一件事不是写搜索代码，而是整理一批足够“乱”的样本数据。

3. 搜索交互层：搜索框、防抖与候选词

3.1 搜索框基础搭建与清除按钮

搜索页我用的是一个独立的Flutter界面，顶部是TextField，下面是结果列表。看起来简单，但交互细节非常多。首先是清楚按钮：输入后右侧必须有一个“×”用来一键清空，这个不能用TextField自带的suffixIcon条件渲染来凑合，而是要结合 focus 状态和文本长度共同判断。我见过很多App清除按钮时隐时现，点起来偶发失灵，就是因为只判断文本长度没判断焦点。

其次是输入框的textInputAction设置成TextInputAction.search，这样键盘右下角会变成“搜索”按钮。点击搜索按钮时收回键盘、触发一次强制搜索（绕过已有防抖，这个细节后面解释）。最后，建议给TextField包一层Autofocus: false，不要把键盘自动弹起来，用户体验上搜索页自动弹键盘太油腻了。

3.2 输入防抖的取舍：300ms还是500ms

实时搜索必须加防抖，不加的话每个字符都会触发一次全量搜索，卡顿不卡顿先不说，状态和候选词会疯狂跳动。我用的防抖工具是Timer包装的：

Timer? _debounce; void _onSearchChanged(String keyword) { _debounce?.cancel(); _debounce = Timer(const Duration(milliseconds: 300), () { _performSearch(keyword.trim()); }); }

300ms是我对比后选择的中间值：中文输入法在联想阶段不会瞬间上屏，300ms足够等用户敲完一段短语；“搜索”按钮点击时则强制取消防抖立即执行。500ms听起来更稳，但实际体验里“按一下键盘字已经出来但结果还没动”的延迟感很明显，不适合工具类App。还有一个细节：搜索关键词要先trim()，否则空格会导致结果列表神秘性全部为空，尤其是用户从其他App复制文本粘贴过来的时候。

3.3 搜索历史与候选词：别小看这两个小功能

搜索历史是搜索页体验的杠杆功能，尤其对“保修期查询”这种高频重复场景。用户可以输入过一次“水龙头”，第二个月又坏了还想查，没有历史就得重新输入。我的实现是把搜索词存到OpenHarmony的轻量级偏好数据库里，最多存10条，去重后按时间倒序显示成历史标签。

候选词我做得比较克制。本来想实现“输入拼音首字母就出候选词”，但中文拼音首字母匹配需要构建词库，成本高、收益有限，我最终做的是“输入部分词匹配已录入家具分类和常用品牌”，把分类表里的“桌/椅/柜/床/灯/收纳”和品牌表里的常见词预加载，输入前两个字符就给出下拉建议。这个功能在OpenHarmony上要注意：列表弹出不要盖住输入法候选栏，否则视觉上会闪跳。

4. 核心搜索逻辑：多字段匹配、打分与高亮

4.1 多字段模糊匹配

搜索逻辑的核心是“到底匹不匹配”。我针对不同字段采用不同策略：

• 名称、品牌、备注、渠道：子串匹配（contains）
• 金额：支持范围查询，比如输入“2000-3000”或“>2000”触发价格过滤
• 日期：支持“2024-05”这样的月份匹配

核心的函数长这样：

bool _matches(SearchIndex idx, String query) { if (query.startsWith('>') || query.startsWith('<') || query.contains('-')) { return _matchPriceOrDate(idx, query); } return idx.allText.contains(query); }

不过这个写法是初始版，跑起来后发现问题很多。比如allText.contains会把“桌”这种单字词匹配到“书桌”，但也会把“饭桌”这种本来不想召回的结果捞出来。这就引出了排序打分的问题——匹配要宽松，排序要严格。

4.2 排序打分：为什么不能用“包含就行”

这是我改版最明显的一处。第一版只是“包含即返回”，结果搜“桌”的时候，数据库里所有带“桌”字的记录全出来了，排在第一位的不一定是我今天想找的那张升降桌，体验非常混乱。

我参考了通常搜索引擎的思维方式，针对这个业务场景设计了一套轻量打分规则：

double _score(SearchIndex idx, String query) { double score = 0; if (idx.nameLower == query) score += 100; // 名称完全相等 else if (idx.nameLower.startsWith(query)) score += 80; // 名称前缀 else if (idx.nameLower.contains(query)) score += 60; // 名称包含 if (idx.brandLower.contains(query)) score += 30; if (idx.notesLower.contains(query)) score += 10; if (idx.channelLower.contains(query)) score += 5; return score; }

权重设计的逻辑是：名称命中是最强的信号，品牌命中次之，备注和渠道只是弱信号。一条记录可能在四个字段里都命中同一个词，那就累加得分，比如名称里有“桌”、备注里也有“桌”，得分就会明显高于仅在名称里出现的记录。排序时得分高的在前，同分再按购买日期倒序。这个规则朴素，但对几百条记录来说，搜索结果准确率已经非常接近我想要的体验。

把排序和打分放一起，还有个好处是能对“完全没匹配”做兜底。有些搜索词确实不合理，一个有“全家桶”精神的搜索功能，这时候应该给出的是“没有找到相关记录”，而不是空白的白屏。

4.3 关键词高亮与Dart正则处理

结果列表里高亮关键词是搜索体验的标配。高亮实现的基本思路是把你输入的关键词在展示文本中标记出来，我用RichText或者TextSpan来包。Dart里可以用RegExp.escape处理特殊字符，避免用户输入[、(、*之类符号时正则爆炸。

final escaped = RegExp.escape(query); final pattern = RegExp(escaped, caseSensitive: false);

高亮时有个小坑：如果同一个词在一个字段里连续出现多次，比如“桌子桌子”，正则默认只匹配第一个。要全局匹配，需要给RegExp加上multiLine或者使用allMatches而不是firstMatch。另外，高亮不应该打断原文本的大小写信息，要用文本片段的前后索引去定位高亮区间，而不是简单替换成大写来显示。Flutter的TextSpan拼接时还要注意overflow: TextOverflow.ellipsis的优先级，高亮后文本如果变长，要保证省略号显示在末尾。

5. OpenHarmony适配记录：键盘、路径与EventChannel

5.1 输入法上屏与键盘遮挡问题

这个是我在OpenHarmony真机调试时遇到的第一块硬骨头。Android上常见的Scaffold(resizeToAvoidBottomInset: true)在OpenHarmony的Flutter适配版本里表现不完全一致。现象是：输入法弹出来时，搜索框被顶上去一点，但结果列表底部还有一截被键盘盖住，滚动到最后的记录永远看不全。

解决办法有两层。第一层是布局层面，把搜索页的根布局改成Scaffold+SafeArea，并在输入框聚焦时通过MediaQuery.of(context).viewInsets.bottom获取键盘高度，给结果列表底部加一个等高padding。第二层是要注意OpenHarmony输入法的预编辑文本问题，中文输入法在联想阶段选字前，TextEditingController的值可能包含未上屏的拼音字符。我在做防抖搜索前特意判断了输入法状态，在拼音拼写阶段不触发搜索，等真正上屏再执行。这个判断在Flutter层没有直接的API，我的做法是监听textInputConnection的setEditingState回调，同时配合一个“连续输入后300ms无变化才搜索”的防抖，基本能规避误搜。

5.2 EventChannel与系统能力调用的跨端适配

搜索功能本身不需要调用太深的系统能力，但搜索历史要持久化，搜索结果里的凭证图片要用本地文件路径，这就要跟原生层打交道。Flutter与OpenHarmony原生之间的双向通信，我用的是EventChannel，因为相比MethodChannel它在实时事件回调上更顺手。比如我需要在图片文件发生变化时刷新搜索结果，原生侧可以主动通过EventChannel把“文件更新了”的事件推给Flutter层，Flutter收到后自动重建搜索索引。

这里有个适配上的细节：OpenHarmony上获取文件路径的API跟Android不一样。Android可以用getApplicationDocumentsDirectory()，但OpenHarmony的目录权限策略有自己的默认路径和沙箱规则。我的做法是在原生侧写一个小的桥接方法，返回一个Dart侧便于操作的路径字符串。整个过程提醒我：Flutter插件在OpenHarmony上并不都能直接跑，用第三方插件前先查一下它是否已经适配鸿蒙的API，否则你在Android上跑得好好的，换到OpenHarmony上就直接崩。

5.3 真机vs模拟器：架构与性能差异

搜索功能在模拟器上测试时，一切流畅得让我以为大功告成。上真机后直接被上了一课：Flutter跑在OpenHarmony真机上，尤其是在带屏幕刷新率不太高的中低端设备上，输入法弹起和列表滚动时的掉帧感很明显。原因是模拟器走的是x86架构，指令集和渲染都在宿主机的GPU上；而真机是arm架构，搜索时大量allText.contains的字符串匹配没有经过任何优化，全部跑在UI线程。

这个问题的解法其实不该等到上真机才做。后来我把“索引构建”这种重活放到了compute或Isolate.run里异步执行，输入防抖搜索时不阻塞UI线程。索引构建在启动时执行一次，全量拼接上千条记录，几百毫秒完成但不开新线程会卡启动帧。我加了个遮罩层“正在准备索引”，后台跑完再出结果页面，这个等待用户几乎无感。

6. 性能调优与实测对比

6.1 三种搜索策略的实测数据

开发过程中我记录了三种搜索策略在真机上的性能表现，数据量是模拟的两万条购买记录：

我对这个结果很满意。第三方案虽然比第二方案慢3毫秒，但换来的是排序质量和高亮信息的完整，两万条数据下完全感觉不到差别。搜索这个功能，性能目标不是“最快”，而是在“不被感知”的前提下做最准的排序。同时索引构建的380毫秒被放到了启动阶段，实际上用户无感。

6.2 大数据量下的卡顿排查与Isolate化

有两万条数据之前，我一度天真地认为“搜索不需要优化”。直到我导入了大约八千条真实历史数据，在真机上连续输入“桌”字，键盘每一键拖出来的延迟感非常明显。排查过程有三个怀疑对象：

• 第一个是列表重建。结果列表用的ListView没有加itemExtent，关键词高亮又导致构建成本高，我换成ListView.builder并给每项固定高度后，滚动明显顺滑。
• 第二个是搜索本身。八千条记录单次全量匹配大约要6毫秒，不算致命，但每输入一个字符都触发一次，就会出现打字不跟手。
• 第三个才是重点——搜索历史写入和读取全是同步操作，OpenHarmony的轻量偏好数据库写入一次可能就有几十毫秒，我还在建索引的隔离区之外直接进行了偏好读写，导致IO阻塞UI。

修复方案就是我前面提到的：把索引构建和搜索这两个计算密集型操作完全扔进Isolate。Dart的Isolate.run在OpenHarmony的Flutter适配版里运行稳定，返回值用普通的Future接收，代码上也不用改太多。注意隔离区里不能直接访问数据库，需要把数据拷贝进去，所以我在调用前做了一个jsonEncode，把记录列表序列化后传入。这个操作也有成本，但只有启动时一次。

6.3 滑动、输入、搜索三者的帧率权衡

性能调优有个不太容易被量化的维度：交互场景的帧率平衡。搜索页上同时存在键盘动画、列表滑动动画、结果更新动画，三者的GPU和CPU资源是共享的。我经验是两个原则：一是结果列表仅在防抖结束后更新，而不是输入过程每帧都重建；二是不要在高频滚动时执行任何数据库写入操作，比如“搜索历史”要延迟到用户点击结果或者离开页面时再写，避免和滚动抢线程。

还有一个细节是OpenHarmony上动画插值器的表现，Flutter默认的Curves.easeInOut在部分设备上会显得“顿”，搜索时的结果过渡动画我干脆用了200ms的淡入淡出，减少持续的高频计算。如果你在真机测试时感觉搜索页“不算卡但说不出的别扭”，先检查这个动画时长，往往不是性能问题，是动画节奏跟系统不搭。

收尾：几个我事后觉得值得记下来的选择

回看整个搜索功能的实现，我最想提醒自己的是三件事。第一，搜索不是“输入框 plus 遍历数组”，它需要数据模型提前为搜索设计好可检索字段，需要索引、打分、高亮、历史、候选词这些细节共同支撑体验。第二，Flutter在OpenHarmony上的适配问题远比我想象的多，不要拿Android的开发习惯直接套用，尤其是在键盘行为和文件路径上，一定留出真机调试时间。第三，性能优化要基于真实数据的数量级来判断，我做这功能之前觉得两万条购买记录算非常多了，真导完数据发现交给正确索引和打分逻辑后，这点量完全不是负担；反过来，如果一开始就按“大数据架构”去设计，反而会把简单功能做复杂。

按这个方案，搜索功能的代码核心逻辑差不多两百行，剩下的都是界面和适配工作。对于只在本地记录几百件家具的人来说，稳定、快、好找，已经足够了。后续如果这个App真的被更多人用起来，我再考虑把搜索历史同步到云端，或者引入拼音首字母匹配，那就是另一个故事了。