1. 项目从零梳理为什么搜索历史值得好好设计1.1 垃圾分类指南App的功能地图搜索历史放在哪先交代一下背景。我手上的垃圾分类指南App核心功能就是输入物品名称返回它是可回收物、有害垃圾、厨余垃圾还是其他垃圾同时给出投放提示和注意事项。这类App的功能链路看着简单但整个信息流都是围绕“搜索”展开的用户搜“香蕉皮”、搜“过期药品”、搜“玻璃瓶”每次查询背后对应一套投放规则。搜索这个入口的体验好坏直接决定了用户会不会留着这个App。在这个前提下搜索历史不是可有可无的装饰它是搜索效率的关键一环。垃圾分类是一个高频、反复的场景用户今天查了“一次性餐盒”明天还会查隔两周还要查。如果每次都重新输入汉字体验落差非常大有了历史记录用户点一下就能再次查询。我在做需求拆解时把搜索历史明确为三个能力第一展示最近查过的关键词方便二次查询第二支持删除单条和清空全部毕竟有些搜索词带个人信息属性用户对隐私是敏感的第三把本地历史作为后续“热门搜索”运营位的数据基础有了本地记录至少可以做到“用户常搜的词优先展示”比完全依赖服务端下发要灵活。为什么单独把搜索历史拿出来写一篇实战因为这个需求横跨了存储选型、状态管理、UI交互、平台适配四个层面是一个能把 Flutter for OpenHarmony 开发里的典型问题一次性串起来的小而全的案例。比起那些动辄几十个页面的完整项目分享这种功能模块更贴近大多数人的实际开发节奏也更容易把每个技术决策讲透。1.2 三种本地存储方案对比我的最终选择及理由做搜索历史第一步不是画界面而是定存储方案。我在常规 Flutter 平台上常用的方案主要有三种换到 OpenHarmony 之后每种方案的适配成本和限制都不一样必须提前想清楚。存储方案优点缺点搜索历史场景评估shared_preferences 系列API简单键值对存储开发效率最高全量读写不适合大数据量最推荐几十条历史完全够用sqflite / drift支持 SQL 查询扩展能力强依赖原生数据库实现OpenHarmony 适配成本高偏重除非要做复杂统计分析文件存储完全可控序列化方式自己定需要自己处理并发、编码、沙箱路径可接受但没必要给简单需求增加复杂度我最终选了 shared_preferences 这一派。原因有三个。第一搜索历史的体量很小撑死几十条每条就一两个字段这个量级用关系型数据库属于杀鸡用牛刀。第二shared_preferences 在 Flutter 里的语义就是“轻量配置和本地状态”跟搜索历史天然匹配。第三也是最重要的OpenHarmony 社区已经有了对应的适配实现省去了自己写 MethodChannel 的麻烦——这一点后面专门讲。我也建议不要一开始就上重型存储。如果你们的产品后续要求按周统计搜索趋势、按关键词频率做排序推荐再把数据迁移到数据库也不迟。数据层做好接口封装替换成本没有想象中高。1.3 全局状态怎么管ChangeNotifier 方案为何够用搜索历史不是只在一个页面用。用户在首页搜索框搜完要跳转结果页结果页里可能有一个“换个词再查”的入口点进去要能直接看到历史设置页又要放一个“清空搜索历史”的按钮。如果每个页面各自读一遍存储很快会被数据不同步的问题缠住。我的做法是在项目启动时初始化一个全局的 SearchHistoryService 单例基于 ChangeNotifier 实现通过 Provider 注入到 Widget 树。任何页面要读历史监听这个服务任何页面要写历史调用服务里的方法。写完调用 notifyListeners 通知所有监听的地方自动刷新。这套方案在 Flutter 社区里非常成熟代码量也小。为什么不直接用 Riverpod 或者 Bloc不是说它们不好而是这个项目里历史数据的读写路径太简单了就是一个列表的增删改查。ChangeNotifier 足够表达且心智负担最小。等后续如果要在历史数据上叠加“热词推荐”“联想搜索”服务层再加方法就行结构不需要推翻重来。状态管理的选型原则从来都是够用就好堆一堆抽象反而让新人难以维护。2. 数据层设计历史记录这样建模才不容易出问题2.1 记录一条搜索历史需要哪些字段搜索历史本质上是“关键词时间”的列表所以字段设计不用复杂。我用了两个核心字段外加一个冗余字段keyword用户搜索的关键词类型是字符串。注意要存trim之后的结果去掉首尾空格避免同一个词出现“香蕉皮”和“ 香蕉皮”两条脏数据。searchTime搜索时间类型用 int 存毫秒时间戳而不是用 ISO 字符串。时间戳排序方便展示时再转换成“今天 14:30”这种人类可读格式即可。cachedCategory这个字段是后来加的有点冗余的味道。用户搜索某个关键词后如果命中了分类就把分类结果一起缓存。下次用户从历史里直接点选App 可以秒开结果页不用再走一次完整查询链路。这个字段不是必须的但加上之后体验提升明显。我在设计时还刻意留了一个扩展位假如后面要支持用户删除单条历史并同步到服务端可以在模型里加一个 updatedAt 字段用来做增量同步。现在不放进去只是不想让这个简单模型背上用不到的包袱。class SearchHistoryItem { final String keyword; final int searchTime; // 毫秒时间戳 final String? cachedCategory; // 冗余缓存可空 SearchHistoryItem({ required this.keyword, required this.searchTime, this.cachedCategory, }); factory SearchHistoryItem.fromJson(MapString, dynamic json) { return SearchHistoryItem( keyword: json[keyword] as String, searchTime: json[searchTime] as int, cachedCategory: json[cachedCategory] as String?, ); } MapString, dynamic toJson() { return { keyword: keyword, searchTime: searchTime, cachedCategory: cachedCategory, }; } }2.2 内存缓存与持久化双写一致性的处理思路搜索历史的读写频率比想象中要高。用户每提交一次搜索就是一写每打开一次历史面板就是一读。如果每次都走 SharedPreferences 的全量序列化和反序列化虽然数据量小数据也不会卡但反复做 IO 终归不是正路尤其在一些低端设备上能体会到轻微延迟。我的方案是内存缓存 持久化的双层结构。App 启动后服务层从 SharedPreferences 读取一次把历史列表放在内存的 List 里。之后所有读操作都直接走内存秒开。写操作也不急着每次同步磁盘而是更新内存后调用 _persist() 异步落盘。由于搜索历史的写操作本身频率有限这个策略不会引入明显的性能问题反而让 UI 的响应更跟手。实现上有一个细节容易忽略SharedPreferences 的 setString 方法是异步的但你不能因为异步就在 UI 上拖着不刷新。先更新内存 List 并 notifyListeners再等持久化完成顺序不能反。万一持久化失败了怎么办我的策略是下次启动时最多恢复到你上次成功落盘的快照不阻塞当前操作。持久化失败的概率在正常设备上很低但因为搜索历史是可重建数据没必要用太重的保底逻辑。2.3 去重、排序与数量上限近二十条策略的取舍搜索历史最常见的三个设计问题是要不要去重、用什么排序、保留多少条。去重是必须的。用户今天搜“牛奶盒”明天还搜“牛奶盒”如果不去重历史里出现两条一模一样的记录看起来就很冗余。去重的策略不是“遇到重复就丢弃新记录”而是“遇到重复就删掉旧记录再把新记录提到最前面”。这样既不会堆重复项又能保证排序反映真实的使用频率。排序整体采用“最近使用优先”。每次写入都把该关键词移动到列表头部历史列表自然按时间倒序。这里有个看似简单但容易做错的点删除旧记录和插入头部这两步必须在同一个修改批次里完成并通过 notifyListeners 一次性通知 UI。如果分两次操作并两次通知UI 可能出现闪烁或中间态。数量上限我设置了 20 条。原因是移动端屏幕空间有限一行能放下五六个标签就已不错四行左右刚好展示完 20 条再往下滚动就失去了“随手点一下”的快捷意义。同时固定上限也兜住了持久化数据无限膨胀的问题。上限设成 20 还有一个隐藏好处清空历史的成本很低用户就算有隐私顾虑也能一眼看完自己留下了哪些记录。3. 手把手实现从环境搭建到代码落地3.1 Flutter for OpenHarmony 环境搭建的几个关键动作在 OpenHarmony 上做 Flutter 开发环境跟标准 Flutter 略有差异我踩过一遍后总结了四个关键动作。第一获取 OpenHarmony 适配版的 Flutter SDK。标准 Flutter SDK 目前不直接支持 OpenHarmony需要用社区维护的 fork 版本一般从开源社区镜像仓库拉取 flutter_flutter 工程选择 release 分支。这一步不能省直接用标准 SDK 后面会遇到平台实现缺失的问题到时候排查成本更高。第二配置环境变量。把 flutter 的 bin 目录加入 PATH同时配置好 OpenHarmony SDK 路径让 Flutter 能识别到 OpenHarmony 工具链。注意不同版本的 flutter_flutter 对 OpenHarmony SDK 版本有最低要求版本太老会编译不过建议直接使用 release 分支里推荐的 SDK 版本组合。第三工程融合。Flutter 代码和 OpenHarmony 壳工程是两个层面。通常做法是用 DevEco Studio 创建 OpenHarmony 工程作为壳再在工程目录下加入 Flutter module通过命令行或 IDE 集成。这个融合过程和安卓原生项目嵌 Flutter 页面很像做过原生嵌入的会比较容易上手。第四版本校验。我第一次搭好环境运行项目时控制台就弹出了类似 the current configured flutter sdk is not known to be fully supported 的警告。这个提示的成因是版本标识校验不匹配常见于用了标准分支 SDK 去跑对 OpenHarmony 的壳工程或者 fork 分支的版本号与工程预期不一致。处理方式是以工程模板锁定的 SDK 版本为准把 flutter 环境切到对应分支然后执行 flutter doctor 重新校验警告消除后再继续。3.2 服务层完整代码增删查与持久化服务层是搜索历史模块的核心。我先建立一个 SearchHistoryService继承 ChangeNotifier把存储和通知逻辑都收敛到这一层。import dart:convert; import package:flutter/foundation.dart; import package:shared_preferences/shared_preferences.dart; class SearchHistoryService extends ChangeNotifier { static const _storageKey garbage_search_history; static const _maxItems 20; final SharedPreferences _prefs; final ListSearchHistoryItem _items []; SearchHistoryService(this._prefs) { _loadFromStorage(); } ListSearchHistoryItem get items List.unmodifiable(_items); bool get isEmpty _items.isEmpty; void _loadFromStorage() { final raw _prefs.getString(_storageKey); if (raw null || raw.isEmpty) return; try { final list jsonDecode(raw) as Listdynamic; _items ..clear() ..addAll( list.map((e) SearchHistoryItem.fromJson(e as MapString, dynamic)), ); } catch (_) { // 反序列化失败时静默降级避免启动崩溃 } } Futurevoid addSearch(String keyword, {String? category}) async { final trimmed keyword.trim(); if (trimmed.isEmpty) return; _items.removeWhere((item) item.keyword trimmed); _items.insert( 0, SearchHistoryItem( keyword: trimmed, searchTime: DateTime.now().millisecondsSinceEpoch, cachedCategory: category, ), ); if (_items.length _maxItems) { _items.removeRange(_maxItems, _items.length); } notifyListeners(); await _persist(); } Futurevoid removeItem(String keyword) async { _items.removeWhere((item) item.keyword keyword); notifyListeners(); await _persist(); } Futurevoid clearAll() async { _items.clear(); notifyListeners(); await _persist(); } Futurevoid _persist() async { final raw jsonEncode(_items.map((e) e.toJson()).toList()); await _prefs.setString(_storageKey, raw); } }这段代码有几个细节值得强调。第一服务层持有 SharedPreferences 实例而不是在方法内部重复调用 SharedPreferences.getInstance()避免每次操作都做一次异步取实例的开销。第二增删方法都在修改内存后立刻 notifyListenersUI 刷新不受磁盘写入速度影响。第三删除单条和清空全部都做了独立方法方便 UI 层直接调用不需要在调用方写过滤逻辑。3.3 搜索历史 UI标签流、删除按钮与空态搜索历史的 UI 我不建议用 ListView因为历史记录通常是短词用流式布局更紧凑。Flutter 里的 Wrap 组件天然适合做这件事每个关键词用一个 ActionChip 展示点按触发搜索Chip 自带删除能力。class SearchHistorySection extends StatelessWidget { final SearchHistoryService service; final ValueChangedString onSearch; const SearchHistorySection({ super.key, required this.service, required this.onSearch, }); override Widget build(BuildContext context) { // 通过 ListenableBuilder 或 Consumer 监听服务变化 return ListenableBuilder( listenable: service, builder: (context, _) { if (service.isEmpty) { return const SizedBox.shrink(); } return Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: [ const Text( 搜索历史, style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16), ), TextButton( onPressed: service.clearAll, child: const Text(清空), ), ], ), Wrap( spacing: 8, runSpacing: 8, children: service.items.map((item) { return ActionChip( label: Text( item.keyword, maxLines: 1, overflow: TextOverflow.ellipsis, ), onPressed: () onSearch(item.keyword), deleteIcon: const Icon(Icons.close, size: 16), onDeleted: () service.removeItem(item.keyword), ); }).toList(), ), ], ); }, ); } }UI层面有三个容易翻车的点。一个是空态处理历史为空时整块区域直接不显示不要留着标题栏和清空按钮占位。第一个用户进来看到“搜索历史 清空”下面空荡荡的观感很差。第二个是 Chip 里的文字长度关键词过长时会撑坏布局必须限制 maxLines 为 1 并设置 ellipsis。第三个是删除按钮的热区ActionChip 默认的 deleteIcon 点击区域较小在手机端容易误触我实测下来保留默认大小问题不大但如果用户反馈误触严重可以把 deleteIcon 的尺寸加大到 20 左右。3.4 搜索框联动防抖与写入时机控制搜索历史最容易做错的地方是把“写入历史”和“输入框内容变化”绑定在一起。新手常见写法是 onChanged 里直接 addSearch结果用户输入“香蕉皮”三个字历史里瞬间多了三条香蕉、香蕉皮、还有中间的拼音输入过程。这是产品上不能接受的。正确的写入时机有两个一个是用户提交搜索时另一个是用户点击历史标签触发搜索时。我在实现里把这两个路径都统一到 submitSearch 方法里先调服务层写入历史再执行真正的搜索跳转。如果后续要加联想功能也就是用户输入过程中下拉展示候选词那可以用 Timer 做 300 毫秒的防抖只在用户停顿后触发联想请求。注意联想请求和写入历史是两码事联想词在被用户选中时才算一次有效搜索那时才需要写入历史。我在项目里曾经想偷懒把联想接口返回的前几个词自动写进历史结果用户根本没点选历史里全是没意义的半截词后来果断改掉了。另外还有一个细节从历史标签点击搜索时要把关键词回填到输入框。这里需要给 TextEditingController 赋值同时注意光标位置直接把光标移到最后。不要用 setState 重建输入框否则会触发键盘收起又弹出的抖动。4. 踩坑实录与排查思路4.1 MissingPluginExceptionOpenHarmony 上的存储插件适配在 OpenHarmony 上跑通搜索历史最先遇到的就是这个报错调用 SharedPreferences.setString 时抛出 MissingPluginException。原因很直接——官方 pub.dev 的 shared_preferences 插件内部通过 MethodChannel 调用宿主原生实现但 OpenHarmony 不是 Android官方插件没有在 OpenHarmony 侧注册对应的实现通道。我带的第一反应是新写一套存储逻辑后来发现不必这么激进。OpenHarmony 社区已经有适配好的 shared_preferences 版本包名和导入路径与官方几乎一致直接替换依赖引用就能用。这个替换不是简简单单换版本号就行要注意适配版的 API 层面是否完全对齐官方版。我的经验是在替换前先看这个适配包的更新记录确认它跟随的官方版本基线避免 API 差异造成新的编译错误。如果你们团队不方便引入第三方适配包也可以自己写 MethodChannel 完成键值对存取。OpenHarmony 原生侧有对应的偏好存储 APIFlutter 侧写好 handler 并不复杂。但自己实现就意味着要维护两端代码存储结构变了还要同步改能省则省这个判断要自己拿捏。4.2 中文关键词写入后读不出来的问题搜索历史里大量数据是中文这块有问题会直接影响功能可用性。我碰到的现象是往 SharedPreferences 写入中文关键词后App 重启读取发现历史列表是空的或者个别词变成了乱码。排查步骤一般是先确认写入端的编码。Flutter 侧默认字符串就是 UTF-16 内部表示JSON 序列化后是 UTF-8 字符串正常情况下不会有问题。真正的问题往往出在 OpenHarmony 原生侧的 SharedPreferences 实现上早期适配版本对特殊字符集的处理不够完整导致中文字符在底层读写时丢失。这个问题的处理策略是升级到修复了编码问题的适配版本。如果坚持用旧版本可以尝试的规避方案是不要直接存原始中文而是用 base64 或者 URL 编码包装一层但这样写出来的历史数据不具备可读性后期排查看不出问题在哪属于不得已而为之。我建议直接在依赖层面解决不要在业务层做这些绕路的 hack。4.3 软键盘弹起把历史区域挤没了一半搜索历史出现在输入框下方。软键盘弹起时页面可用高度被压缩如果布局写得太死历史区域会被挤到看不见用户想点历史反而要把键盘收起操作路径变得很奇怪。Flutter 侧的处理点是 Scaffold 的 resizeToAvoidBottomInset 属性。默认是 true意思是键盘弹起时 Scaffold 会调整 body 高度。对搜索历史这种场景我建议保留默认的 resize 行为让历史区域跟着上移保证标签流始终可见。如果你的输入框在顶部而历史列表很长反而可以考虑把 resizeToAvoidBottomInset 设为 false让历史列表可以滚动而不是被压缩。还有一个 OpenHarmony 特有的点壳工程的窗口软键盘模式需要与 Flutter 侧配合。如果在 DevEco Studio 里配置了 adjustNothingFlutter 侧再怎么设置也收不到正确的视口变化。这个属于跨端联调问题排查时一定要两端都看一眼。4.4 跨页同步历史记录改了页面没刷新搜索历史模块很容易出现一个隐蔽问题在结果页触发了一次搜索历史列表更新了但回到首页时历史区域没有刷新。出现这个现象的原因多数是监听挂错了地方。如果项目里用的是 Provider 的 Consumer要注意 Consumer 包裹的 Widget 范围是否覆盖了历史区域。有时候为了让代码少缩进几层把 Consumer 放在整个页面根部但页面根部组件由于某些原因没有继承到同一个 Provider 实例就收不到通知。排查时先确认 Provider 是在 MaterialApp 之上注入的再确认历史区域确实是同一个 BuildContext 下面的 Consumer。另一个原因是服务层写操作没有调 notifyListeners。在 addSearch、removeItem、clearAll 三个方法里我都调用了 notifyListeners但如果你后续自己加了一个方法比如合并历史很容易忘记通知。我的习惯是凡是修改 _items 的方法要么在一个批次里修改并通知一次要么在方法末尾统一调用 notifyListeners避免漏通知。4.5 历史条数暴涨后的列表性能优化20 条历史理论上不需要性能优化但如果产品经理把“建议保留次数”改成 100 条或者历史记录里塞进了长文本关键词一次性构建所有 Chip 也会带来首帧卡顿。性能优化的第一板斧是降低单条构建成本。Chip 内部的 TextStyle、Padding 尽量用常量不要在 build 方法里动态创建。第二板斧是避免无谓的重建把历史区域包一层 ListenableBuilder只有历史数据变化时才重建 Chip 列表。第三板斧是如果历史条目真的很多可以把 Wrap 换成 ListView.builder用懒加载降低首帧开销滚动时再按需构建。顺带一提如果滚动历史列表时掉帧还可以关注一下当前 Flutter 版本在 OpenHarmony 上的渲染引擎配置。不同版本的渲染路径有差异遇到掉帧先检查 build 方法里有没有耗时操作再考虑引擎层面配置不要上来就改架构。我在实际测试中还发现调试模式下写存储的性能明显低于 release 模式这是 Flutter 开发的常规现象。判断存储性能问题时尽量用 release 包做基准不要被 Debug 模式的数据误导。最后再说一个从需求出发的体会搜索历史这个功能虽然小但它牵出的存储、状态、UI、平台适配问题几乎是 Flutter for OpenHarmony 开发的缩影。把数据结构和状态管理在前置设计里理顺后面无论是扩展搜索联想还是接入更多跨端能力都会顺手很多。如果你们项目里还有其他类似的轻量功能也建议用同样的思路去拆解一遍——先把数据层稳住了UI 层再怎么改都不慌。