做 Flutter for OpenHarmony 电子合同签署App 的这段经历里，我一度以为最硬核的会是签名面板、证书解析、骑缝章渲染这些"看得见"的模块。结果真到了测试和交付阶段，卡住我时间最久的，反而是看起来平平无奇的"活动历史"功能。
所谓活动历史，就是用户点进一份合同之后，能看到这份合同从起草、发出签署、被拒、重新签署、最终归档的完整过程记录。听起来就是个时间线列表，但随着真机适配、离线缓存、实时刷新、分页加载这些问题叠加到一起，它变成了一个非常典型的"看起来简单、做起来心累"的业务模块。
这篇文章不讲套话，就围绕 Flutter for OpenHarmony 电子合同签署App 中活动历史模块的实现，把我当时的方案选型、核心代码、踩坑记录和最终体验全部摊开。如果你也在做 OpenHarmony 上的 Flutter 业务开发，或者在做合同、审批、工单类 B 端 App，这篇文章应该能帮你少走不少弯路。
1. 项目背景与功能拆解
1.1 活动历史模块的业务定位
电子合同签署App 的核心链路很简单：创建合同、发送给签署方、签署方看合同、签字/拒签、回到发起方确认、归档存证。但这套链路里每一步都不是一次就能完成的，尤其是企业用户，一份合同往往要来回好几轮：销售助理发起合同，法务在上面加了审核批注，客户看了之后提出修改意见，发起方改完再次发送，最后才完成签署。
活动历史模块要做的，就是把这每一轮的操作按时间顺序记录下来，并且在界面上清晰呈现给用户。对普通用户来说，这个模块是"合同现在到底进行到哪一步了"的答案；对法务和风控来说，这个模块承担了还原事实过程的审计作用——谁在什么时间做了什么操作，操作前后合同内容有没有变化，这些信息都必须在页面上能回溯。
所以这个功能虽然 UI 上只是一条时间线，但它在产品里的定位是"信任基础设施"。这也是为什么我后来没有把它做成简单列表去糊弄，而是按一个独立的业务模块来做设计。
1.2 需求边界与展示层次
需求评审之后，我们把活动历史拆成了几个层次，避免一开始就往复杂了做。
第一层是基础时间线：按时间倒序展示合同的关键事件，比如"2024-03-12 10:23 王强发起了签署请求"、"2024-03-12 14:05 李敏拒绝了签署"、"2024-03-13 09:01 王强重新发送了签署请求"。
第二层是事件详情：每条活动记录点击进入之后，能看到该操作前后的合同状态、操作人、操作终端、IP 等审计信息。这里面最麻烦的是"合同状态快照"——不是说事件本身，而是操作发生那一刻合同数据是什么样。一开始我们想实时去请求合同详情，后来发现历史事件的合同快照必须随事件本身存下来，否则合同被修改之后，历史记录里的快照就失真了。
第三层是筛选与检索：用户要能按事件类型（签署完成、被拒、过期、归档）和操作人来筛。这一层在第一个版本只做了简单的类型筛选，操作人筛选延后了，因为要联动组织架构数据，复杂度会成倍上升。
如果你也在规划类似模块，我的建议是先做第一层和第三层的"查看型"需求，把时间线和筛选先交付。快照、审计、详情这些偏后端的能力，一定要在数据模型设计阶段就预留字段，不要等用户提了需求再补，那时候已经改不动了。
1.3 为什么选 Flutter + OpenHarmony 而不是 ArkUI
这里有个绕不开的问题：既然设备跑的是 OpenHarmony，为什么不直接用 ArkUI 开发？我们团队当时的判断是，业务不止要跑在 OpenHarmony 上，还要跑 Android 和 iOS，而且核心业务逻辑已经在 Flutter 代码库里沉淀了两三年。
如果我们为了一个平台重写 ArkUI 版本，团队要同时维护两套合同签署逻辑，业务迭代速度直接减半。Flutter 跨端方案的价值就在于，UI 层我们只写一份，平台差异全部收敛到"平台通道"这一层。
当然这个选择是有代价的。OpenHarmony 上的 Flutter 运行时和 Android 上的 Flutter 运行时在底层并不是完全一致的，尤其是原生插件、平台视图、后台存活这几个方面，都出现了不少适配问题。我在后面第 4 章会把踩过的坑详细列出来。
如果你是非 Flutter 团队，只做 OpenHarmony 单平台，我可能会建议你直接用 ArkUI，因为官方支持和坑位都更可控。但如果你已经有 Flutter 技术资产，走 Flutter for OpenHarmony 是完全值得的，前提是你要接受"适配成本没有文档写那么顺"这个现实。
2. 技术选型与架构设计
2.1 状态管理：从 ChangeNotifier 到 Provider
活动历史模块的状态不算复杂，主要有这几个：列表数据、加载状态、筛选条件、分页游标、是否有新事件到达。我一开始用的是ChangeNotifier + Provider，没有上 Bloc，原因很简单——这个模块没有复杂的 event-driven 状态转换，用 Bloc 反而要写很多样板代码。
基本结构是这样的：一个ActivityListController负责持有List<ContractActivity>、currentPage、hasMore、loadingMore这几个状态，对外暴露loadMore()和refresh()，数据变更时notifyListeners()，UI 层通过Consumer监听。
之所以不把分页游标直接塞进 Widget 里，是为了让"本地缓存 + 远程接口"这件事不散落在 UI 层。UI 只负责触发刷新和加载更多，具体的数据来源和合并逻辑都在 Repository 和 Controller 里面，这样测试和排错都干净很多。
如果你项目里已经有 Riverpod 或 GetX，也不是不行，但我不建议为了这个小模块把全家桶搬进去。状态管理选型的一个实用原则是：模块的状态越接近"一个列表 + 几个动作"，用最轻的方案就够了。
2.2 数据层设计：分页接口 + 本地缓存
活动历史的数据来源是服务端接口，每次进入合同详情页都会请求第一页数据，之后滚动到底部再拉下一页。但移动端网络不稳定，电子合同又是低频但高价值的场景，用户经常在地铁、地下室这种环境下看历史记录，所以本地缓存不能少。
我们的缓存策略很简单：合同ID + 页码 作为本地 SQLite 表的键，每一页数据直接以 JSON 字符串存进去，列表进来时先读缓存，同时发请求拿最新数据，拿到之后合并去重并回写缓存。
这里有一个容易忽略的坑：分页接口拿到的数据，可能在缓存期间已经有更新，比如用户A在后台改了合同，用户B打开列表看到的是脏缓存。解决方式是给每条活动记录加一个自增版本号或服务端时间戳，合并时用时间戳判断谁更新。没做这个处理之前，我在测试时反复遇到"列表里明明显示已拒签，点进详情却是已签署"这种诡异问题，后来才发现是缓存和接口数据各自为政造成的。
2.3 Flutter 组件通信与 EventChannel 打通原生事件
活动历史模块里有一块看起来不起眼但非常关键的内容：实时性。签署人在另一端完成了签署，如果当前用户正停在合同列表页，活动历史应该自动刷新出一条"对方已签署"的新记录。
这件事靠轮询能做，但体验很差。Flutter 端和 OpenHarmony 原生端之间，除了常规的MethodChannel请求-响应之外，还有一条很重要的通信方式叫EventChannel，它适合做原生向 Flutter 单向推送的连续事件流。我们的活动历史实时更新就是通过 EventChannel 实现的。
原生侧在合同签署状态发生变化时，往 Flutter 端推一个事件，里面带上合同ID和事件类型，Flutter 端收到之后判断当前页面是否正在展示这个合同，如果是，就触发一次局部刷新；如果不是，就把事件写入一个待处理队列，等用户切到该合同时再处理。
这里我想强调一个选型经验：Flutter 组件通信的方式有MethodChannel、EventChannel、BasicMessageChannel三种，很多人分不清。我的理解是，需要返回值的一问一答用 MethodChannel；原生主动推送、Flutter 被动接收的连续数据流用 EventChannel；需要双向收发并且不在乎消息格式的用 BasicMessageChannel。活动历史的实时事件用 EventChannel 是最顺手的。
2.4 路由切换与页面状态保活
活动历史的另一个隐蔽坑是路由切换。用户从合同列表进入合同详情，再从详情进入活动历史的某个事件详情，然后返回，中间经历了多层Navigator.push。如果这里不做状态保活，用户从事件详情返回时，活动列表可能会重新发起加载请求，页面会闪一下加载态，甚至滚动位置直接丢掉。
Flutter 里Navigator切换页面后会不会丢失状态，取决于你怎么组织页面。默认情况下，被完全覆盖的页面 State 会被保留，但不一定保留滚动位置和控制器状态。我们的做法是给活动历史列表的ListView设置PageStorageKey，同时让ActivityListController的实例放在上层页面或者 Provider 作用域里，不随路由销毁。
另外，如果你做的是底部 Tab 切换，建议直接用IndexedStack或者给子页面混入AutomaticKeepAliveClientMixin。实测下来，用IndexedStack虽然会一次性构建所有 Tab 的 Widget，但状态保活效果最稳定，对活动历史这种需要保持滚动位置的列表来说值得。
3. 活动历史核心实现
3.1 数据模型与 JSON 解析
先把数据模型写清楚。活动历史的服务端返回的 JSON 里，每个事件包含：事件ID、合同ID、事件类型、操作人、发生时间、事件详情对象。我用 Dart 定义了一个ContractActivity模型，事件类型用一个枚举来表达：
enum ActivityType { draftCreated, signRequested, signCompleted, rejected, expired, archived, } class ContractActivity { final String id; final String contractId; final ActivityType type; final DateTime happenedAt; final String operatorName; final String operatorId; final Map<String, dynamic> detail; const ContractActivity({ required this.id, required this.contractId, required this.type, required this.happenedAt, required this.operatorName, required this.operatorId, required this.detail, }); factory ContractActivity.fromJson(Map<String, dynamic> json) { return ContractActivity( id: json['id'] as String, contractId: json['contractId'] as String, type: _typeFromString(json['type'] as String), happenedAt: DateTime.parse(json['happenedAt'] as String), operatorName: json['operatorName'] as String? ?? '未知操作人', operatorId: json['operatorId'] as String? ?? '', detail: json['detail'] as Map<String, dynamic>? ?? {}, ); } static ActivityType _typeFromString(String raw) { switch (raw) { case 'DRAFT_CREATED': return ActivityType.draftCreated; case 'SIGN_REQUESTED': return ActivityType.signRequested; case 'SIGN_COMPLETED': return ActivityType.signCompleted; case 'REJECTED': return ActivityType.rejected; case 'EXPIRED': return ActivityType.expired; case 'ARCHIVED': return ActivityType.archived; default: return ActivityType.signRequested; } } }实际项目里我是用json_serializable生成的，手写这个示例是为了让你看清字段映射逻辑。注意detail这个字段不要设计成强类型，因为不同事件类型的详情结构差异很大。比如"发起签署"的 detail 里有签署链接和有效期，"拒绝签署"的 detail 里有拒绝理由和修改意见，"归档"的 detail 里有归档机构信息。统一用Map<String, dynamic>存，展示时再按类型做差异化渲染，这样服务端加字段时 Flutter 端不需要发版。
3.2 分页加载与下拉刷新
分页加载的核心是 Repository 层，我把它设计成这样：
class ActivityRepository { final ApiClient _apiClient; final ActivityLocalCache _cache; ActivityRepository(this._apiClient, this._cache); Future<List<ContractActivity>> fetchPage({ required String contractId, required int page, required int pageSize, bool forceRefresh = false, }) async { if (!forceRefresh) { final cached = await _cache.getPage(contractId, page, pageSize); if (cached.isNotEmpty) { return cached; } } final remote = await _apiClient.fetchActivityPage( contractId: contractId, page: page, pageSize: pageSize, ); if (remote.isNotEmpty) { await _cache.savePage(contractId, page, remote); } return remote; } }然后 Controller 里维护分页游标：
class ActivityListController extends ChangeNotifier { final ActivityRepository _repository; final List<ContractActivity> _items = []; final String contractId; int _page = 1; bool _hasMore = true; bool _loadingMore = false; List<ContractActivity> get items => List.unmodifiable(_items); bool get hasMore => _hasMore; ActivityListController(this.contractId, this._repository); Future<void> refresh() async { _hasMore = true; _page = 1; final remote = await _repository.fetchPage( contractId: contractId, page: 1, pageSize: 20, forceRefresh: true, ); _items ..clear() ..addAll(remote); _hasMore = remote.length >= 20; _page = 2; notifyListeners(); } Future<void> loadMore() async { if (!_hasMore || _loadingMore) return; _loadingMore = true; try { final remote = await _repository.fetchPage( contractId: contractId, page: _page, pageSize: 20, ); if (remote.isEmpty) { _hasMore = false; } else { _items.addAll(remote); _page += 1; _hasMore = remote.length >= 20; } notifyListeners(); } finally { _loadingMore = false; } } }UI 层用RefreshIndicator包住ListView.builder，滚动到底部时触发loadMore()。这里有一个经验：不要在build方法里直接写ScrollController监听，因为setState会导致监听器重复添加。建议把滚动监听放在initState里，用WidgetsBinding.instance.addPostFrameCallback确保页面渲染完成后再挂载。
我用的是itemExtent加固定卡片高度的方式，第一版没有加，结果列表滚动时明显卡顿。加了固定高度之后，Flutter 不需要逐项测量，滚动性能提升非常明显。
3.3 时间线 UI 的实现要点
时间线 UI 的常规做法是左侧一条竖线，每个节点有个圆点，右侧是事件卡片。如果用最基础的 Widget 堆，很快就会发现两个问题：连线位置不好对齐，圆点和卡片高度不一致时竖线会断。
我的做法是每一行用一个行级组件，左侧固定宽度放圆点，圆点下面是连线，右侧用Expanded放卡片。连线不要从头到底画一整条，而是画"上一个圆点底部到当前圆点底部"这段，这样无论卡片多高，线都是连续的。
具体的 Widget 结构我简化如下：
class ActivityTimelineItem extends StatelessWidget { final ContractActivity activity; final bool isLast; const ActivityTimelineItem({ super.key, required this.activity, this.isLast = false, }); @override Widget build(BuildContext context) { return IntrinsicHeight( child: Row( crossAxisAlignment: CrossAxisAlignment.stretch, children: [ SizedBox( width: 32, child: Column( children: [ Container( width: 12, height: 12, decoration: BoxDecoration( shape: BoxShape.circle, color: _colorFor(activity.type), ), ), if (!isLast) Expanded( child: Container(width: 2, color: Colors.grey.shade300), ), ], ), ), const SizedBox(width: 12), Expanded( child: Padding( padding: const EdgeInsets.only(bottom: 16), child: _ActivityCard(activity: activity), ), ), ], ), ); } }这里有个性能细节：时间线卡片里如果加了阴影、圆角裁剪、渐变这些装饰，滑动的每一帧都需要重绘，很容易掉帧。建议给每个卡片包一层RepaintBoundary，把卡片绘制结果缓存成位图。实测之后，活动历史列表的滚动帧率从开始的偶发掉帧，变成了全程稳定 60 帧。
另外，卡片上的时间显示，我推荐同时显示具体时间和相对时间，比如"10分钟前"作为主标题，"2024-03-12 10:23"作为副标题。电子合同用户对时间准确性非常敏感，只显示相对时间会让用户无法核对，只显示绝对时间又不够直观，两者都放是成本最低的方案。
3.4 实时更新与事件流驱动
前面说了用 EventChannel 接收原生事件，这里贴一下 Flutter 端的监听代码：
class ActivityEventBridge { static const EventChannel _eventChannel = EventChannel( 'com.example.econtract/activity_events', ); final Stream<dynamic> _stream = _eventChannel.receiveBroadcastStream(); void start({required void Function(ContractActivity event) onNewEvent}) { _stream.listen((event) { final eventMap = Map<String, dynamic>.from(event as Map); final activity = ContractActivity.fromJson(eventMap); onNewEvent(activity); }, onError: (Object error) { debugPrint('activity event stream error: $error'); }); } }原生端每次推送的事件结构，尽量直接复用ContractActivity的 JSON 格式，这样 Flutter 端解析逻辑只有一份。
这里要特别提一个我反复踩的坑：EventChannel 的监听注册要放在应用初始化流程里，并且要保证 Flutter 引擎已经完成初始化之后再注册，否则会导致事件丢失。最稳妥的办法是等第一帧渲染结束之后再start()，可以用WidgetsBinding.instance.endOfFrame.then(...)来确保时序。
实时事件进来之后，Controller 要做的是判断当前 PageView 首页是否就是这个合同，如果是，把事件插到列表头部并去重；如果不是，把事件写进一个 pending map，等切换回来时统一处理。这个逻辑看起来简单，但没有它，就会出现用户从合同A切到合同B，再切回合同A时，漏掉一笔签署记录的 bug。
4. 常见问题与排查技巧实录
4.1 服务端时间戳与时区显示错乱
活动历史的时间显示是最容易翻车的一个点。服务端存的是 UTC 时间，接口返回的是带Z的 ISO 格式字符串，比如2024-03-12T10:23:00Z。Dart 的DateTime.parse解析这种字符串时，得到的是 UTC 时间，直接用的话，页面时间会比本地时间慢 8 个小时。
解决方式是在fromJson里统一做一次.toLocal()，并且模型层只保留 Dart 的DateTime对象，展示层不要再做任何时区转换。我之前的代码里有一个隐蔽问题：某些事件在 UI 上做了addHours(8)的硬编码，结果测试人员在偏远时区测试时，时间又不对了。后来全部改成DateTime.parse(json).toLocal()才彻底干净。
4.2 大列表首帧卡顿与 Impeller 渲染问题
活动历史的列表如果一次塞 50 条以上，第一版在 OpenHarmony 真机上出现明显的首帧白屏和滑动掉帧。我排查之后发现原因有三个：卡片用了太多BoxShadow、列表没有设置itemExtent、时间线圆点颜色用了主题动态色导致每个 item 都要重新解析样式。
解决方式是给卡片阴影统一换成Container的边框加浅色背景模拟，去掉部分圆角裁剪，列表加固定itemExtent，并且给圆点颜色定义成静态常量。
还有一个和渲染引擎相关的坑：OpenHarmony 上的 Flutter 引擎对 Impeller 的支持还不是很完善，某些场景会出现渲染异常甚至平台视图黑屏。如果测试时发现页面渲染不正常，可以在启动参数里暂时关掉 Impeller，回退到 Skia 后端，等引擎版本升级后再重新开启。这个开关在接入 OpenHarmony 的 Flutter 版本里一般是配置在引擎初始化参数中，具体键名要看你用的 Flutter for OpenHarmony 分支版本，调试时可以用日志输出验证当前生效的渲染后端。
4.3 EventChannel 在 OpenHarmony 平台通道上的适配差异
我一开始把 Android 上成熟的 EventChannel 代码直接迁移到 OpenHarmony，结果发现原生侧拿不到正常的通道实例。后来翻了 Flutter for OpenHarmony 的适配文档才明白，OpenHarmony 侧注册平台通道的方式和 Android 不完全一样，通道要挂在正确的 Flutter 视图上下文上，而且EventSink的回调时机也有差异。
我的建议是，在 Flutter 端封装一个PlatformChannelAdapter，把所有 MethodChannel 和 EventChannel 的创建集中到一个类里。这样换平台适配时，只需要改这一个文件，业务层完全不动。这个抽象层的价值，在 OpenHarmony 和 Android 双端并行开发时体现得特别明显——同样的业务代码，两边的通道初始化可能完全不同，但业务层感知不到。
4.4 PlatformView 与 PDF 预览的鸿蒙适配
活动历史的事件详情里会涉及查看合同 PDF 原文，比如"拒绝签署"的事件详情里需要展示当时那一版合同预览。我们最初计划用 Flutter 自己的 PDF 渲染库，但对 OpenHarmony 的兼容性不好，后来改成了原生 PDF 预览组件，通过 PlatformView 嵌入 Flutter。
结果 PlatformView 在 OpenHarmony 上也踩了坑：PlatformView 和 Flutter 页面重叠时，触摸事件有时会穿透，导致列表没法正常滚动。我们最终的做法是把 PlatformView 放在一个独立的详情页里，不放在滚动列表中，同时给 PlatformView 容器加了IgnorePointer之外的触摸事件托管处理，才解决了无效触摸问题。
这里我的建议是：凡是涉及复杂原生视图的场景，尽量用"独立页面 + 全屏 PlatformView"的模式，不要在列表中间嵌一个小窗口，否则事件冲突排查起来极其痛苦。
4.5 XTS 认证与 Flutter 引擎版本相关的坑
OpenHarmony 应用如果要上架到官方应用市场，需要通过 XTS 兼容性认证，这个认证对原生 API 的调用约束比较严格。我们在适配环节遇到的一个问题是，Flutter 引擎内部会调用一些 OpenHarmony API，跑 XTS 测试时被判定为"使用了未声明的敏感权限"，导致应用无法过检。
这个问题的处理方式不是去改 Flutter 引擎源码，而是确认你用的 Flutter for OpenHarmony 版本是否基于当前 OpenHarmony SDK 版本适配。不同版本的 SDK 对权限管控和 API 约束差异很大，Flutter 社区版如果没有跟上，就会出现"开发时一切正常，一过 XTS 就挂"的情况。
我的经验是，在项目的oh-package.json5里声明权限时，尽量做到最小化，不用的权限坚决不写；同时通过一个PlatformCapabilities工具类，按 OpenHarmony API 版本做能力检测，避免在新旧版本系统上调用不存在的接口。这个做法让我们的活动历史模块在过 XTS 时省去了大量反复修改的时间。
5. 这次实战下来我最想提醒的三件事
第一件事：活动历史这种"低 UI 复杂度，高数据复杂度"的模块，一定先把数据模型和缓存策略定死，再去做时间线样式。我一开始先搭了漂亮的 UI，后补数据层，结果返工了两版，UI 再好看，数据合并逻辑不对，测试一看就是废的。
第二件事：如果团队里已经有 Flutter 代码资产，用 Flutter for OpenHarmony 是对的，但必须把平台通道封装成一个独立的适配层。EventChannel、MethodChannel、PlatformView、权限申请，这些东西在 Android、OpenHarmony 上的差异比想象中大，只有集中管理才能控制成本。我后期已经养成一个习惯：凡是涉及原生能力，先在适配层里跑一遍冒烟测试，再让业务接入。
第三件事：电子合同场景里，用户对"时间"和"事实"的信任感是产品的基本盘。活动历史里每一秒时间偏差、每一条记录丢多，都会变成信任危机。所以我最后做了一遍全量数据校验，把本地缓存和服务端数据逐条比对，确保不会有漏掉的事件和错误的时区显示。
如果你也在做类似的功能，我建议把这篇文章里提到的分页、缓存、EventChannel、状态保活这几件事，先做成一个最小可运行的骨架，再往里面填业务逻辑。这样既能看到全貌，又不会在实现细节里迷失方向。
