最近在推进一个孵化项目的鸿蒙化时整理依赖清单发现 numbers_to_text 这个 Flutter 三方库在鸿蒙侧基本是“裸奔”状态——Dart 代码本身能跑但牵涉系统语言、金额格式、本地化文本的场景统统要手动补适配。这个库解决的问题很朴素但特别容易被忽略把1234567.89变成one million two hundred thirty-four thousand five hundred sixty-seven and eighty-nine cents。听起来像“格式化字符串”的小事但跑过一遍发票核对、合同金额播报、财务无障碍朗读之后你会意识到这是一层被低估的“语言级直观”底座。这篇文章会把我在鸿蒙适配过程中的完整思路和实操记录下来为什么需要这个适配、numbers_to_text 内部到底怎么组织数字文本、鸿蒙侧有哪些坑、最终怎么落地。适合两类人看一类是正准备把现有 Flutter 业务搬到鸿蒙的开发者另一类是财务、票据、无障碍场景里被“数字读法”反复折磨的后端或客户端同学。1. 为什么要把 numbers_to_text 搬到鸿蒙上1.1 数字转文本在真实业务里的位置很多开发者第一次接触 numbers_to_text 是在做“金额大写”、“报销单文字化”、“语音播报账单”这类需求时。它做的事情一句话就能讲清楚把阿拉伯数字转换成自然语言文本。在英文环境下是1,234.56转one thousand two hundred thirty-four and fifty-six cents在多语言环境下它还会根据选定的 language 参数输出对应语言的文本规则。你可能觉得这不就是个NumberFormat加几张映射表的事真做过财务类需求的人不会这么想。财务场景里数字不只是给人看的还承担着“防篡改、可复核、易朗读”的责任。合同里的大写金额、银行回单里的英文金额、ERP 系统导出的英文发票摘要这些地方只要拼接规则错一个ty或者teen整张单据就得作废重审。numbers_to_text 的价值在于它把这套规则封装成了可复用的组件而不是每个业务方各写各的intToWords()。在鸿蒙生态里这个需求变得更加现实。鸿蒙应用现在大量承接政企办公、金融票据、无障碍辅助类场景这些场景恰恰是“数字读法”的高频使用地。但三方库生态没有完全跟上Flutter 侧的纯 Dart 包虽然可以编译过却缺少对鸿蒙系统语言配置、金额进制、Locale 动态切换的原生感知能力。1.2 鸿蒙 Flutter 生态里“库有缺口”的现实先明确一个背景鸿蒙 NEXT 不再兼容 Android 运行时Flutter 应用要跑在鸿蒙上需要使用适配过的 Flutter 引擎版本当前主流做法是使用社区维护的鸿蒙 Flutter 引擎分支。在这个引擎上Dart 层的标准库绝大多数仍然可用但凡是依赖PlatformDispatcher.locale、MethodChannel、EventChannel与系统侧互动的能力都可能存在版本差异。numbers_to_text 本身是纯 Dart 包按理说“直接就能跑”。我第一次也是这么以为的改完依赖一编译确实能出包。但真正跑业务用例时问题就来了鸿蒙系统语言设置为简体中文时Dart 层拿到的 locale 经常不是预期的zh_CN而 numbers_to_text 对中文的支持又不像英文那么完善再叠加财务场景里的“四舍五入规则不一致”、“货币符号取不到系统配置”这个库在鸿蒙上的可用性其实只有一半。所以“鸿蒙化适配”不是把包塞进依赖列表就完事而是要重新梳理这个库的输入输出边界哪些逻辑可以留在 Dart 层直接用哪些必须通过平台通道从鸿蒙系统侧读取哪些需要针对鸿蒙的财务场景做参数规范化。1.3 “语言级直观”到底指什么我一直在提“语言级直观”这个词不是包装出来的概念而是真实体验差异。人眼识别1,234,567.89需要数三次逗号才能确定是“百万级”但人耳或人脑听到one million two hundred thirty-four thousand five hundred sixty-seven and eighty-nine cents时数量级是即时成立的。对核对数字的人、视障用户、以及需要把金额语音播报出来的 POS 机场景来说这种表达方式直接从“看符号”升级到“读语言”理解成本和出错率都会下降。财务治理底座的身份也来源于此一套稳定的数字转文本能力能统一所有业务模块的数字表达规则。报销单、发票摘要、审计日志、合同模板都不会出现“一个模块写 Thirteen另一个模块写 thirteen”这种低级不一致。适配鸿蒙就是在新的系统生态里把这套一致性底座重新立起来。2. numbers_to_text 的核心实现拆解2.1 整数数字的分组与拼接规则想高效适配一个库第一步是看懂它的实现骨架。numbers_to_text 对整数的处理遵循英语数字表达的标准逻辑三位一组thousand, million, billion, trillion组内再按百位、十位、个位拼接。这个结构和中文数字的“万进制”完全不同所以适配时绝不能想当然。以1234567为例它内部的处理路径大致是按千分位分组1 | 234 | 567最高组单独处理1 - one million第二组234 - two hundred thirty-four thousand第三组567 - five hundred sixty-seven拼接时处理连字符和空格得到one million two hundred thirty-four thousand five hundred sixty-seven这个“按三位分组”的逻辑很像我们记电话号码的方式——不是一口气读 11 位数字而是拆成 3-4-4 或者 3-3-5 这样的小段。numbers_to_text 做得好的一点是把hundred、and、连字符twenty-four、teen 和 ty 的边界都收敛到了内部规则里外部调用不需要关心这些细节。但边界情况不少。比如1000和1100的读法分别是one thousand和one thousand one hundred而1001是one thousand one0需要单独处理为zero负数依赖signed: true参数控制。这些细节在普通显示场景无所谓但在财务场景里每个单词都影响审计文本的准确性。2.2 小数、分数、货币与符号处理的边界整数只是第一层财务场景真正棘手的是小数、分数与货币的编排。numbers_to_text 提供了几个入口方法numberToText处理整数、floatToText处理带小数的数值、moneyToText处理金额、fractionToText处理分数。floatToText的逻辑核心是将小数部分按“位”展开而不是按“值”展开。比如3.14会输出three point one four这种读法在计量场景更稳妥3.5则可以输出three point five。分数场景里1/2被读作one half1/4是one quarter这依赖预置的“特殊分数词表”。moneyToText是最有财务味道的方法。它会把整数部分按原逻辑转文本小数部分作为cents或pence处理并拼接货币单位。比如 USD 金额1,234.56读作one thousand two hundred thirty-four dollars and fifty-six cents。这里涉及两个容易踩坑的点货币代码到货币名称的映射USD - dollarEUR - euro是否完整以及“零头”与整数部分的连接词and在不同语言里是否一致。适配鸿蒙时这些边界一个都不能省。我见过生产事故某个系统把0.01在英文场景下输出成zero point zero one导致客户拒收对账单。真正专业的表现应该是zero dollars and one cent这样既符合财务规范又能被审计系统解析的文本。2.3 一套可移植的“数字-文本映射引擎”设计numbers_to_text 给我们的最大启示是它把“数字 - 文本”这件事抽象成了“分位 映射 连词”的三层引擎。分位层负责决定数量级单位thousand/million/billion映射层负责把 0-999 的每个数字块转成词串连词层负责处理空格、连字符、and等语言习惯。理解这个抽象对鸿蒙适配极其关键。因为我们在鸿蒙侧往往不是重新发明轮子而是把这三层逻辑中的“映射层”替换成适配鸿蒙语言偏好后的版本或者把“连词层”按中文金额大写规则重写。比如中文财务场景常见的“壹仟贰佰叁拾肆元伍角陆分”就是典型的“分位 中文法定数字映射 财务连词”的组合。我建议在适配时不要直接改三方库源码而是在你工程里做一个薄封装层把 numbers_to_text 的输出格式规范成自己团队的“标准数字文本模型”。这样后续鸿蒙引擎升级、库版本升级业务侧都不受影响。3. 鸿蒙化适配的两条技术路线与选型3.1 路线A纯 Dart 重实现推荐基础版因为 numbers_to_text 最核心的逻辑都在 Dart 层理论上鸿蒙化首选是“纯 Dart 方案”直接用包内已有的转换能力只把系统侧语言、货币配置通过轻量通道注入进来。这条路线的优势很明显实现简单、依赖少、不受鸿蒙引擎底层差异影响。你只需要解决一个问题——Dart 层怎么拿到正确的系统 Locale。鸿蒙 Flutter 引擎的PlatformDispatcher.locale在部分版本上返回的结果和 Android 上不完全一致特别是在系统语言设置成“简体中文 英文辅助”这种复合场景下Dart 层可能拿到错误的优先级。我的做法是封装一个NumberTextService它内部维护一个当前生效的 locale 状态。初始化时先读取PlatformDispatcher.instance.locale如果发现空值或异常值再用MethodChannel向鸿蒙侧发起一次查询获取系统偏好。后续系统语言切换事件通过EventChannel持续监听从而实现“不重启应用即时切换数字读法”的体验。这个方案适合绝大多数业务场景。如果你只是想让鸿蒙应用里数字表达符合当地语言习惯没有强依赖系统特有 API纯 Dart 方案足够。3.2 路线B鸿蒙原生能力桥接MethodChannel 原生类有些需求纯 Dart 解决不了。比如你的财务模块需要读取鸿蒙系统自带的货币格式化规则包含小数点符号、千分位符号、货币符号位置或者需要调用系统无障碍朗读引擎确认“当前语音通道是否正在使用”这时候就得走平台通道。鸿蒙侧插件注册的方式和 Android 类似在 ohos 工程的插件目录下新建适配类通过MethodChannel注册方法处理器然后在 Dart 侧用同样的 channel name 发起调用。需要注意鸿蒙 Flutter 引擎的 binary messenger 接口在不同版本上名字略有差异以你集成的引擎版本为准。一个典型的鸿蒙侧实现是先接收 Dart 传来的数字字符串注意用字符串而不是 double避免精度丢失再调用鸿蒙系统Intl相关能力做格式化或货币映射最后把结果返回给 Dart。路线B适合“数据源在原生侧”的场景。比如财务系统里金额的单位是鸿蒙本地化接口提供的或者需要和鸿蒙的“超级终端”能力联动把数字文本投到另一个设备上进行语音播报。这种情况用 port 通道打通两侧是不可避免的。3.3 我的选型结论两条路线的边界我划得很清楚维度纯 Dart 重实现鸿蒙原生能力桥接实现工作量小聚焦 Locale 注入中需要双端联调系统特性依赖低引擎差异影响小高依赖鸿蒙原生 API财务精度控制好数字全程在 Dart 层中注意通道传输精度多语言扩展依赖包内语言表可复用系统语言资源实时语言切换需 EventChannel 辅助原生侧原生支持我的结论是“两端结合”先用纯 Dart 方案把numbers_to_text的核心链路跑通保证 90% 的数字转文本需求在 Dart 层稳定闭环再给那几个必须读系统配置的方法留出原生通道的扩展点。这样既有稳定性又有灵活性。如果你问我现在项目里用的是哪种我可以坦白说线上是纯 Dart 方案占主导原生桥接只用于“获取系统货币符号”这一个调用点。因为财务系统的数字转文本最终要稳定要可控不要每跑一步都依赖原生侧玄学行为。4. 实操手把手完成一轮最小适配4.1 工程准备Flutter 插件 ohos 目录假设你手上已经有一个跑通鸿蒙引擎的 Flutter 工程接下来要做的第一件事是检查pubspec.yaml里有没有正确声明鸿蒙平台目录。Flutter 插件工程通常会维护android/、ios/等平台目录鸿蒙化适配时你需要增加ohos/目录结构。这个目录的核心文件是ohos/entry/src/main/ets/下的插件注册代码。用官方或社区的 ohos 插件模板初始化后你会得到一个空壳工程它负责把插件注册到鸿蒙的 Flutter 引擎上。确认这个壳工程能正常编译是后续所有适配的前提。检查点有三个第一ohos 目录里的oh-package.json5依赖名和版本是否与你集成的 Flutter 引擎版本匹配第二工具链能否识别entry模块第三运行hvigor构建时有没有报“找不到 flutter engine”的错。这三关过了进度条才真正开始。4.2 Dart 层改造Locale 获取与参数传递我建议先把 numbers_to_text 的调用封装到自己的服务类里后续适配不会污染业务代码。一个最小可用的实现大概是这样的import package:flutter/services.dart; import package:numbers_to_text/numbers_to_text.dart; class NumberTextService { NumberTextService._(); static final NumberTextService instance NumberTextService._(); NumbersToText? _enConverter; Locale? _currentLocale; // 初始化优先从 Dart 侧取 locale异常时再走原生通道 Futurevoid init() async { _currentLocale PlatformDispatcher.instance.locale; if (_currentLocale null || _currentLocale!.languageCode.isEmpty) { _currentLocale await _fetchNativeLocale(); } _enConverter NumbersToText( language: Languages.english, signed: true, decimalSeparator: _currentLocale?.decimalSeparator ?? ., ); } FutureLocale? _fetchNativeLocale() async { final String raw await _channel.invokeMethodString(getSystemLocale) ?? ; if (raw.isEmpty) return null; final parts raw.split(_); return Locale(parts.first, parts.length 1 ? parts.last : null); } String moneyToEnText(double value, String currencyCode) { // 注意严谨场景不要把 double 直接传进来这里仅为示例 return _enConverter?.moneyToText(value, currency: currencyCode) ?? value.toString(); } }这段代码做了三件事把 locale 读取逻辑收敛到一处、把 numbers_to_text 初始化收敛到一处、给原生通道留了扩展点。注意我在moneyToEnText上方用注释提示了精度问题——真实的财务金额计算建议使用Decimal类型double 只适合展示层。这是我在生产项目里踩过的坑0.1 0.2这种经典误差在金额转文本时会被放大成“某分钱对不上账”的故障。4.3 鸿蒙侧注册与方法实现如果你确实需要走原生通道补 Locale鸿蒙侧的代码逻辑很简单。在插件注册类里加一个MethodChannel处理getSystemLocale方法。核心是用鸿蒙的配置模块读取当前语言偏好然后拼成语言_地区格式返回。下面是我在鸿蒙侧使用的示意代码具体接口名以你集成引擎版本为准// 插件注册文件ohos/entry/src/main/ets/entryability/EntryBackAware.ets 等 import { MethodChannel } from ohos/flutter_ohos_plugin; import { i18n } from kit.LocalizationKit; export function registerNumberTextChannel(messenger: Object): void { const channel new MethodChannel(messenger, numbers_to_text_channel); channel.setMethodCallHandler((call, result) { if (call.method getSystemLocale) { const language i18n.getSystemLanguage(); const region i18n.getSystemRegion(); result.success(${language}_${region}); return; } result.notImplemented(); }); }这段代码的意图不是照抄而是展示“最小职责”原生侧不承担数字转文本的主逻辑只负责给出正确的语言环境。把系统的语言能力返回给 Dart由 numbers_to_text 决定按什么语言规则去转换。这样职责单一排查问题时也不用两头猜。4.4 端到端验证用例集适配完成后我强烈建议你建立一份“数字读法金标用例集”。不要只测123这种简单数字必须覆盖财务场景的所有边界。我目前维护的用例集大致长这样整数边界0-zero1,000-one thousand1,000,000-one million小数精度0.01123.45999999.99分数表达1/2-one half3/4-three quarters负数-45.67是否带minus货币表达USD 1234.56是否输出dollars and centsJPY这类无小数货币是否省略小数段大数压测trillion级别是否能正确输出不发生整数溢出语言切换系统语言从英文切到中文后调用结果是否符合预期每个用例在提交代码前都要跑一遍。这个技术债不还后面每次升级引擎版本都会心里发毛。5. 适配过程中的常见问题与排查实录5.1 Locale 为空导致规则失效这是我遇到的第一个问题。在鸿蒙模拟器上PlatformDispatcher.instance.locale返回了一个空对象或者undefined导致NumbersToText初始化时拿到错误的分隔符。报错现象是英文金额输出变成了one thousand two hundred thirty four连字符和and全部丢失。排查思路是打印所有能拿到的 locale 信息Dart 层PlatformDispatcher.instance.locale、鸿蒙侧i18n.getSystemLanguage()、还有系统设置里的实际语言选项。最终确认鸿蒙模拟器的早期版本对 Flutter 的 locale 上报不完整Dart 层拿不到值。解决办法就是我前面写的提供一个原生通道兜底初始化时两侧数据对比取非空值。这个坑的教训是不要信任任何一个平台通道的首次返回值。我后来统一封装了_resolveLocale()函数它会把 Dart 侧值、原生侧值、默认值做“三值比较”然后打印最终生效的项。这套逻辑虽然笨但在跨平台适配时非常管用。5.2 大数与精度问题BigInt 丢失四舍五入财务系统里经常出现超过 JavaScript 安全整数范围的金额Dart 原生 VM 的 int 是 64 位但一旦你从鸿蒙原生侧通过 MethodChannel 传值很多通道默认会把数字转成 double 或者某个中间格式精度直接丢得一塌糊涂。我在联调时遇到了一个典型事故鸿蒙侧传1000000000000000000010的19次方给 DartDart 收到后发现最后几位已经变了导致金额文本里多出好几个“零”。排查到最后发现是原生通道的数值类型映射问题。解决方案非常朴素但需要形成纪律任何跨通道的金额传递都用字符串。Dart 侧接收 String再用BigInt.parse或Decimal.parse解析转换完成后再返回字符串给原生侧。numbers_to_text 底层虽然主要处理 int/double但你可以在封装层做一个“字符串 - 大数 - 分段文本”的预处理确保超大金额不被通道吃掉精度。5.3 财务场景的金额上限与货币符号坑numbers_to_text 对trillion以下的数量级支持得很好但超过之后会发生什么文档里没有明确说。我实测10^15quadrillion 级别时输出开始偏离预期因为它内部的数量级表只到 trillion。财务场景里遇到超大金额时我建议不要硬拼英文数量级词而是直接进入“工程降级”把数字按科学计数法转文本或者拆成“万/亿”这样的中文单位。这个决策不在三方言里而在业务需求里。千万别为了追求“全部转成英文”把金额输出成没人看得懂的串。货币符号另一个坑是零小数货币。日元、韩元这类货币的小数位是零moneyToText如果按美分逻辑硬套会输出zero cents这种让财务人皱眉的文本。适配时我建议按货币代码维护一张“小数位覆盖表”在调用moneyToText之前先判断该货币有没有小数位没有就只输出整数部分的货币文本。5.4 离线、包体积与裁剪优化最后聊一个容易被忽略的性能问题。numbers_to_text 全部语言资源编译后会给鸿蒙产物增加几百 KB 的体积。对移动应用来说几百 KB 不算致命但它会让首包加载变慢特别是在鸿蒙的 AOT 编译链路里未使用的语言映射表可能无法被完全裁剪。我的优化经验是如果你的业务只用英文和中文两种数字表达就自己维护一个裁剪后的转换器不要引入全量多语言包。可以用 Dart 的const映射表把英文规则和中文法定数字规则写死然后在封装层写一个NumberWordsEngine替代 numbers_to_text 全量语言包的工作。这个做法还有一个额外收益你可以完全控制数字到文本的“方言”比如中文场景下你可能有“壹佰贰拾叁元整”这种大写金额需求这不是 numbers_to_text 原版能给你的东西。自己写一套裁剪引擎按需加载体积和灵活性双赢。6. 从适配经验反推财务治理底座还可以怎么扩展如果你坚持看到这里说明你大概率也在做 Flutter 鸿蒙化的财务类项目。我最后再分享一个实际体会不要把 numbers_to_text 的鸿蒙化适配当成“一次性移植任务”而是当成“财务数字表达层的第一次基建”。因为一旦你有了稳定可控的数字转文本服务后续很多能力都可以顺势生长出来。我在项目落地的过程中把NumberTextService扩展成了三个子模块数字转文本、金额格式统一、审计日志摘要生成。数字转文本负责把数值变成语言金额格式统一负责把货币符号和小数位规范化审计日志摘要负责把结构化的对账结果变成自然语言描述。这三个子模块共享同一套 locale 解析和货币小数位表数据流完全一致。后续如果你碰到这些需求可以沿着同样的思路去做中文财务大写金额的扩展、多语言动态切换的实时刷新、无障碍模式下的金额朗读优化、以及和鸿蒙原生“读屏”能力的深度联动。这些扩展点不需要重写底层只是在NumberTextService的封装层加方法而已。踩过几次坑之后我最大的感受是三方库的鸿蒙化适配真正难的不是把代码编译过而是把“系统差异、语言差异、精度的差异”统一在一个可控的抽象层里。numbers_to_text 只是一个开始它对数字表达的处理方式和对多语言的扩展思路可以作为你在鸿蒙上搭建本地化数值转换体系的参照。希望这篇文章能让你少走一些弯路。
鸿蒙化适配 numbers_to_text：Flutter 数字转文本的财务实战
最近在推进一个孵化项目的鸿蒙化时整理依赖清单发现 numbers_to_text 这个 Flutter 三方库在鸿蒙侧基本是“裸奔”状态——Dart 代码本身能跑但牵涉系统语言、金额格式、本地化文本的场景统统要手动补适配。这个库解决的问题很朴素但特别容易被忽略把1234567.89变成one million two hundred thirty-four thousand five hundred sixty-seven and eighty-nine cents。听起来像“格式化字符串”的小事但跑过一遍发票核对、合同金额播报、财务无障碍朗读之后你会意识到这是一层被低估的“语言级直观”底座。这篇文章会把我在鸿蒙适配过程中的完整思路和实操记录下来为什么需要这个适配、numbers_to_text 内部到底怎么组织数字文本、鸿蒙侧有哪些坑、最终怎么落地。适合两类人看一类是正准备把现有 Flutter 业务搬到鸿蒙的开发者另一类是财务、票据、无障碍场景里被“数字读法”反复折磨的后端或客户端同学。1. 为什么要把 numbers_to_text 搬到鸿蒙上1.1 数字转文本在真实业务里的位置很多开发者第一次接触 numbers_to_text 是在做“金额大写”、“报销单文字化”、“语音播报账单”这类需求时。它做的事情一句话就能讲清楚把阿拉伯数字转换成自然语言文本。在英文环境下是1,234.56转one thousand two hundred thirty-four and fifty-six cents在多语言环境下它还会根据选定的 language 参数输出对应语言的文本规则。你可能觉得这不就是个NumberFormat加几张映射表的事真做过财务类需求的人不会这么想。财务场景里数字不只是给人看的还承担着“防篡改、可复核、易朗读”的责任。合同里的大写金额、银行回单里的英文金额、ERP 系统导出的英文发票摘要这些地方只要拼接规则错一个ty或者teen整张单据就得作废重审。numbers_to_text 的价值在于它把这套规则封装成了可复用的组件而不是每个业务方各写各的intToWords()。在鸿蒙生态里这个需求变得更加现实。鸿蒙应用现在大量承接政企办公、金融票据、无障碍辅助类场景这些场景恰恰是“数字读法”的高频使用地。但三方库生态没有完全跟上Flutter 侧的纯 Dart 包虽然可以编译过却缺少对鸿蒙系统语言配置、金额进制、Locale 动态切换的原生感知能力。1.2 鸿蒙 Flutter 生态里“库有缺口”的现实先明确一个背景鸿蒙 NEXT 不再兼容 Android 运行时Flutter 应用要跑在鸿蒙上需要使用适配过的 Flutter 引擎版本当前主流做法是使用社区维护的鸿蒙 Flutter 引擎分支。在这个引擎上Dart 层的标准库绝大多数仍然可用但凡是依赖PlatformDispatcher.locale、MethodChannel、EventChannel与系统侧互动的能力都可能存在版本差异。numbers_to_text 本身是纯 Dart 包按理说“直接就能跑”。我第一次也是这么以为的改完依赖一编译确实能出包。但真正跑业务用例时问题就来了鸿蒙系统语言设置为简体中文时Dart 层拿到的 locale 经常不是预期的zh_CN而 numbers_to_text 对中文的支持又不像英文那么完善再叠加财务场景里的“四舍五入规则不一致”、“货币符号取不到系统配置”这个库在鸿蒙上的可用性其实只有一半。所以“鸿蒙化适配”不是把包塞进依赖列表就完事而是要重新梳理这个库的输入输出边界哪些逻辑可以留在 Dart 层直接用哪些必须通过平台通道从鸿蒙系统侧读取哪些需要针对鸿蒙的财务场景做参数规范化。1.3 “语言级直观”到底指什么我一直在提“语言级直观”这个词不是包装出来的概念而是真实体验差异。人眼识别1,234,567.89需要数三次逗号才能确定是“百万级”但人耳或人脑听到one million two hundred thirty-four thousand five hundred sixty-seven and eighty-nine cents时数量级是即时成立的。对核对数字的人、视障用户、以及需要把金额语音播报出来的 POS 机场景来说这种表达方式直接从“看符号”升级到“读语言”理解成本和出错率都会下降。财务治理底座的身份也来源于此一套稳定的数字转文本能力能统一所有业务模块的数字表达规则。报销单、发票摘要、审计日志、合同模板都不会出现“一个模块写 Thirteen另一个模块写 thirteen”这种低级不一致。适配鸿蒙就是在新的系统生态里把这套一致性底座重新立起来。2. numbers_to_text 的核心实现拆解2.1 整数数字的分组与拼接规则想高效适配一个库第一步是看懂它的实现骨架。numbers_to_text 对整数的处理遵循英语数字表达的标准逻辑三位一组thousand, million, billion, trillion组内再按百位、十位、个位拼接。这个结构和中文数字的“万进制”完全不同所以适配时绝不能想当然。以1234567为例它内部的处理路径大致是按千分位分组1 | 234 | 567最高组单独处理1 - one million第二组234 - two hundred thirty-four thousand第三组567 - five hundred sixty-seven拼接时处理连字符和空格得到one million two hundred thirty-four thousand five hundred sixty-seven这个“按三位分组”的逻辑很像我们记电话号码的方式——不是一口气读 11 位数字而是拆成 3-4-4 或者 3-3-5 这样的小段。numbers_to_text 做得好的一点是把hundred、and、连字符twenty-four、teen 和 ty 的边界都收敛到了内部规则里外部调用不需要关心这些细节。但边界情况不少。比如1000和1100的读法分别是one thousand和one thousand one hundred而1001是one thousand one0需要单独处理为zero负数依赖signed: true参数控制。这些细节在普通显示场景无所谓但在财务场景里每个单词都影响审计文本的准确性。2.2 小数、分数、货币与符号处理的边界整数只是第一层财务场景真正棘手的是小数、分数与货币的编排。numbers_to_text 提供了几个入口方法numberToText处理整数、floatToText处理带小数的数值、moneyToText处理金额、fractionToText处理分数。floatToText的逻辑核心是将小数部分按“位”展开而不是按“值”展开。比如3.14会输出three point one four这种读法在计量场景更稳妥3.5则可以输出three point five。分数场景里1/2被读作one half1/4是one quarter这依赖预置的“特殊分数词表”。moneyToText是最有财务味道的方法。它会把整数部分按原逻辑转文本小数部分作为cents或pence处理并拼接货币单位。比如 USD 金额1,234.56读作one thousand two hundred thirty-four dollars and fifty-six cents。这里涉及两个容易踩坑的点货币代码到货币名称的映射USD - dollarEUR - euro是否完整以及“零头”与整数部分的连接词and在不同语言里是否一致。适配鸿蒙时这些边界一个都不能省。我见过生产事故某个系统把0.01在英文场景下输出成zero point zero one导致客户拒收对账单。真正专业的表现应该是zero dollars and one cent这样既符合财务规范又能被审计系统解析的文本。2.3 一套可移植的“数字-文本映射引擎”设计numbers_to_text 给我们的最大启示是它把“数字 - 文本”这件事抽象成了“分位 映射 连词”的三层引擎。分位层负责决定数量级单位thousand/million/billion映射层负责把 0-999 的每个数字块转成词串连词层负责处理空格、连字符、and等语言习惯。理解这个抽象对鸿蒙适配极其关键。因为我们在鸿蒙侧往往不是重新发明轮子而是把这三层逻辑中的“映射层”替换成适配鸿蒙语言偏好后的版本或者把“连词层”按中文金额大写规则重写。比如中文财务场景常见的“壹仟贰佰叁拾肆元伍角陆分”就是典型的“分位 中文法定数字映射 财务连词”的组合。我建议在适配时不要直接改三方库源码而是在你工程里做一个薄封装层把 numbers_to_text 的输出格式规范成自己团队的“标准数字文本模型”。这样后续鸿蒙引擎升级、库版本升级业务侧都不受影响。3. 鸿蒙化适配的两条技术路线与选型3.1 路线A纯 Dart 重实现推荐基础版因为 numbers_to_text 最核心的逻辑都在 Dart 层理论上鸿蒙化首选是“纯 Dart 方案”直接用包内已有的转换能力只把系统侧语言、货币配置通过轻量通道注入进来。这条路线的优势很明显实现简单、依赖少、不受鸿蒙引擎底层差异影响。你只需要解决一个问题——Dart 层怎么拿到正确的系统 Locale。鸿蒙 Flutter 引擎的PlatformDispatcher.locale在部分版本上返回的结果和 Android 上不完全一致特别是在系统语言设置成“简体中文 英文辅助”这种复合场景下Dart 层可能拿到错误的优先级。我的做法是封装一个NumberTextService它内部维护一个当前生效的 locale 状态。初始化时先读取PlatformDispatcher.instance.locale如果发现空值或异常值再用MethodChannel向鸿蒙侧发起一次查询获取系统偏好。后续系统语言切换事件通过EventChannel持续监听从而实现“不重启应用即时切换数字读法”的体验。这个方案适合绝大多数业务场景。如果你只是想让鸿蒙应用里数字表达符合当地语言习惯没有强依赖系统特有 API纯 Dart 方案足够。3.2 路线B鸿蒙原生能力桥接MethodChannel 原生类有些需求纯 Dart 解决不了。比如你的财务模块需要读取鸿蒙系统自带的货币格式化规则包含小数点符号、千分位符号、货币符号位置或者需要调用系统无障碍朗读引擎确认“当前语音通道是否正在使用”这时候就得走平台通道。鸿蒙侧插件注册的方式和 Android 类似在 ohos 工程的插件目录下新建适配类通过MethodChannel注册方法处理器然后在 Dart 侧用同样的 channel name 发起调用。需要注意鸿蒙 Flutter 引擎的 binary messenger 接口在不同版本上名字略有差异以你集成的引擎版本为准。一个典型的鸿蒙侧实现是先接收 Dart 传来的数字字符串注意用字符串而不是 double避免精度丢失再调用鸿蒙系统Intl相关能力做格式化或货币映射最后把结果返回给 Dart。路线B适合“数据源在原生侧”的场景。比如财务系统里金额的单位是鸿蒙本地化接口提供的或者需要和鸿蒙的“超级终端”能力联动把数字文本投到另一个设备上进行语音播报。这种情况用 port 通道打通两侧是不可避免的。3.3 我的选型结论两条路线的边界我划得很清楚维度纯 Dart 重实现鸿蒙原生能力桥接实现工作量小聚焦 Locale 注入中需要双端联调系统特性依赖低引擎差异影响小高依赖鸿蒙原生 API财务精度控制好数字全程在 Dart 层中注意通道传输精度多语言扩展依赖包内语言表可复用系统语言资源实时语言切换需 EventChannel 辅助原生侧原生支持我的结论是“两端结合”先用纯 Dart 方案把numbers_to_text的核心链路跑通保证 90% 的数字转文本需求在 Dart 层稳定闭环再给那几个必须读系统配置的方法留出原生通道的扩展点。这样既有稳定性又有灵活性。如果你问我现在项目里用的是哪种我可以坦白说线上是纯 Dart 方案占主导原生桥接只用于“获取系统货币符号”这一个调用点。因为财务系统的数字转文本最终要稳定要可控不要每跑一步都依赖原生侧玄学行为。4. 实操手把手完成一轮最小适配4.1 工程准备Flutter 插件 ohos 目录假设你手上已经有一个跑通鸿蒙引擎的 Flutter 工程接下来要做的第一件事是检查pubspec.yaml里有没有正确声明鸿蒙平台目录。Flutter 插件工程通常会维护android/、ios/等平台目录鸿蒙化适配时你需要增加ohos/目录结构。这个目录的核心文件是ohos/entry/src/main/ets/下的插件注册代码。用官方或社区的 ohos 插件模板初始化后你会得到一个空壳工程它负责把插件注册到鸿蒙的 Flutter 引擎上。确认这个壳工程能正常编译是后续所有适配的前提。检查点有三个第一ohos 目录里的oh-package.json5依赖名和版本是否与你集成的 Flutter 引擎版本匹配第二工具链能否识别entry模块第三运行hvigor构建时有没有报“找不到 flutter engine”的错。这三关过了进度条才真正开始。4.2 Dart 层改造Locale 获取与参数传递我建议先把 numbers_to_text 的调用封装到自己的服务类里后续适配不会污染业务代码。一个最小可用的实现大概是这样的import package:flutter/services.dart; import package:numbers_to_text/numbers_to_text.dart; class NumberTextService { NumberTextService._(); static final NumberTextService instance NumberTextService._(); NumbersToText? _enConverter; Locale? _currentLocale; // 初始化优先从 Dart 侧取 locale异常时再走原生通道 Futurevoid init() async { _currentLocale PlatformDispatcher.instance.locale; if (_currentLocale null || _currentLocale!.languageCode.isEmpty) { _currentLocale await _fetchNativeLocale(); } _enConverter NumbersToText( language: Languages.english, signed: true, decimalSeparator: _currentLocale?.decimalSeparator ?? ., ); } FutureLocale? _fetchNativeLocale() async { final String raw await _channel.invokeMethodString(getSystemLocale) ?? ; if (raw.isEmpty) return null; final parts raw.split(_); return Locale(parts.first, parts.length 1 ? parts.last : null); } String moneyToEnText(double value, String currencyCode) { // 注意严谨场景不要把 double 直接传进来这里仅为示例 return _enConverter?.moneyToText(value, currency: currencyCode) ?? value.toString(); } }这段代码做了三件事把 locale 读取逻辑收敛到一处、把 numbers_to_text 初始化收敛到一处、给原生通道留了扩展点。注意我在moneyToEnText上方用注释提示了精度问题——真实的财务金额计算建议使用Decimal类型double 只适合展示层。这是我在生产项目里踩过的坑0.1 0.2这种经典误差在金额转文本时会被放大成“某分钱对不上账”的故障。4.3 鸿蒙侧注册与方法实现如果你确实需要走原生通道补 Locale鸿蒙侧的代码逻辑很简单。在插件注册类里加一个MethodChannel处理getSystemLocale方法。核心是用鸿蒙的配置模块读取当前语言偏好然后拼成语言_地区格式返回。下面是我在鸿蒙侧使用的示意代码具体接口名以你集成引擎版本为准// 插件注册文件ohos/entry/src/main/ets/entryability/EntryBackAware.ets 等 import { MethodChannel } from ohos/flutter_ohos_plugin; import { i18n } from kit.LocalizationKit; export function registerNumberTextChannel(messenger: Object): void { const channel new MethodChannel(messenger, numbers_to_text_channel); channel.setMethodCallHandler((call, result) { if (call.method getSystemLocale) { const language i18n.getSystemLanguage(); const region i18n.getSystemRegion(); result.success(${language}_${region}); return; } result.notImplemented(); }); }这段代码的意图不是照抄而是展示“最小职责”原生侧不承担数字转文本的主逻辑只负责给出正确的语言环境。把系统的语言能力返回给 Dart由 numbers_to_text 决定按什么语言规则去转换。这样职责单一排查问题时也不用两头猜。4.4 端到端验证用例集适配完成后我强烈建议你建立一份“数字读法金标用例集”。不要只测123这种简单数字必须覆盖财务场景的所有边界。我目前维护的用例集大致长这样整数边界0-zero1,000-one thousand1,000,000-one million小数精度0.01123.45999999.99分数表达1/2-one half3/4-three quarters负数-45.67是否带minus货币表达USD 1234.56是否输出dollars and centsJPY这类无小数货币是否省略小数段大数压测trillion级别是否能正确输出不发生整数溢出语言切换系统语言从英文切到中文后调用结果是否符合预期每个用例在提交代码前都要跑一遍。这个技术债不还后面每次升级引擎版本都会心里发毛。5. 适配过程中的常见问题与排查实录5.1 Locale 为空导致规则失效这是我遇到的第一个问题。在鸿蒙模拟器上PlatformDispatcher.instance.locale返回了一个空对象或者undefined导致NumbersToText初始化时拿到错误的分隔符。报错现象是英文金额输出变成了one thousand two hundred thirty four连字符和and全部丢失。排查思路是打印所有能拿到的 locale 信息Dart 层PlatformDispatcher.instance.locale、鸿蒙侧i18n.getSystemLanguage()、还有系统设置里的实际语言选项。最终确认鸿蒙模拟器的早期版本对 Flutter 的 locale 上报不完整Dart 层拿不到值。解决办法就是我前面写的提供一个原生通道兜底初始化时两侧数据对比取非空值。这个坑的教训是不要信任任何一个平台通道的首次返回值。我后来统一封装了_resolveLocale()函数它会把 Dart 侧值、原生侧值、默认值做“三值比较”然后打印最终生效的项。这套逻辑虽然笨但在跨平台适配时非常管用。5.2 大数与精度问题BigInt 丢失四舍五入财务系统里经常出现超过 JavaScript 安全整数范围的金额Dart 原生 VM 的 int 是 64 位但一旦你从鸿蒙原生侧通过 MethodChannel 传值很多通道默认会把数字转成 double 或者某个中间格式精度直接丢得一塌糊涂。我在联调时遇到了一个典型事故鸿蒙侧传1000000000000000000010的19次方给 DartDart 收到后发现最后几位已经变了导致金额文本里多出好几个“零”。排查到最后发现是原生通道的数值类型映射问题。解决方案非常朴素但需要形成纪律任何跨通道的金额传递都用字符串。Dart 侧接收 String再用BigInt.parse或Decimal.parse解析转换完成后再返回字符串给原生侧。numbers_to_text 底层虽然主要处理 int/double但你可以在封装层做一个“字符串 - 大数 - 分段文本”的预处理确保超大金额不被通道吃掉精度。5.3 财务场景的金额上限与货币符号坑numbers_to_text 对trillion以下的数量级支持得很好但超过之后会发生什么文档里没有明确说。我实测10^15quadrillion 级别时输出开始偏离预期因为它内部的数量级表只到 trillion。财务场景里遇到超大金额时我建议不要硬拼英文数量级词而是直接进入“工程降级”把数字按科学计数法转文本或者拆成“万/亿”这样的中文单位。这个决策不在三方言里而在业务需求里。千万别为了追求“全部转成英文”把金额输出成没人看得懂的串。货币符号另一个坑是零小数货币。日元、韩元这类货币的小数位是零moneyToText如果按美分逻辑硬套会输出zero cents这种让财务人皱眉的文本。适配时我建议按货币代码维护一张“小数位覆盖表”在调用moneyToText之前先判断该货币有没有小数位没有就只输出整数部分的货币文本。5.4 离线、包体积与裁剪优化最后聊一个容易被忽略的性能问题。numbers_to_text 全部语言资源编译后会给鸿蒙产物增加几百 KB 的体积。对移动应用来说几百 KB 不算致命但它会让首包加载变慢特别是在鸿蒙的 AOT 编译链路里未使用的语言映射表可能无法被完全裁剪。我的优化经验是如果你的业务只用英文和中文两种数字表达就自己维护一个裁剪后的转换器不要引入全量多语言包。可以用 Dart 的const映射表把英文规则和中文法定数字规则写死然后在封装层写一个NumberWordsEngine替代 numbers_to_text 全量语言包的工作。这个做法还有一个额外收益你可以完全控制数字到文本的“方言”比如中文场景下你可能有“壹佰贰拾叁元整”这种大写金额需求这不是 numbers_to_text 原版能给你的东西。自己写一套裁剪引擎按需加载体积和灵活性双赢。6. 从适配经验反推财务治理底座还可以怎么扩展如果你坚持看到这里说明你大概率也在做 Flutter 鸿蒙化的财务类项目。我最后再分享一个实际体会不要把 numbers_to_text 的鸿蒙化适配当成“一次性移植任务”而是当成“财务数字表达层的第一次基建”。因为一旦你有了稳定可控的数字转文本服务后续很多能力都可以顺势生长出来。我在项目落地的过程中把NumberTextService扩展成了三个子模块数字转文本、金额格式统一、审计日志摘要生成。数字转文本负责把数值变成语言金额格式统一负责把货币符号和小数位规范化审计日志摘要负责把结构化的对账结果变成自然语言描述。这三个子模块共享同一套 locale 解析和货币小数位表数据流完全一致。后续如果你碰到这些需求可以沿着同样的思路去做中文财务大写金额的扩展、多语言动态切换的实时刷新、无障碍模式下的金额朗读优化、以及和鸿蒙原生“读屏”能力的深度联动。这些扩展点不需要重写底层只是在NumberTextService的封装层加方法而已。踩过几次坑之后我最大的感受是三方库的鸿蒙化适配真正难的不是把代码编译过而是把“系统差异、语言差异、精度的差异”统一在一个可控的抽象层里。numbers_to_text 只是一个开始它对数字表达的处理方式和对多语言的扩展思路可以作为你在鸿蒙上搭建本地化数值转换体系的参照。希望这篇文章能让你少走一些弯路。
