做了三个月的项目先交代背景我们团队要给OpenHarmony设备做一款移动数据使用监管助手技术栈选定Flutter for OpenHarmony核心功能之一就是SIM卡管理。最初我预估这款功能就是读一读运营商、拿一下IMSI真正落地方案时才发现从系统Telephony能力到Flutter端的桥接、卡槽识别、状态监听、双卡流量归属每一步都有决策要做。这篇文章就把我们这版SIM卡管理模块从设计到落地的完整路径讲清楚包含桥接层的代码骨架、踩过的坑和最终的调试方法给准备在OpenHarmony上用Flutter做通信类功能的团队一份可参考的实战记录。1. 立项前先想清楚为什么移动数据监管类App要把SIM卡管理单独拆出来做1.1 表面需求是读卡真实需求是流量算在谁的账上很多团队拿到移动数据使用监管助手这类需求时第一反应是打开系统文档找SIM卡信息查询接口返回什么就显示什么。这其实漏掉了产品的核心逻辑用户关心的不是ICCID或者IMSI本身而是我这个月到底用了多少流量、这笔流量算在主卡还是副卡头上、流量快用完了系统能不能提醒我。举几个实际场景。家里给孩子配了手机用的是共享流量套餐家长需要在App里看到孩子当前用的是哪张卡、这个月已经消耗了多少共享流量。双卡用户很可能一张卡用于日常上网、另一张卡用于收验证码和通话App需要正确识别流量消耗归属。企业给员工配发工作手机时也会把工作SIM和个人SIM分开月底要看工作卡的使用情况。这些需求都指向同一件事SIM卡信息必须和流量统计体系强绑定。也就是说SIM卡管理在架构上不是一个独立的、可插拔的读取工具它是流量统计的上游模块。读取到的卡槽编号、卡状态、默认数据卡标识这些字段会在后续被流量查询、月度报表、超额提醒这些功能反复引用。如果一开始不把SIM管理拆成独立模块而是把Telephony查询散落在各个页面里双卡场景一出来代码就会变得非常难维护。1.2 为什么偏偏用Flutter for OpenHarmony这个选择不是拍脑袋。首先是团队技能栈的复用UI层我们已经有比较成熟的Flutter组件积累统计图表、卡片列表这类界面用Flutter写效率很高。其次是终端覆盖问题OpenHarmony的设备形态不只有手机还有平板、带屏设备、信息栏设备Flutter的分支能保证同一套UI逻辑跑在多个形态上不用为每个形态单独维护一套前端代码。但选型也意味着承担一个现实Flutter for OpenHarmony本身并不带有直接访问SIM卡的能力它和系统通信要借助平台通道。也就是说只要涉及SIM卡查询、状态订阅、双卡策略判断就必须自己把桥接层写出来。官方文档里关于Telephony的介绍往往是通用的真正落实到Flutter侧怎么接、事件怎么推、多卡怎么映射需要我们自己补完。这里还要重申一个边界我们做的是移动数据使用监管监管对象是用户自己SIM卡产生的流量用量数据包含本地统计、超额提醒、套餐管理等应用只读取SIM公开信息和用量数据不涉及任何对通信内容的管理也不会上传任何信息。搞清楚这个产品边界后面所有技术决策都不会走偏。2. 摸清底牌系统侧SIM信息从哪来Flutter层怎么够到它2.1 卡槽、SIM卡与状态先梳理清楚三级信息在OpenHarmony上做SIM管理第一步是理解系统侧的信息层级。我把它们分成三级后面的数据模型设计也完全按这个分层来。卡槽级信息描述设备有几个卡槽、每个卡槽处于什么状态。比如设备支持双卡双待那么在卡槽维度上会有卡槽1、卡槽2两个位置每个位置可能插入SIM卡也可能是空卡槽。系统还会额外给出哪个卡槽是默认数据卡槽这个字段在流量归属判断中极其关键。卡级信息描述当前插入的这张SIM卡本身是什么。包括ICCID、IMSI、运营商名称、注册的电话号码等。这块信息通常由系统Telephony服务读取部分接口以JSON字符串返回也可能以结构化对象返回不同系统版本存在差异。状态级信息描述这张卡当前能不能正常使用。正常状态下SIM卡就绪可以正常注册网络也可能是缺卡、PIN锁定、PUK锁定等异常状态。对移动数据监管App来说状态变化直接影响流量统计和UI展示。举例来说用户拔出SIM卡再插回去卡片状态会经历从就绪到缺卡再到就绪的过程如果App不响应这个变化本地流量统计就会算错时间范围。理解了这个三级结构再去读系统Telephony相关接口就能对号入座。需要提醒的是不要假设所有设备都支持全部接口低端设备、双卡双待实现不同返回的字段可能缺失代码里必须有兜底默认值。2.2 MethodChannel、EventChannel还是FFI渠道选型Flutter与OpenHarmony系统通信的常见方式有三种MethodChannel、EventChannel、FFI。选型原则其实很简单搞清楚通信是一次性还是持续性的即可。SIM信息读取是一次性请求用户进入页面、点击刷新时发起查询完返回结果这种场景用MethodChannel最合适。它的模型是一个方法名加一组参数Dart侧调用平台侧处理通过回调返回数据双方是典型的请求-响应关系。SIM状态变化监听是持续性的例如插拔卡、卡锁定、默认数据卡切换这类事件需要从系统侧源源不断推送到Flutter侧对应EventChannel。它建立的是一条事件流平台侧有事件就发射Dart侧订阅接收。FFI则不适合这个场景。FFI适合高频计算或者必须紧贴系统底层能力的场景比如图像处理、加解密。SIM卡信息查询本身是低频操作走平台通道的通信开销完全可以接受没必要用FFI去绕一层。通信方式适用场景在本项目中的用途MethodChannel一次请求一次响应读取SIM列表、查询默认数据卡EventChannel系统事件持续推送监听SIM插拔、状态变化、数据卡切换FFI高频计算、底层库调用本场景不使用2.3 不能照搬Android写法的三个差异最初我们尝试把Android平台上的SIM管理逻辑平移过来很快就发现三条关键差异。第一是权限模型不同OpenHarmony的敏感权限申请时机、声明方式与Android存在差异读取SIM信息需要在应用配置文件中声明并且在运行时向用户申请授权。第二是接口命名和返回结构不同Android里很多接口直接返回Parcelable对象OpenHarmony里部分接口返回JSON字符串字段名也不一致跨平台层必须做归一化。第三是事件订阅机制不同Android有系统广播机制OpenHarmony需要主动注册Telephony事件回调并且要在生命周期里正确注销否则会出现内存泄漏或重复回调。这三条差异直接影响桥接层设计后面几节会展开讲具体实现。3. 桥接层拆解ArkTS侧说我能读Dart侧说我要读3.1 平台侧与Flutter侧各管什么桥接层最容易犯的错误是职责混乱。我们最终定了这样一个分工平台侧只做三件事封装Telephony查询、做轻量缓存、发射SIM状态变更事件。所有业务判断比如流量应该算在哪张卡上当前状态下UI应该展示什么全部放到Flutter侧。为什么这样分因为平台通道的通信成本客观存在如果业务判断放平台侧每增加一个规则就要同步改两端代码还要重新打包联调。Flutter侧才是适合做业务迭代的地方。与此同时轻量缓存放平台侧是有必要的因为某个Telephony接口可能被多次调用比如进入页面时读一次、用户手动刷新时读一次、事件回调后再补一次每次都现查系统缓存会增加不必要的开销和失败概率。还有一个隐性约定平台侧不做任何数据持久化。SIM卡信息是否要落盘、落盘之后怎么脱敏这属于Flutter侧业务逻辑平台侧拿到原始数据就返回不做加工。3.2 Dart侧通道封装方法名、参数与异常约定Dart侧这层要解决三件事定义清晰的通道名和方法名、定义SIM卡的数据模型、统一定义异常类型。通道名我习惯带模块前缀直接命名为sim_manager事件通道命名为sim_manager/events。方法名按动作来定义getSimList对应读取全部卡槽的SIM信息getDefaultDataSim查询当前默认数据卡simStateChange是事件名而不是方法名。这样的命名约定在桥接层扩大时很好用。class SimCardInfo { final int slotIndex; final String? iccId; final String? imsi; final String? carrierName; final String? phoneNumber; final int state; final bool isDefaultDataSim; SimCardInfo({ required this.slotIndex, this.iccId, this.imsi, this.carrierName, this.phoneNumber, required this.state, required this.isDefaultDataSim, }); factory SimCardInfo.fromMap(MapString, dynamic map) { return SimCardInfo( slotIndex: map[slotIndex] as int? ?? 0, iccId: map[iccId] as String?, imsi: map[imsi] as String?, carrierName: map[carrierName] as String?, phoneNumber: map[phoneNumber] as String?, state: map[state] as int? ?? 0, isDefaultDataSim: map[isDefaultDataSim] as bool? ?? false, ); } }调用侧需要处理好异常。MethodChannel调用失败时通常会抛PlatformException我们把它统一转成业务异常SimManagerException携带错误码和可读信息。这样UI层只需要捕获一个异常类型不需要关心平台侧到底抛了什么。static const MethodChannel _channel MethodChannel(sim_manager); FutureListSimCardInfo getSimList() async { try { final Listdynamic? list await _channel.invokeMethod(getSimList); return list ?.map((e) SimCardInfo.fromMap( MapString, dynamic.from(e as Map))) .toList() ?? []; } on PlatformException catch (e) { throw SimManagerException(e.code, e.message); } }3.3 ArkTS侧实现注册时机、异步回调和错误码ArkTS侧是桥接层的另一半。首先要注意注册时机MethodChannel和EventChannel的注册要放在Ability生命周期里确保页面还没有发起调用时通道已经就绪。我们的做法是在onCreate里初始化通道在onDestroy里释放资源和取消订阅。其次要处理异步查询。Telephony的查询接口大多是异步的平台通道的Result对象必须在异步完成后才调用不能在方法入口处提前返回。同时还要注意一次调用只能触发一次result()否则会引发运行时错误。错误处理也要统一查询失败时调用error方法并给出错误码例如SIM_READ_FAILED、PERMISSION_DENIEDFlutter侧拿错误码做后续提示。const methodChannel new MethodChannel(sim_manager); methodChannel.onMethodCall(async (call) { if (call.method getSimList) { try { const simList await getSimListFromTelephony(); call.result(simList); } catch (e) { call.error(SIM_READ_FAILED, read SIM fail: ${e.message}); } } });这里有个小细节给Flutter侧返回数据时尽量返回数组或Map这样的组合结构不要返回一个巨大的JSON字符串再让Flutter侧做字符串解析。结构化对象在类型映射上损耗更小代码也更容易维护。4. 核心功能落地SIM读取、卡槽识别与流量归属统计4.1 从系统返回数据到Flutter模型的完整链路桥接层跑通后核心功能就变成了数据流转系统Telephony接口的数据通过平台通道进入Flutter再被转换成SimCardInfo模型最终渲染到界面。平台侧返回的数据字段与Flutter模型的映射要提前定好。我建议两边使用同一套字段名也就是驼峰命名避免在平台转换层做字段重命名减少出错。要注意的有几点字段可能缺失必须给默认值ICCID、IMSI这类敏感标识符在UI上要做脱敏处理比如只显示前四位和后四位全量数据仅用于本地逻辑判断电话号码可能为空要处理好空值的UI展示。4.2 卡槽与默认数据卡怎么判断谁的流量流量归属统计是整个监管助手的核心而它依赖一个关键概念默认数据卡。很多双卡手机的语音通话卡和数据上网卡是分开设置的流量消耗只发生在默认数据卡上。那么在一个统计周期内App判定这张SIM卡用了多少流量先要确认当前周期里哪张卡是默认数据卡。如果用户中途切换了默认数据卡那么切换前后流量应当分别累加到两张卡各自的统计维度上。实际操作中我们采用了一条保守策略每次查询SIM列表时都检查与缓存中的默认数据卡是否一致发现变化时立即生成一次卡切换事件并且触发一次流量快照把切换前累计流量落库切换后重新累计。这样的处理能保证月度报表不会把切换前后的流量混在一起。场景处理策略需要特别注意的坑单卡设备流量归属唯一直接累计不需要处理切换但要兼容空卡槽双卡、数据卡固定只有默认数据卡累计流量语音卡状态变化不应影响流量统计双卡、数据卡中途切换切换时做流量快照并落库快照必须和事件同周期避免漏算临时拔出SIM卡再插入重新读取SIM列表核对ICCID插回不同卡时要防止数据串账特别提醒一点ICCID的核对非常重要。用户如果拔出一张卡再插入另一张卡的标识会变化流量统计必须落到正确的卡上而不是凭卡槽位置判断。卡槽位置可能不变但卡已经换了这正是SIM管理里最容易出数据事故的地方。4.3 状态监听与UI联动插拔卡、锁卡、切换运营商SIM状态监听用EventChannel实现。Dart侧订阅事件流后UI层监听状态变化刷新卡片视图和流量统计。事件流里需要区分事件类型比如SIM_STATE_CHANGED、DEFAULT_DATA_SIM_CHANGED、SIM_LOADED。static const EventChannel _eventChannel EventChannel(sim_manager/events); StreamSimEvent simEvents() { return _eventChannel .receiveBroadcastStream() .map((event) SimEvent.fromMap(MapString, dynamic.from(event))); }事件流有一个必须处理的细节防抖。系统的Telephony事件可能连续触发比如SIM刚插回时会伴随读卡、注册、状态就绪等多个事件如果每个事件都触发一次完整查询和UI刷新会造成界面频繁闪动。我们采用一个简单策略事件到达后先重置一个300毫秒的定时器时间窗口内的事件全部合并窗口结束后再执行一次查询刷新。这个方法非常管用系统事件再密集也不会导致界面抖动。5. 真机调试与高频踩坑清单5.1 Permission声明调不通多半不是代码问题项目早期我们遇到一次非常典型的代码没问题但结果就是空的故障Dart侧调用MethodChannel平台侧也走到了查询逻辑但返回的数据永远是空列表。排查了很久发现是系统权限配置没有加全。OpenHarmony的SIM信息读取需要声明对应的敏感权限还要在运行时向用户申请授权两者缺一不可。这件事的教训是遇到Telephony相关的查询返回空、返回失败第一优先级不是看代码逻辑而是确认权限声明和授权状态。可以在平台侧加一步权限检查逻辑检测到未授权时直接向Flutter侧返回明确错误码而不是返回空数据这样问题定位会快很多。5.2 类型映射与回调死锁桥接层的两个经典问题在SIM管理项目里也遇到了。一个是类型映射平台侧返回的整型字段在Dart侧被解析成其他类型或者布尔值变成了字符串这种问题一般通过严格限定两边字段类型和写测试用例来预防。另一个是回调死锁MethodChannel的回调如果在异步查询还没结束时就被垃圾回收会导致Dart侧一直等待平台返回表现为整个方法卡住。做异步查询时必须持有Result引用并且在回调结束后及时置空。5.3 我们在测试中遇到的八个问题问题现象根因解决办法查不到SIM信息返回空列表权限未配置或未授权补齐声明增加授权提示流程双卡列表顺序不稳定两次查询卡顺序不一致系统返回顺序依赖卡槽初始化时机按卡槽索引排序不依赖返回顺序热插拔后无事件拔出SIM卡UI无变化事件订阅未注册到正确回调域检查事件注册与生命周期绑定切换数据卡不生效默认数据卡字段未更新业务缓存未失效主动刷新SIM列表比对缓存回调只触发一次第二次查询无响应Result被提前释放持有Result引用完成为止ICCID显示不全UI显示乱码多语言区域编码问题统一使用UTF-8处理返回字符串模拟器总是缺卡无法验证多卡逻辑模拟器不支持真实SIM用双卡真机测试准备两张测试卡锁卡后无法恢复状态停留在锁定事件丢失后状态未重新同步进入前台主动刷新一次SIM列表5.4 调试工具与测试策略SIM卡管理模块的调试核心建议是准备一套可控的物理环境。我们的做法是准备一台双卡真机、两张不同运营商的测试卡在测试过程中交替进行插卡、拔卡、换卡、锁定SIM卡、切换默认数据卡等操作每操作一步就观察Flutter侧日志和UI状态。系统日志在排查平台侧问题的时候价值很大可以从日志中看到Telephony服务在事件触发时的内部状态。Flutter侧则打印通道事件日志两边时间线对齐就能快速定位是事件没从系统触发还是事件到了通道层却被丢弃。6. 从零到能显示双卡信息一套可直接照抄的上手路径6.1 最小演示工程搭建步骤如果你也要在OpenHarmony上用Flutter做SIM卡相关功能我建议先搭一个最小演示工程验证通道和读取能力再往里加业务逻辑。第一步创建一个Flutter工程确认Flutter for OpenHarmony环境能正常构建。第二步在平台侧注册MethodChannel和EventChannel只实现getSimList一个方法。第三步在Dart侧写一个简单的页面调用getSimList并把返回的卡信息展示成列表。第四步真机运行先确认能正常显示卡列表再逐步加入事件监听和双卡策略。不要在这之前急着写流量统计。桥接层没有验证稳定之前所有上层业务都是空中楼阁。这个最小工程花三小时能跑通但会为后续节省大量排查时间。6.2 从能读卡到能做流量监管的扩展清单桥接层稳定后就可以按下面清单逐步扩展功能。第一步接入SIM状态监听完成插拔卡和锁卡的UI联动。第二步读取默认数据卡建立卡槽与流量统计的对应关系。第三步做月度流量报表把SIM卡标识与流量记录关联起来。第四步做超额提醒在流量接近套餐上限时触发通知。第五步如果用户有副卡识别需求可以根据运营商名称或自定义标签实现。每一步都不难难的是把每一步做的数据决策放在同一个框架里。SIM管理模块在整个App里看起来只是一个小功能但实际上它是所有流量统计功能的地基。最后分享一个我们在真实业务中总结下来的经验SIM卡管理模块的验收一定要包含异常场景不只是正常的插卡读卡。拔卡、换卡、锁卡、切换数据卡这类操作恰恰是用户真正使用时大概率会遇到的情况也是代码最容易出错的地方。我们在联调阶段把异常场景用例补齐之后整个模块的稳定性明显提升线上反馈的问题也少了很多。如果你正在做类似功能希望这份实践记录能让你少走几段弯路。 
长河君 · 2026/10/15 12:11:52 · 阅读 1.2k Flutter+OpenHarmony SIM卡管理实战：桥接层与双卡流量统计
做了三个月的项目先交代背景我们团队要给OpenHarmony设备做一款移动数据使用监管助手技术栈选定Flutter for OpenHarmony核心功能之一就是SIM卡管理。最初我预估这款功能就是读一读运营商、拿一下IMSI真正落地方案时才发现从系统Telephony能力到Flutter端的桥接、卡槽识别、状态监听、双卡流量归属每一步都有决策要做。这篇文章就把我们这版SIM卡管理模块从设计到落地的完整路径讲清楚包含桥接层的代码骨架、踩过的坑和最终的调试方法给准备在OpenHarmony上用Flutter做通信类功能的团队一份可参考的实战记录。1. 立项前先想清楚为什么移动数据监管类App要把SIM卡管理单独拆出来做1.1 表面需求是读卡真实需求是流量算在谁的账上很多团队拿到移动数据使用监管助手这类需求时第一反应是打开系统文档找SIM卡信息查询接口返回什么就显示什么。这其实漏掉了产品的核心逻辑用户关心的不是ICCID或者IMSI本身而是我这个月到底用了多少流量、这笔流量算在主卡还是副卡头上、流量快用完了系统能不能提醒我。举几个实际场景。家里给孩子配了手机用的是共享流量套餐家长需要在App里看到孩子当前用的是哪张卡、这个月已经消耗了多少共享流量。双卡用户很可能一张卡用于日常上网、另一张卡用于收验证码和通话App需要正确识别流量消耗归属。企业给员工配发工作手机时也会把工作SIM和个人SIM分开月底要看工作卡的使用情况。这些需求都指向同一件事SIM卡信息必须和流量统计体系强绑定。也就是说SIM卡管理在架构上不是一个独立的、可插拔的读取工具它是流量统计的上游模块。读取到的卡槽编号、卡状态、默认数据卡标识这些字段会在后续被流量查询、月度报表、超额提醒这些功能反复引用。如果一开始不把SIM管理拆成独立模块而是把Telephony查询散落在各个页面里双卡场景一出来代码就会变得非常难维护。1.2 为什么偏偏用Flutter for OpenHarmony这个选择不是拍脑袋。首先是团队技能栈的复用UI层我们已经有比较成熟的Flutter组件积累统计图表、卡片列表这类界面用Flutter写效率很高。其次是终端覆盖问题OpenHarmony的设备形态不只有手机还有平板、带屏设备、信息栏设备Flutter的分支能保证同一套UI逻辑跑在多个形态上不用为每个形态单独维护一套前端代码。但选型也意味着承担一个现实Flutter for OpenHarmony本身并不带有直接访问SIM卡的能力它和系统通信要借助平台通道。也就是说只要涉及SIM卡查询、状态订阅、双卡策略判断就必须自己把桥接层写出来。官方文档里关于Telephony的介绍往往是通用的真正落实到Flutter侧怎么接、事件怎么推、多卡怎么映射需要我们自己补完。这里还要重申一个边界我们做的是移动数据使用监管监管对象是用户自己SIM卡产生的流量用量数据包含本地统计、超额提醒、套餐管理等应用只读取SIM公开信息和用量数据不涉及任何对通信内容的管理也不会上传任何信息。搞清楚这个产品边界后面所有技术决策都不会走偏。2. 摸清底牌系统侧SIM信息从哪来Flutter层怎么够到它2.1 卡槽、SIM卡与状态先梳理清楚三级信息在OpenHarmony上做SIM管理第一步是理解系统侧的信息层级。我把它们分成三级后面的数据模型设计也完全按这个分层来。卡槽级信息描述设备有几个卡槽、每个卡槽处于什么状态。比如设备支持双卡双待那么在卡槽维度上会有卡槽1、卡槽2两个位置每个位置可能插入SIM卡也可能是空卡槽。系统还会额外给出哪个卡槽是默认数据卡槽这个字段在流量归属判断中极其关键。卡级信息描述当前插入的这张SIM卡本身是什么。包括ICCID、IMSI、运营商名称、注册的电话号码等。这块信息通常由系统Telephony服务读取部分接口以JSON字符串返回也可能以结构化对象返回不同系统版本存在差异。状态级信息描述这张卡当前能不能正常使用。正常状态下SIM卡就绪可以正常注册网络也可能是缺卡、PIN锁定、PUK锁定等异常状态。对移动数据监管App来说状态变化直接影响流量统计和UI展示。举例来说用户拔出SIM卡再插回去卡片状态会经历从就绪到缺卡再到就绪的过程如果App不响应这个变化本地流量统计就会算错时间范围。理解了这个三级结构再去读系统Telephony相关接口就能对号入座。需要提醒的是不要假设所有设备都支持全部接口低端设备、双卡双待实现不同返回的字段可能缺失代码里必须有兜底默认值。2.2 MethodChannel、EventChannel还是FFI渠道选型Flutter与OpenHarmony系统通信的常见方式有三种MethodChannel、EventChannel、FFI。选型原则其实很简单搞清楚通信是一次性还是持续性的即可。SIM信息读取是一次性请求用户进入页面、点击刷新时发起查询完返回结果这种场景用MethodChannel最合适。它的模型是一个方法名加一组参数Dart侧调用平台侧处理通过回调返回数据双方是典型的请求-响应关系。SIM状态变化监听是持续性的例如插拔卡、卡锁定、默认数据卡切换这类事件需要从系统侧源源不断推送到Flutter侧对应EventChannel。它建立的是一条事件流平台侧有事件就发射Dart侧订阅接收。FFI则不适合这个场景。FFI适合高频计算或者必须紧贴系统底层能力的场景比如图像处理、加解密。SIM卡信息查询本身是低频操作走平台通道的通信开销完全可以接受没必要用FFI去绕一层。通信方式适用场景在本项目中的用途MethodChannel一次请求一次响应读取SIM列表、查询默认数据卡EventChannel系统事件持续推送监听SIM插拔、状态变化、数据卡切换FFI高频计算、底层库调用本场景不使用2.3 不能照搬Android写法的三个差异最初我们尝试把Android平台上的SIM管理逻辑平移过来很快就发现三条关键差异。第一是权限模型不同OpenHarmony的敏感权限申请时机、声明方式与Android存在差异读取SIM信息需要在应用配置文件中声明并且在运行时向用户申请授权。第二是接口命名和返回结构不同Android里很多接口直接返回Parcelable对象OpenHarmony里部分接口返回JSON字符串字段名也不一致跨平台层必须做归一化。第三是事件订阅机制不同Android有系统广播机制OpenHarmony需要主动注册Telephony事件回调并且要在生命周期里正确注销否则会出现内存泄漏或重复回调。这三条差异直接影响桥接层设计后面几节会展开讲具体实现。3. 桥接层拆解ArkTS侧说我能读Dart侧说我要读3.1 平台侧与Flutter侧各管什么桥接层最容易犯的错误是职责混乱。我们最终定了这样一个分工平台侧只做三件事封装Telephony查询、做轻量缓存、发射SIM状态变更事件。所有业务判断比如流量应该算在哪张卡上当前状态下UI应该展示什么全部放到Flutter侧。为什么这样分因为平台通道的通信成本客观存在如果业务判断放平台侧每增加一个规则就要同步改两端代码还要重新打包联调。Flutter侧才是适合做业务迭代的地方。与此同时轻量缓存放平台侧是有必要的因为某个Telephony接口可能被多次调用比如进入页面时读一次、用户手动刷新时读一次、事件回调后再补一次每次都现查系统缓存会增加不必要的开销和失败概率。还有一个隐性约定平台侧不做任何数据持久化。SIM卡信息是否要落盘、落盘之后怎么脱敏这属于Flutter侧业务逻辑平台侧拿到原始数据就返回不做加工。3.2 Dart侧通道封装方法名、参数与异常约定Dart侧这层要解决三件事定义清晰的通道名和方法名、定义SIM卡的数据模型、统一定义异常类型。通道名我习惯带模块前缀直接命名为sim_manager事件通道命名为sim_manager/events。方法名按动作来定义getSimList对应读取全部卡槽的SIM信息getDefaultDataSim查询当前默认数据卡simStateChange是事件名而不是方法名。这样的命名约定在桥接层扩大时很好用。class SimCardInfo { final int slotIndex; final String? iccId; final String? imsi; final String? carrierName; final String? phoneNumber; final int state; final bool isDefaultDataSim; SimCardInfo({ required this.slotIndex, this.iccId, this.imsi, this.carrierName, this.phoneNumber, required this.state, required this.isDefaultDataSim, }); factory SimCardInfo.fromMap(MapString, dynamic map) { return SimCardInfo( slotIndex: map[slotIndex] as int? ?? 0, iccId: map[iccId] as String?, imsi: map[imsi] as String?, carrierName: map[carrierName] as String?, phoneNumber: map[phoneNumber] as String?, state: map[state] as int? ?? 0, isDefaultDataSim: map[isDefaultDataSim] as bool? ?? false, ); } }调用侧需要处理好异常。MethodChannel调用失败时通常会抛PlatformException我们把它统一转成业务异常SimManagerException携带错误码和可读信息。这样UI层只需要捕获一个异常类型不需要关心平台侧到底抛了什么。static const MethodChannel _channel MethodChannel(sim_manager); FutureListSimCardInfo getSimList() async { try { final Listdynamic? list await _channel.invokeMethod(getSimList); return list ?.map((e) SimCardInfo.fromMap( MapString, dynamic.from(e as Map))) .toList() ?? []; } on PlatformException catch (e) { throw SimManagerException(e.code, e.message); } }3.3 ArkTS侧实现注册时机、异步回调和错误码ArkTS侧是桥接层的另一半。首先要注意注册时机MethodChannel和EventChannel的注册要放在Ability生命周期里确保页面还没有发起调用时通道已经就绪。我们的做法是在onCreate里初始化通道在onDestroy里释放资源和取消订阅。其次要处理异步查询。Telephony的查询接口大多是异步的平台通道的Result对象必须在异步完成后才调用不能在方法入口处提前返回。同时还要注意一次调用只能触发一次result()否则会引发运行时错误。错误处理也要统一查询失败时调用error方法并给出错误码例如SIM_READ_FAILED、PERMISSION_DENIEDFlutter侧拿错误码做后续提示。const methodChannel new MethodChannel(sim_manager); methodChannel.onMethodCall(async (call) { if (call.method getSimList) { try { const simList await getSimListFromTelephony(); call.result(simList); } catch (e) { call.error(SIM_READ_FAILED, read SIM fail: ${e.message}); } } });这里有个小细节给Flutter侧返回数据时尽量返回数组或Map这样的组合结构不要返回一个巨大的JSON字符串再让Flutter侧做字符串解析。结构化对象在类型映射上损耗更小代码也更容易维护。4. 核心功能落地SIM读取、卡槽识别与流量归属统计4.1 从系统返回数据到Flutter模型的完整链路桥接层跑通后核心功能就变成了数据流转系统Telephony接口的数据通过平台通道进入Flutter再被转换成SimCardInfo模型最终渲染到界面。平台侧返回的数据字段与Flutter模型的映射要提前定好。我建议两边使用同一套字段名也就是驼峰命名避免在平台转换层做字段重命名减少出错。要注意的有几点字段可能缺失必须给默认值ICCID、IMSI这类敏感标识符在UI上要做脱敏处理比如只显示前四位和后四位全量数据仅用于本地逻辑判断电话号码可能为空要处理好空值的UI展示。4.2 卡槽与默认数据卡怎么判断谁的流量流量归属统计是整个监管助手的核心而它依赖一个关键概念默认数据卡。很多双卡手机的语音通话卡和数据上网卡是分开设置的流量消耗只发生在默认数据卡上。那么在一个统计周期内App判定这张SIM卡用了多少流量先要确认当前周期里哪张卡是默认数据卡。如果用户中途切换了默认数据卡那么切换前后流量应当分别累加到两张卡各自的统计维度上。实际操作中我们采用了一条保守策略每次查询SIM列表时都检查与缓存中的默认数据卡是否一致发现变化时立即生成一次卡切换事件并且触发一次流量快照把切换前累计流量落库切换后重新累计。这样的处理能保证月度报表不会把切换前后的流量混在一起。场景处理策略需要特别注意的坑单卡设备流量归属唯一直接累计不需要处理切换但要兼容空卡槽双卡、数据卡固定只有默认数据卡累计流量语音卡状态变化不应影响流量统计双卡、数据卡中途切换切换时做流量快照并落库快照必须和事件同周期避免漏算临时拔出SIM卡再插入重新读取SIM列表核对ICCID插回不同卡时要防止数据串账特别提醒一点ICCID的核对非常重要。用户如果拔出一张卡再插入另一张卡的标识会变化流量统计必须落到正确的卡上而不是凭卡槽位置判断。卡槽位置可能不变但卡已经换了这正是SIM管理里最容易出数据事故的地方。4.3 状态监听与UI联动插拔卡、锁卡、切换运营商SIM状态监听用EventChannel实现。Dart侧订阅事件流后UI层监听状态变化刷新卡片视图和流量统计。事件流里需要区分事件类型比如SIM_STATE_CHANGED、DEFAULT_DATA_SIM_CHANGED、SIM_LOADED。static const EventChannel _eventChannel EventChannel(sim_manager/events); StreamSimEvent simEvents() { return _eventChannel .receiveBroadcastStream() .map((event) SimEvent.fromMap(MapString, dynamic.from(event))); }事件流有一个必须处理的细节防抖。系统的Telephony事件可能连续触发比如SIM刚插回时会伴随读卡、注册、状态就绪等多个事件如果每个事件都触发一次完整查询和UI刷新会造成界面频繁闪动。我们采用一个简单策略事件到达后先重置一个300毫秒的定时器时间窗口内的事件全部合并窗口结束后再执行一次查询刷新。这个方法非常管用系统事件再密集也不会导致界面抖动。5. 真机调试与高频踩坑清单5.1 Permission声明调不通多半不是代码问题项目早期我们遇到一次非常典型的代码没问题但结果就是空的故障Dart侧调用MethodChannel平台侧也走到了查询逻辑但返回的数据永远是空列表。排查了很久发现是系统权限配置没有加全。OpenHarmony的SIM信息读取需要声明对应的敏感权限还要在运行时向用户申请授权两者缺一不可。这件事的教训是遇到Telephony相关的查询返回空、返回失败第一优先级不是看代码逻辑而是确认权限声明和授权状态。可以在平台侧加一步权限检查逻辑检测到未授权时直接向Flutter侧返回明确错误码而不是返回空数据这样问题定位会快很多。5.2 类型映射与回调死锁桥接层的两个经典问题在SIM管理项目里也遇到了。一个是类型映射平台侧返回的整型字段在Dart侧被解析成其他类型或者布尔值变成了字符串这种问题一般通过严格限定两边字段类型和写测试用例来预防。另一个是回调死锁MethodChannel的回调如果在异步查询还没结束时就被垃圾回收会导致Dart侧一直等待平台返回表现为整个方法卡住。做异步查询时必须持有Result引用并且在回调结束后及时置空。5.3 我们在测试中遇到的八个问题问题现象根因解决办法查不到SIM信息返回空列表权限未配置或未授权补齐声明增加授权提示流程双卡列表顺序不稳定两次查询卡顺序不一致系统返回顺序依赖卡槽初始化时机按卡槽索引排序不依赖返回顺序热插拔后无事件拔出SIM卡UI无变化事件订阅未注册到正确回调域检查事件注册与生命周期绑定切换数据卡不生效默认数据卡字段未更新业务缓存未失效主动刷新SIM列表比对缓存回调只触发一次第二次查询无响应Result被提前释放持有Result引用完成为止ICCID显示不全UI显示乱码多语言区域编码问题统一使用UTF-8处理返回字符串模拟器总是缺卡无法验证多卡逻辑模拟器不支持真实SIM用双卡真机测试准备两张测试卡锁卡后无法恢复状态停留在锁定事件丢失后状态未重新同步进入前台主动刷新一次SIM列表5.4 调试工具与测试策略SIM卡管理模块的调试核心建议是准备一套可控的物理环境。我们的做法是准备一台双卡真机、两张不同运营商的测试卡在测试过程中交替进行插卡、拔卡、换卡、锁定SIM卡、切换默认数据卡等操作每操作一步就观察Flutter侧日志和UI状态。系统日志在排查平台侧问题的时候价值很大可以从日志中看到Telephony服务在事件触发时的内部状态。Flutter侧则打印通道事件日志两边时间线对齐就能快速定位是事件没从系统触发还是事件到了通道层却被丢弃。6. 从零到能显示双卡信息一套可直接照抄的上手路径6.1 最小演示工程搭建步骤如果你也要在OpenHarmony上用Flutter做SIM卡相关功能我建议先搭一个最小演示工程验证通道和读取能力再往里加业务逻辑。第一步创建一个Flutter工程确认Flutter for OpenHarmony环境能正常构建。第二步在平台侧注册MethodChannel和EventChannel只实现getSimList一个方法。第三步在Dart侧写一个简单的页面调用getSimList并把返回的卡信息展示成列表。第四步真机运行先确认能正常显示卡列表再逐步加入事件监听和双卡策略。不要在这之前急着写流量统计。桥接层没有验证稳定之前所有上层业务都是空中楼阁。这个最小工程花三小时能跑通但会为后续节省大量排查时间。6.2 从能读卡到能做流量监管的扩展清单桥接层稳定后就可以按下面清单逐步扩展功能。第一步接入SIM状态监听完成插拔卡和锁卡的UI联动。第二步读取默认数据卡建立卡槽与流量统计的对应关系。第三步做月度流量报表把SIM卡标识与流量记录关联起来。第四步做超额提醒在流量接近套餐上限时触发通知。第五步如果用户有副卡识别需求可以根据运营商名称或自定义标签实现。每一步都不难难的是把每一步做的数据决策放在同一个框架里。SIM管理模块在整个App里看起来只是一个小功能但实际上它是所有流量统计功能的地基。最后分享一个我们在真实业务中总结下来的经验SIM卡管理模块的验收一定要包含异常场景不只是正常的插卡读卡。拔卡、换卡、锁卡、切换数据卡这类操作恰恰是用户真正使用时大概率会遇到的情况也是代码最容易出错的地方。我们在联调阶段把异常场景用例补齐之后整个模块的稳定性明显提升线上反馈的问题也少了很多。如果你正在做类似功能希望这份实践记录能让你少走几段弯路。