在鸿蒙生态上跑 Flutter本身就是一件自带话题度的事情如果再叠加“电子合同签署”这种对稳定性和安全性要求极高的业务场景那每一步都是在踩坑与填坑之间反复横跳。这段时间我一直在做 OpenHarmony 版的电子合同签署 App其中一个使用频率极高、逻辑看似简单但细节并不少的功能就是合同搜索。这篇文章就把我在合同搜索实现过程中踩过的坑、优化过的方案、以及和鸿蒙底层打交道的一些经验做个梳理希望能给同样在搞 Flutter OpenHarmony 的朋友省点时间。1. 项目背景与搜索功能定位1.1 电子合同App为什么需要强大的搜索能力电子合同签署 App 和普通工具类 App 有一个很明显的差异用户每次打开 App目的性极强。要么是找某个合同看状态要么是翻历史记录核对签署信息要么是处理待办签名。随着签署量增加合同数量从几十份增长到几千份只是时间问题这时候如果没有一个靠谱的搜索入口用户就得一页页翻列表体验会变得非常糟糕。搜索功能在这个场景下不是“锦上添花”而是核心路径的一部分。我在做需求拆解时把用户搜索合同的行为分成了三类一是按合同名称关键词搜索二是按合同状态筛选包括待签署、已签署、已作废这些三是按合同相对方或合同编号搜索这两类在实际使用中占比非常高。还有一个容易被忽略的诉求是搜索历史的保留因为合同名称往往很长用户第二次搜索时大概率会复用之前的关键词。所以搜索功能从一开始就被定位为高频核心功能而不是单纯的列表过滤。它的性能表现、交互细节、以及和原生能力之间的协作方式都会直接影响用户对整个 App 的评价。1.2 OpenHarmony Flutter 的适配选型选择 Flutter 来开发 OpenHarmony 应用最大的优势就是跨端复用。我们团队原本已经有一套成熟的 Flutter 代码库如果能直接在鸿蒙设备上跑起来就不用再单独维护一套原生鸿蒙应用开发和维护成本都会大幅降低。但实际去做的时候才发现OpenHarmony 的 Flutter 适配并没有想象中那么“开箱即用”。社区版本的 flutter_flutter 分支虽然一直在跟进但和官方稳定的 Flutter SDK 之间始终存在版本差异。我们当时遇到的最典型问题就是一个提示当前配置的 Flutter SDK 不被完全支持the current configured flutter sdk is not known to be fully supported。这类问题本质上是因为 OpenHarmony 的 Flutter 分支版本落后于上游某些新特性或 API 变更没有被同步过去。我当时的处理策略是锁定 Flutter 版本不要追新。OpenHarmony 的适配分支在哪个版本稳定就固定在哪个版本开发哪怕官方已经发布了更新版本也先按住不动。这个策略虽然保守但确实帮我们规避了很多底层兼容性问题。另外建议在项目根目录的 README 里明确记录当前使用的 Flutter 版本和对应的 OpenHarmony SDK 版本方便其他同事接入时能快速复现环境。2. 搜索需求拆解与整体设计2.1 需求场景分析合同搜索的场景看起来简单但深入拆解之后就会发现有好几层逻辑需要处理。我按照用户操作路径把它分成了四个核心场景。第一层是关键词搜索。用户输入合同名称中的部分文字我们需要在本地数据库中模糊匹配出相关合同。这里要解决的问题是匹配效率和结果排序不能用户输入几个字就卡半天也不能搜出来的结果乱七八糟没有优先级。第二层是条件筛选。用户可能只记得合同是“上个月签的”或者“状态是待签署”这时需要支持按时间范围和状态维度进行组合过滤。这个功能用列表页顶部的筛选入口就能实现但要注意筛选条件和搜索关键词之间是“且”的关系不是“或”的关系。第三层是搜索历史记录。用户搜索过的关键词应该被保留下来以标签形式展示在搜索页。点击历史标签可以直接再次发起搜索长按可以删除单条记录。这个功能实现起来并不复杂但体验价值极高。第四层是搜索结果落地页。用户搜索到合同后点击进入详情页从详情页返回时需要保持搜索关键词和滚动位置不变。这个场景看着不起眼但如果不做状态保存用户每次返回都要重新搜索体验就会打折扣。2.2 技术方案选型本地搜索 vs 服务端搜索在设计搜索方案时首先需要确定搜索是在本地执行还是请求服务端接口。这两种方案各有适用场景我整理了一个对比表格供参考。对比维度本地搜索服务端搜索响应速度毫秒级无网络延迟取决于网络状况通常在几百毫秒以上数据完整性只覆盖已缓存到本地的数据可以搜索全量合同数据离线可用支持不支持实现复杂度较低主要依赖数据库查询较高需要设计接口和联调实时性依赖本地数据同步策略实时性强我在实际项目中的选择是“本地优先 服务端兜底”的双层策略。用户搜索时优先在本地数据库中匹配因为本地检索速度极快能给用户即打即搜的反馈。如果本地结果为空再调用服务端搜索接口扩大检索范围。这样既保证搜索体验又不牺牲搜索的完整性。本地数据库我采用的是 sqflite 插件底层是 SQLite 数据库。之所以没有选择 Hive 或者其他的 NoSQL 方案是因为合同数据天然是结构化的合同名称、编号、状态、签署时间、相对方这些字段都非常适合用关系型数据库来存储和查询。而且 SQLite 对模糊查询 LIKE 的支持足够好配合索引可以达到很好的查询性能。2.3 数据结构与索引设计合同数据的表结构设计直接影响搜索性能。我最初的设计比较随意合同表就是简单的一个表把所有字段都塞进去。结果合同数量到了几千条之后搜索响应时间开始明显变长这时才意识到索引设计有多重要。我最终采用的表结构大致是这样CREATE TABLE contract ( id INTEGER PRIMARY KEY AUTOINCREMENT, contract_no TEXT NOT NULL, contract_name TEXT NOT NULL, counterparty TEXT, status INTEGER NOT NULL DEFAULT 0, sign_time INTEGER, create_time INTEGER, content TEXT ); CREATE INDEX idx_contract_name ON contract(contract_name); CREATE INDEX idx_contract_no ON contract(contract_no); CREATE INDEX idx_status_sign_time ON contract(status, sign_time);三个索引各有用途idx_contract_name 加速按合同名称模糊搜索idx_contract_no 支持按编号精确匹配和前缀匹配idx_status_sign_time 则用于常见的“状态时间范围”组合筛选。这里有一个关键点不要盲目地在所有字段上都建索引。索引能加速查询但也会拖慢写入和更新速度还会增加数据库文件体积。对于搜索功能来说只需要在真正作为查询条件的字段上建立索引即可。3. 核心功能实现3.1 搜索页面布局与交互设计搜索页面的布局我采用的是一种比较经典的方案顶部是搜索输入框和搜索按钮输入框下方是搜索历史区域再往下是搜索结果列表。点击输入框自动获得焦点并弹出键盘输入过程中实时触发搜索同时在输入框右侧显示清除按钮。Scaffold( backgroundColor: Colors.white, body: SafeArea( child: Column( children: [ _buildSearchBar(), Expanded( child: _buildBody(), ), ], ), ), );搜索输入框我使用了 TextField 组件并设置了 textInputAction 为 TextInputAction.search这样键盘右下角会显示“搜索”按钮符合用户操作习惯。另外设置了 autofocus 为 false避免进入页面时键盘自动弹起遮挡内容。搜索历史区域用了一个横向滚动的标签列表每个标签是一个圆角容器点击后直接执行搜索。这里我加了一个双击防抖逻辑防止用户快速点击同一个标签时发起重复请求。3.2 关键词匹配与拼音搜索实现关键词匹配的核心是模糊查询 SQLFutureListContractModel searchContracts(String keyword) async { final db await DatabaseHelper.instance.database; final likeKeyword %$keyword%; final result await db.query( contract, where: contract_name LIKE ? OR contract_no LIKE ? OR counterparty LIKE ?, whereArgs: [likeKeyword, likeKeyword, likeKeyword], orderBy: sign_time DESC, ); return result.map((e) ContractModel.fromMap(e)).toList(); }这个 SQL 实现了三个字段的模糊匹配并按签署时间倒序排列保证最近的合同排在前面。从实现角度来说这个方案已经能覆盖大部分搜索场景了。但我在实际使用中发现一个体验问题用户想搜索“华为技术有限公司”的合同却只记得“hw”这个缩写这时候模糊查询无能为力。为了解决这个问题我在合同表里增加了一个拼音索引字段 pinyin在合同数据写入时自动生成合同名称的拼音首字母组合然后在搜索时额外匹配这个字段。拼音转换我使用了一个轻量级的拼音库在数据插入时做一次转换搜索时直接匹配 pinyin 字段即可。这个方案的优点是搜索性能不受影响还是走 SQL 的 LIKE 查询只是多匹配一个字段而已缺点是合同名称是中文时没有问题但如果合同名称本身包含英文或数字需要做一下兼容处理。3.3 搜索历史与热门标签实现搜索历史我用 SharedPreferences 来存储数据结构是 List 最多保留 10 条。每次搜索成功后将关键词插入到列表头部并去除重复项然后保存回本地。Futurevoid saveSearchHistory(String keyword) async { final prefs await SharedPreferences.getInstance(); final history prefs.getStringList(search_history) ?? []; history.remove(keyword); history.insert(0, keyword); if (history.length 10) { history.removeRange(10, history.length); } await prefs.setStringList(search_history, history); }热门标签的设计和搜索历史类似只是数据来源从本地变成了服务端接口。服务端根据所有用户的搜索频率返回排名前几的热门关键词客户端在搜索页面顶部以标签形式展示。这块逻辑不难但要注意服务端接口的调用时机我是在进入搜索页后异步拉取热门标签不阻塞页面渲染。搜索结果为空时的展示也是容易被忽略的细节。我会展示一个空状态视图图标加提示文字“未找到相关合同”同时推荐几个热门搜索词让用户尝试。这个设计对降低用户的挫败感很有帮助。3.4 状态管理与页面状态保持合同搜索页有一个典型的状态管理诉求用户点击搜索结果进入合同详情页在详情页完成签署或查看操作后返回此时搜索页的关键词、搜索结果列表和滚动位置都必须保持不变。这里我遇到了很多 Flutter 开发者都会问的问题Flutter Navigator 切换页面后会丢失状态吗答案是默认情况下使用 Navigator.push 跳转新页面时原页面的 State 对象仍然保留在堆栈中状态不会丢失。但如果使用了某些会自动清理页面的操作或者页面被系统回收状态就可能丢失。我使用 Cubit 来做搜索状态管理搜索页的 UiState 保存在 Cubit 中页面销毁重建时可以通过 BlocProvider 再次获取同一个 Cubit 实例从而恢复搜索状态。下面是我定义的搜索 Cubitclass SearchCubit extends CubitSearchState { SearchCubit() : super(const SearchState()); void onKeywordChanged(String keyword) { emit(state.copyWith(keyword: keyword)); } void onSearchResultLoaded(ListContractModel result) { emit(state.copyWith(result: result, isLoading: false)); } void onSearchLoading() { emit(state.copyWith(isLoading: true)); } void onClearSearch() { emit(state.copyWith(keyword: , result: [], isLoading: false)); } }页面级别的状态保持通过 Cubit 处理滚动位置我用 PageStorageKey 保存。搜索列表使用 ListView.builder 时给 ListView 设置一个 PageStorageKey同时给 ListView 的 scrollController 传入 initialScrollOffset 参数返回页面时滚动位置就能自动恢复。这里有一个实践心得不要试图把所有的状态都放到 Cubit 里像输入框的文本内容、滚动位置这类 UI 态交给 Flutter 自带的机制处理更简单高效。Cubit 只保存业务状态比如关键词、搜索结果、加载状态。4. OpenHarmony 适配与原生通信4.1 平台插件适配鸿蒙流程做 OpenHarmony 适配时最头疼的往往是 Flutter 插件。很多 Flutter 插件表面上支持所有平台但到了鸿蒙这里就会出问题。社区中有部分插件已经适配了 OpenHarmony但生态远不如 Android/iOS 成熟。我用的插件策略总结下来就一句话能用官方渠道的就用官方渠道不能用就自己写平台通道。拿搜索功能的场景来说如果需要读取本地文件、获取设备信息、或者调用系统分享能力就要走平台通道。Flutter 平台通道有三种MethodChannel 适合请求-响应模式的调用EventChannel 适合事件流的持续监听BasicMessageChannel 适合双向消息传递。在搜索实现中我主要用了前两种MethodChannel 用于获取搜索所需的一些原生能力EventChannel 在服务端搜索时接收搜索结果推送。OpenHarmony 侧的插件开发和 Android 类似需要在项目的 ohos 目录下实现对应的平台通道代码。流程大致是在 Flutter 侧声明通道名和方法名在鸿蒙原生侧使用if (methodCall.method xxx)来判断方法名并执行相应逻辑。需要注意通道名在两端必须完全一致否则调用时不会报错但就是没反应这个坑我踩过一次。4.2 MethodChannel 与 EventChannel 在搜索场景中的应用我们在搜索功能中实际用到 MethodChannel 的场景是获取本地文件目录路径。因为合同详情可能需要打开本地存储的 PDF 附件而 Flutter 侧无法直接获取 App 的私有目录路径需要原生侧提供。static const platform MethodChannel(com.example.contract/app); FutureString? getAppDocumentsPath() async { try { final path await platform.invokeMethod(getAppDocumentsPath); return path; } on PlatformException catch (e) { debugPrint(获取路径失败: ${e.message}); return null; } }服务端搜索推送则使用 EventChannel。用户输入关键词后客户端先查本地数据库同时异步向服务端发起搜索请求。服务端如果耗时较长可以通过 EventChannel 分批推送结果客户端收到后逐步更新搜索结果列表。这个方案对于搜索结果特别多的情况非常有效用户不需要等所有结果都返回后才能看到数据。4.3 Flutter SDK 版本兼容性与 Gradle 插件问题OpenHarmony 开发中一个高频问题就是 Flutter SDK 版本不兼容。我之前遇到过一次升级 Flutter 版本后构建时直接报了一个错误提示当前配置的 Flutter SDK 不被完全支持。这个问题的根源是 OpenHarmony 的 Flutter 适配分支更新滞后上游 Flutter 的新版本还没有被适配。还有一个很常见的 Gradle 插件配置问题构建时报错信息大致是 applying flutters main gradle plugin imperatively using the apply method is no longer supported。这其实是 Flutter 构建方式变化导致的新版 Flutter 要求使用标准的 plugins 配置方式而不是在 build.gradle 中用 apply 方法引入插件。处理办法是修改项目 android 目录下的 build.gradle 配置把插件应用方式改为标准的 plugins 块或者在 flutter_flutter 分支支持的版本范围内调整配置。这类问题在 OpenHarmony 项目里尤其需要注意因为鸿蒙的构建链路和 Android 并不完全相同报错信息往往又像 Android 的报错导致排查方向容易跑偏。我最后采用的办法是锁死 Flutter 版本和 OpenHarmony 分支版本并在流水线里固定 flutter 和 dart 的路径减少环境差异带来的不可控问题。4.4 Dart 代码组织与 part 关键字搜索相关代码量变大后我做了代码组织上的重构。这里顺手提一下 Dart 的 part 关键字它允许将一个库的代码拆分成多个文件。在实际项目中我把搜索功能的数据模型、数据库操作、Cubit 状态管理拆分到了不同文件通过 part 关键字在同一个库中统一组织。// search_library.dart library search_library; part search_cubit.dart; part search_state.dart; part search_repository.dart;这样做的优点是文件职责单一查找和修改代码时定位很快缺点是 part 文件之间的私有变量和方法可以互相访问如果团队协作时没有明确规范容易产生隐式依赖。我用 part 的前提是这些文件的耦合度本身就很高属于一个业务模块的内部实现细节而不是把毫不相关的代码硬拆开。如果你的项目是多人协作且模块边界清晰用标准的 import/export 管理可能更合适。5. 性能优化与踩坑实录5.1 搜索卡顿优化搜索功能最容易出现的性能问题就是输入卡顿。用户每输入一个字符就触发一次数据库查询如果数据库数据量大查询耗时较长UI 线程就会被阻塞出现输入掉帧、键盘响应迟钝的问题。我的优化方案是给输入框的 onChanged 回调加一个 debounce 防抖逻辑用户停止输入 300 毫秒后才真正发起搜索。这样即使用户快速输入“劳动合同模板”七个字也只会触发一次搜索而不是七次。代码实现如下Timer? _debounceTimer; void _onKeywordChanged(String keyword) { _debounceTimer?.cancel(); _debounceTimer Timer(const Duration(milliseconds: 300), () { context.readSearchCubit().search(keyword); }); }这个方案的收益非常明显数据库查询次数从“每个字符一次”降到“整段输入一次”。实测下来输入流畅度和结果响应速度都有质的提升。另一个优化点是索引命中。LIKE 关键字以%开头时SQLite 无法使用普通 B-tree 索引会退化为全表扫描。为了缓解这个问题我在查询条件里对纯前缀匹配的场景做了特殊处理比如用户输入的合同编号是准确的就走startsWith方式查询这样可以完全命中索引。5.2 TabBar 点击取消动画效果搜索页中我加了一个分类切换的 TabBar用来区分“全部合同”“待签署”“已签署”这几个标签页。默认情况下 TabBar 点击切换时自带一个水波纹动画但在这个场景下我觉得动画有点拖沓点击后要等动画结束才能看到内容变化操作感受不够干脆。取消动画的方法很简单给 TabBar 设置一个空的动画效果覆盖即可。核心代码如下TabBar( controller: _tabController, tabs: const [ Tab(text: 全部), Tab(text: 待签署), Tab(text: 已签署), ], // 通过设置 indicator 和 overlay 相关参数来弱化动画 indicatorColor: Colors.transparent, overlayColor: MaterialStateProperty.resolveWith((states) Colors.transparent), )更彻底的处理方式是自定义一个 TabBar 替代组件完全自己控制布局和切换逻辑。但对于大多数场景去掉动画效果就已经够用了。这个点在 UI 体验上属于细节中的细节但如果你在做的是企业级应用这类细节往往决定了用户对产品专业度的感知。5.3 常见问题排查与避坑技巧我在搜索功能开发中遇到过不少问题这里整理成一张排查表都是亲测有效的经验。问题现象可能原因解决思路输入关键词后搜索无反应通道名不一致或 debounce 时间过长检查 MethodChannel 通道名是否一致尝试缩短防抖时间搜索速度慢未建索引或 LIKE 全局模糊查询在搜索字段上建立索引优化查询条件搜索结果高亮不生效富文本解析逻辑有问题检查 HighlightSpan 的 range 是否受字符串长度变化影响返回搜索结果页状态丢失Cubit 实例未正确保存使用 BlocProvider 的 lazy 参数管理 Cubit 生命周期OpenHarmony 上报错 Flutter SDK 不支持版本不匹配锁定 Flutter 版本和鸿蒙适配分支版本构建报 Gradle 插件 apply 方法错误配置方式落后修改为标准的 plugins 块配置还有一个我特别想提醒的坑搜索历史列表的去重逻辑。如果用户先搜索了“劳动合同”又搜索了“劳动”然后把“劳动合同”从历史记录里删掉再去搜索“劳动合同”这时新搜索应该把“劳动合同”插回历史列表顶部。这个场景我一开始没处理好导致同一个关键词在历史上出现两条数据越积越多后面检查才发现是去重逻辑没有在“删除后重新插入”的场景下生效。避坑技巧其实就一条凡是要动数据的操作先想清楚增量场景和存量场景然后写好单元测试覆盖住这些边界情况。搜索功能的逻辑不算复杂但正因为简单反而容易在细节上马虎。5.4 OpenHarmony 打包与构建问题打包构建阶段遇到的最头疼的问题是一个 Java 异常java.lang.AssertionError: java.lang.Exception: could not close这一类的报错。这类问题通常和 Gradle 缓存、文件锁、以及鸿蒙构建工具的冲突有关。我的排查步骤是这样先清理 Flutter 和 Gradle 的构建缓存执行flutter clean和删除android/.gradle目录然后检查是否有多个 flutter 进程同时运行导致文件锁冲突最后检查鸿蒙侧的 hvigor 构建配置是否和 Flutter 的构建缓存目录冲突。实测下来大多数情况下清缓存重试就能解决少数情况需要重启构建机器。如果你用的是 Windows 环境开发 OpenHarmony 应用这类文件锁和缓存冲突出现的概率更高建议优先使用容器化或 CI 流水线构建避免本地环境干扰。6. 合同搜索之外的扩展思考搜索功能做完了但合同数据的利用价值其实远不止于此。搜索本质上是“用户带着明确需求来查数据”而我们手里还有一类需求是不明确的用户只是想浏览看看有什么待处理的合同。这时候靠搜索就有点无能为力了更合适的是智能推荐。我在搜狗这个功能上线后做了一次后续规划基于用户的历史搜索关键词和合同签署状态在首页增加一个“猜你想找”的推荐位。实现思路可以基于搜索历史的词频统计找到高频关键词与合同名称做相关性匹配推荐相关合同。这个功能不需要引入重型推荐系统简单的词频统计加模糊匹配就能做出不错的效果。另外还可以考虑给搜索功能加入拍照识别能力。企业用户经常收到纸质合同需要录入系统如果能在搜索页提供“拍合同编号自动识别”的入口用 OCR 识别合同编号并直接跳转到对应合同这个体验会非常直接。OpenHarmony 上已经有可用的 OCR 能力接入方案Flutter 侧通过 MethodChannel 调用即可。总之搜索这个功能单独看是一个闭环放到整个 App 的业务体系里它又是用户行为的入口和数据积累的节点。把搜索数据和用户行为串联起来往往比搜索本身更出价值。我在实际开发中的最大体会是越是看起来简单的功能越要重视状态管理和边界情况。合同搜索界面上就是输入框加列表但真正做下来涉及到的技术点涵盖了数据库索引、状态管理、平台通信、性能优化和构建排障。每一个环节单独拿出来都不算难难的是把它们组合在一起时任何一个点掉链子都会影响整体体验。尤其在做 OpenHarmony 适配时很多问题不是 Flutter 层面的而是构建环境和平台差异带来的保持耐心、做好版本控制、记录踩坑日志是跨端开发最值得养成的习惯。