做跨端適配最怕遇到的就是那種“包很小、功能看著很直接真跑起來(lái)全是隱性差異”的組件。最近在把一套 Flutter 工程往鴻蒙HarmonyOS端遷移時(shí)我花了兩天時(shí)間把 humanize 這個(gè)人性化數(shù)據(jù)格式組件徹底理順了。簡(jiǎn)單說(shuō)humanize 負(fù)責(zé)把原始數(shù)字、文件大小、日期差值這些冷冰冰的數(shù)據(jù)翻譯成人話1234567 顯示成 1.23 million3845 字節(jié)顯示成 3.8 KB三天前的時(shí)間顯示成“3 days ago”。這類能力在普通 Flutter 環(huán)境里用得很順但到了鴻蒙端最先暴露出來(lái)的不是功能缺失而是語(yǔ)言、單位、刷新時(shí)機(jī)這些“感知層”問(wèn)題。這篇內(nèi)容適合正在做 Flutter 組件向鴻蒙遷移的開發(fā)者也適合想搞清楚這類格式化組件在非標(biāo)準(zhǔn)環(huán)境下如何本地化的朋友。1. 為什么是 humanize人性化格式的語(yǔ)義范圍比你想的更寬1.1 數(shù)字、日期、文件大小之外的“隱藏語(yǔ)義”很多人第一次接觸 humanize以為它只是“把數(shù)字變短”。實(shí)際用下來(lái)會(huì)發(fā)現(xiàn)它是一整套“語(yǔ)言規(guī)則”的集合底層依賴的是 locale、復(fù)數(shù)規(guī)則、單位體系這些東西?？绲进櫭啥酥攸c(diǎn)往往不在包本身而在于它對(duì)語(yǔ)言的假設(shè)。我在這次適配中把需要關(guān)注的語(yǔ)義能力分成了四類貼一張表方便對(duì)照?qǐng)鼍霸紨?shù)據(jù)英文輸出中文場(chǎng)景期望緊湊數(shù)字12345671.23 million123.5萬(wàn)相對(duì)日期now - 3 小時(shí)3 hours ago3小時(shí)前序數(shù)詞33rd第3文件大小2048 bytes2 KB2 KB前兩類幾乎每個(gè) App 都會(huì)用到。緊湊數(shù)字出現(xiàn)在指標(biāo)卡、統(tǒng)計(jì)報(bào)表、支付金額備選展示里相對(duì)日期出現(xiàn)在點(diǎn)贊記錄、消息列表、動(dòng)態(tài)時(shí)間戳里。文件大小次之主要出現(xiàn)在下載頁(yè)和存儲(chǔ)詳情頁(yè)。序數(shù)詞在中文環(huán)境里使用頻率低但英文環(huán)境下“1st、2nd、3rd”又是剛需。還有一個(gè)容易忽略的“隱藏語(yǔ)義”自然語(yǔ)言連接。英文會(huì)把列表拼成 “A, B and C”中文則習(xí)慣“A、B 和 C”。這種低頻能力我建議適配時(shí)先凍結(jié)不要強(qiáng)行統(tǒng)一等核心場(chǎng)景穩(wěn)定后再考慮。盲目擴(kuò)大適配范圍只會(huì)讓回歸測(cè)試量翻倍收益卻很小。1.2 適配鴻蒙前先做能力盤點(diǎn)哪些必改、哪些暫緩在動(dòng)手寫代碼之前我把 humanize 的現(xiàn)有能力從頭到尾過(guò)了一遍按“改動(dòng)成本”和“用戶感知頻率”做了個(gè)優(yōu)先級(jí)排序高優(yōu)先級(jí)緊湊數(shù)字、相對(duì)日期。這兩個(gè)幾乎每個(gè)界面都會(huì)出現(xiàn)而且中文和英文的表述習(xí)慣差異巨大。中優(yōu)先級(jí)文件大小。高頻但規(guī)則相對(duì)固定主要糾結(jié)在二進(jìn)制和十進(jìn)制的選擇上。低優(yōu)先級(jí)序數(shù)詞、復(fù)數(shù)、自然語(yǔ)言連接。中文環(huán)境基本感知不到英文環(huán)境保留默認(rèn)行為即可。這個(gè)優(yōu)先級(jí)直接影響后面兩個(gè)決策改哪些代碼、先跑哪些測(cè)試用例。做能力盤點(diǎn)還有一個(gè)作用避免把“通用包直接引入”當(dāng)成適配完成。我知道不少團(tuán)隊(duì)在遷移時(shí)直接把 humanize 加進(jìn) pubspec運(yùn)行了一下中文場(chǎng)景發(fā)現(xiàn)輸出還是英文就開始懷疑鴻蒙 SDK 有問(wèn)題。其實(shí)問(wèn)題很簡(jiǎn)單——組件自帶的是英文本地化規(guī)則它需要你主動(dòng)告訴它當(dāng)前是什么語(yǔ)言。所以適配的第一步永遠(yuǎn)是先把 Locale 鏈路打通。2. 鴻蒙端跑通用 humanize 的第一道坎Locale 與中文本地化2.1 默認(rèn)英文文案的來(lái)源與“半本地化”現(xiàn)象在普通 Flutter 環(huán)境里很多組件會(huì)自動(dòng)讀取系統(tǒng)語(yǔ)言比如 Material 組件庫(kù)里的日期選擇器、文本方向判斷。但 humanize 這類純 Dart 格式化組件不會(huì)去監(jiān)聽系統(tǒng)狀態(tài)它只知道你傳進(jìn)來(lái)的 locale 參數(shù)。鴻蒙端接入后我遇到的第一個(gè)怪現(xiàn)象是系統(tǒng)語(yǔ)言已經(jīng)切成中文界面上的按鈕、Label 都變成了中文但 humanize 輸出的還是 “1.2K”“3 days ago”。你可以理解成一種“半本地化”狀態(tài)——UI 層被系統(tǒng)處理了但數(shù)據(jù)格式化層沒(méi)被通知到。排查后發(fā)現(xiàn)鴻蒙端 Flutter 拿到的系統(tǒng)語(yǔ)言標(biāo)識(shí)偶爾會(huì)是 BCP47 格式比如zh-CN而 Dart 側(cè)很多組件習(xí)慣用下劃線格式zh_CN。如果直接把zh-CN當(dāng)成Locale對(duì)象的輸出傳入底層匹配不上語(yǔ)言表就會(huì)回退到默認(rèn)英文。這個(gè)小細(xì)節(jié)在排錯(cuò)時(shí)很隱蔽很多同事一開始都以為是緩存問(wèn)題其實(shí)只是字符串分隔符不同。所以我在項(xiàng)目里加了一個(gè)normalizeLocale函數(shù)專門把-轉(zhuǎn)成_并且把zh_Hans、zh_Hant這種帶腳本標(biāo)識(shí)的 Locale 也做歸一化處理。2.2 中文字段表的調(diào)整數(shù)字單位、復(fù)數(shù)規(guī)則、日期相對(duì)詞打通 Locale 之后下一步就是語(yǔ)言表本身。英文數(shù)字是三位一個(gè)單位thousand、million、billion中文是四位一個(gè)單位萬(wàn)、億。這意味著人類感知的“刻度”完全不同不能只把英文詞換成中文詞連分組邏輯都要改。相對(duì)日期也一樣。英文有完整的單復(fù)數(shù)變化“1 hour ago”和 “2 hours ago”中文沒(méi)有復(fù)數(shù)后綴直接是“1小時(shí)前”“2小時(shí)前”。方向詞也不一樣英文用 ago / in中文用“前 / 后”還有“剛剛”“馬上”這種口語(yǔ)化表達(dá)。我的做法是維護(hù)一個(gè)簡(jiǎn)單的多語(yǔ)言數(shù)據(jù)表class HumanizeMessages { final String justNow; final String minutesAgo; final String hoursAgo; final String daysAgo; final String inMinutes; final String compactTenThousand; final String compactHundredMillion; }每個(gè)語(yǔ)言一份中文、英文各一份。啟動(dòng)時(shí)根據(jù)當(dāng)前 Locale 選取并注入到統(tǒng)一的格式化入口。這里有一個(gè)關(guān)鍵點(diǎn)不要在每個(gè)頁(yè)面里各自創(chuàng)建一份表否則切語(yǔ)言時(shí)會(huì)看到一部分頁(yè)面是新的文案、一部分還是舊的非常難排查。2.3 一個(gè)容易忽略的細(xì)節(jié)語(yǔ)言切換后的緩存失效真正讓我多花了半天時(shí)間的是緩存問(wèn)題。格式化結(jié)果本質(zhì)上也是本地化產(chǎn)物是會(huì)隨語(yǔ)言變化的。但團(tuán)隊(duì)里有些同學(xué)習(xí)慣把格式化后的字符串直接緩存到內(nèi)存里理由也很正當(dāng)“一天之內(nèi)語(yǔ)言不會(huì)變”。實(shí)際在鴻蒙設(shè)備上系統(tǒng)語(yǔ)言設(shè)置是可以實(shí)時(shí)切換的多語(yǔ)言應(yīng)用也常常在應(yīng)用內(nèi)切換語(yǔ)言這時(shí)候緩存就成了罪魁禍?zhǔn)?。我的建議是格式化后的字符串只做短期緩存比如單次頁(yè)面構(gòu)建會(huì)話內(nèi)有效不做全局靜態(tài)緩存。更嚴(yán)格的做法是格式化結(jié)果根本不緩存每次視圖重建時(shí)重新計(jì)算。后面會(huì)講到這套機(jī)制在真機(jī)上踩坑的過(guò)程。3. 核心實(shí)操數(shù)字壓縮、文件大小與日期語(yǔ)義的鴻蒙端適配3.1 數(shù)字壓縮中英文單位映射與邊界精度數(shù)字壓縮是 humanize 最常見的用法也是最容易踩精度坑的地方。英文場(chǎng)景里1234567 通常期望顯示成 1.23M 或者 1.23 million中文場(chǎng)景則習(xí)慣直接顯示成 123.5萬(wàn)四位一檔。一開始我嘗試直接用NumberFormat.compact它在普通 Flutter 環(huán)境里的表現(xiàn)確實(shí)不錯(cuò)。但在鴻蒙端 Flutter 嵌入環(huán)境下我發(fā)現(xiàn) intl 的版本行為不完全一致部分版本對(duì)中文 compact 的處理會(huì)保留冗長(zhǎng)的零比如輸出 “1200000”而不是“120萬(wàn)”。為了保持回歸可控我干脆自己寫了一個(gè)精簡(jiǎn)版String compactNumber(num value, {String locale zh}) { if (locale.startsWith(zh)) { if (value 100000000) { return _trimZero((value / 100000000).toStringAsFixed(1)) 億; } if (value 10000) { return _trimZero((value / 10000).toStringAsFixed(1)) 萬(wàn); } return value.toStringAsFixed(0); } // 英文場(chǎng)景使用原有 humanize 邏輯 }_trimZero做的事情是把 123.0 修正成 123把 1.50 修正成 1.5避免界面出現(xiàn) “123.0萬(wàn)”這種別扭的文案。這里要注意一個(gè)邊界如果值為 99995000用萬(wàn)做單位會(huì)看到 “9999.5萬(wàn)”用億做單位會(huì)得到 “1.0億”。從人體感知角度1.0億顯然更簡(jiǎn)潔但判斷邏輯不能只做兩次 if需要在“位數(shù)縮短”和“精度損失”之間取一個(gè)平衡。我的經(jīng)驗(yàn)是當(dāng)值在億和千萬(wàn)之間時(shí)優(yōu)先取最接近的整位單位而不是機(jī)械地按數(shù)值大小分段。3.2 文件大小二進(jìn)制 vs 十進(jìn)制、單位詞是否翻譯文件大小格式化看起來(lái)簡(jiǎn)單實(shí)際會(huì)引出兩個(gè)爭(zhēng)論進(jìn)制和單位詞。進(jìn)制的選擇。鴻蒙操作系統(tǒng)的文件管理器習(xí)慣用二進(jìn)制進(jìn)制也就是 1KB 1024B1GB 1024MB。但也有部分第三方應(yīng)用習(xí)慣用十進(jìn)制1kB 1000B。工程上我建議全端統(tǒng)一用二進(jìn)制因?yàn)榕c系統(tǒng)顯示一致用戶對(duì)比存儲(chǔ)空間時(shí)不會(huì)算出小數(shù)點(diǎn)差異。代碼邏輯就是 1024 遞歸取模單位從 B 一路走到 TB。單位詞要不要翻譯成中文是另一個(gè)容易沖動(dòng)處理的地方。有人會(huì)想把 KB 顯示成“千字節(jié)”把 MB 顯示成“兆字節(jié)”。我實(shí)測(cè)下來(lái)的結(jié)論是不要翻譯。一是這些單位已經(jīng)是國(guó)際通用符號(hào)用戶概念里自帶語(yǔ)義二是“千字節(jié)”這種中文詞在窄卡上容易折行還會(huì)擠掉數(shù)字的可讀性。通用做法是保留 KB、MB、GB 英文縮寫只在數(shù)字小數(shù)位規(guī)則上做本地化。String fileSize(int bytes, {bool useBinary true}) { const unit [B, KB, MB, GB, TB]; var size bytes.toDouble(); var step 0; final base useBinary ? 1024 : 1000; while (size base step unit.length - 1) { size / base; step; } return step 0 ? ${bytes} B : ${size.toStringAsFixed(2)} ${unit[step]}; }3.3 相對(duì)時(shí)間方向詞與“剛剛”的適配相對(duì)時(shí)間格式化比數(shù)字復(fù)雜一點(diǎn)因?yàn)樗枰幚怼斑^(guò)去”和“未來(lái)”兩個(gè)方向還要考慮顯示粒度。String relativeTime(DateTime time, {DateTime? now}) { final current now ?? DateTime.now(); final diff current.difference(time); if (diff.inSeconds.abs() 30) return 剛剛; if (diff.isNegative) { // 未來(lái)時(shí)間 if (diff.inMinutes.abs() 60) return ${diff.inMinutes.abs()}分鐘后; if (diff.inHours.abs() 24) return ${diff.inHours.abs()}小時(shí)后; return ${diff.inDays.abs()}天后; } if (diff.inMinutes 60) return ${diff.inMinutes}分鐘前; if (diff.inHours 24) return ${diff.inHours}小時(shí)前; if (diff.inDays 7) return ${diff.inDays}天前; // 超過(guò) 7 天直接走日期格式 return DateFormat(yyyy-MM-dd).format(time); }這個(gè)實(shí)現(xiàn)里有幾個(gè)容易出問(wèn)題的細(xì)節(jié)。第一個(gè)是now.difference(time)的方向性如果time是過(guò)去的某個(gè)時(shí)刻diff為正數(shù)但如果time在未來(lái)inMinutes會(huì)是負(fù)數(shù)。很多新手直接拿負(fù)數(shù)去做拼接結(jié)果界面出現(xiàn)“-3分鐘前”。第二個(gè)是中文不需要復(fù)數(shù)但英文需要所以相對(duì)時(shí)間的英文分支要額外處理 single 和 plural。第三個(gè)是“剛剛”的閾值30秒以內(nèi)是體驗(yàn)最好的超過(guò) 1 分鐘還顯示“剛剛”會(huì)讓人覺得時(shí)間沒(méi)刷新。4. 真機(jī)驗(yàn)證與排錯(cuò)記錄切語(yǔ)言不刷新、字體缺字、精度誤差4.1 切語(yǔ)言后文案不刷新完整排查鏈路這個(gè)排錯(cuò)過(guò)程我完整記錄過(guò)非常典型值得按鏈路走一遍?，F(xiàn)象是這樣的真機(jī)上把系統(tǒng)語(yǔ)言從英文切到中文界面大部分文字立刻變中文但某個(gè)列表頁(yè)里 humanize 格式化出來(lái)的數(shù)字還是 1.2K日期還是 3 days ago。等了十幾秒也不刷新。第一步我檢查 Flutter 側(cè)是否收到了系統(tǒng)語(yǔ)言變化。在MaterialApp的localeResolutionCallback里打了日志確認(rèn)回調(diào)觸發(fā)了頁(yè)面也重建了。第二步懷疑是列表項(xiàng)渲染太快格式化發(fā)生在頁(yè)面構(gòu)建之前。查看代碼后發(fā)現(xiàn)列表數(shù)據(jù)在進(jìn)入頁(yè)面時(shí)統(tǒng)一格式化后緩存進(jìn)了一個(gè)列表項(xiàng)模型里。也就是說(shuō)頁(yè)面雖然重建了但列表數(shù)據(jù)的格式化內(nèi)容是事前算好的不會(huì)跟著語(yǔ)言變化重新計(jì)算。這是第一個(gè)根因。第三步修復(fù)方式是把緩存去掉在 item 的build方法里重新調(diào)用格式化函數(shù)。改完再測(cè)大部分文案正常了但還有一處數(shù)字依舊是英文。第四步這處數(shù)字來(lái)自另一個(gè)模塊的靜態(tài)工具類。這個(gè)工具類直接引用了Intl.defaultLocale而它被某個(gè)三方日志組件在初始化時(shí)設(shè)置成了en_US。這屬于全局變量污染。修復(fù)方案很粗暴在應(yīng)用啟動(dòng)階段統(tǒng)一用一個(gè)AppLocaleController維護(hù)當(dāng)前的 locale并在系統(tǒng)語(yǔ)言變化回調(diào)里同時(shí)更新Intl.defaultLocale。排查來(lái)回花了兩小時(shí)但收獲很直接格式化入口必須收斂到統(tǒng)一的地方任何散落的分支都可能在某個(gè)角落繞過(guò)語(yǔ)言更新邏輯。4.2 精簡(jiǎn)字體下“萬(wàn)”“億”的渲染異常第二個(gè)問(wèn)題來(lái)自一臺(tái)系統(tǒng)字體被精簡(jiǎn)過(guò)的設(shè)備界面里“1.2萬(wàn)”的“萬(wàn)”字渲染成了豆腐塊。最初我以為是 humanize 輸出亂碼后來(lái)發(fā)現(xiàn)是字體回退鏈路的問(wèn)題數(shù)字格式化后生成了中文字符而這個(gè)界面為了視覺統(tǒng)一配置了某款拉丁字體族中文字符沒(méi)有對(duì)應(yīng)的 fallback。這個(gè)坑在鴻蒙端比其他端更容易遇到因?yàn)椴簧嬴櫭稍O(shè)備鏡像為了減小體積會(huì)裁剪自帶中文字體集。解決辦法是在數(shù)字指標(biāo)這類組件的TextStyle里顯式指定一個(gè)包含 CJK 字符的字體族比如TextStyle( fontSize: 14, fontFamily: HarmonyOS Sans, fontFamilyFallback: [HarmonyOS Sans SC], )實(shí)在無(wú)法確定字體集時(shí)也可以臨時(shí)把中文單位替換成國(guó)際縮寫比如“1.2e8”這種形式。雖然犧牲了美觀但至少不會(huì)出現(xiàn)亂碼。4.3 精度誤差與展示截?cái)鄶?shù)字壓縮還有一個(gè)隱藏的精度問(wèn)題顯示值和真實(shí)值之間存在舍入誤差。例如 22994999 按萬(wàn)顯示是 2299.5萬(wàn)按億顯示是 0.2億兩種方案差異很大。產(chǎn)品經(jīng)理經(jīng)常要求“保留一位小數(shù)”但當(dāng)數(shù)值跨越單位閾值時(shí)保留一位小數(shù)的行為會(huì)讓數(shù)字變大或變小。比如 99999999最貼近的表述是 9999.9999萬(wàn)按一位小數(shù)會(huì)約成 10000.0萬(wàn)而用戶的直覺期望是顯示成更高的“1.0億”。這類問(wèn)題沒(méi)法完全靠語(yǔ)言表解決必須在格式化函數(shù)里做“就近取整單位”的邏輯比較兩個(gè)相鄰單位的結(jié)果哪種更短、更符合直覺。這個(gè)判斷規(guī)則我放在第三個(gè)段落里提到的compactNumber的邊界分支中并且加了注釋當(dāng)值的首位接近 9 時(shí)優(yōu)先進(jìn)位到高一級(jí)單位而不是強(qiáng)行保留當(dāng)前單位的一位小數(shù)。5. 性能與工程落地在鴻蒙端引入 humanize 的正確姿勢(shì)5.1 調(diào)用頻率與執(zhí)行耗時(shí)別在 build 里重復(fù)構(gòu)造格式化函數(shù)看起來(lái)輕但底層如果每次調(diào)用都去創(chuàng)建NumberFormat或DateFormat實(shí)例成本并不低。我在低端測(cè)試機(jī)上開了日志測(cè)過(guò)一次列表滾動(dòng)時(shí)每個(gè) item 同時(shí)做數(shù)字壓縮和相對(duì)日期格式化如果每幀都重新 new 格式化器幀率會(huì)出現(xiàn)肉眼可見的抖動(dòng)。正確的做法是把格式化器做成單例或者在狀態(tài)管理層的入口里預(yù)創(chuàng)建實(shí)例后續(xù)只調(diào)用format方法。尤其是DateFormat構(gòu)造時(shí)需要解析模式字符串比NumberFormat更重盡量做到整個(gè)應(yīng)用只創(chuàng)建一次。5.2 統(tǒng)一封裝與禁用范圍不要讓每處 UI 自己格式化這次適配讓我最大的教訓(xùn)是humanize 不應(yīng)該出現(xiàn)在任意的 UI 文件里。它太容易被順手調(diào)用一旦散落語(yǔ)言切換、精度策略、單位統(tǒng)一都會(huì)失控。我最終的做法是封裝了一個(gè)統(tǒng)一的語(yǔ)義格式化入口公開方法只有四個(gè)SemanticText.compactNumber(int value)SemanticText.fileSize(int bytes)SemanticText.relativeTime(DateTime time)SemanticText.ordinal(int number)UI 層只面向這個(gè)入口調(diào)用具體是用 humanize 原邏輯還是自己實(shí)現(xiàn)對(duì)調(diào)用方透明。這樣后續(xù)如果要擴(kuò)展語(yǔ)言只需改語(yǔ)言表如果要調(diào)整單位策略只需改動(dòng)入口內(nèi)部實(shí)現(xiàn)。5.3 回歸清單這樣測(cè)才能放心合入鴻蒙分支最后列一份我用來(lái)合入的回歸清單覆蓋這次踩過(guò)的所有問(wèn)題檢查項(xiàng)用例預(yù)期結(jié)果主要語(yǔ)言輸出系統(tǒng)語(yǔ)言切中文數(shù)字顯示“1.2萬(wàn)”、日期顯示“3小時(shí)前”次語(yǔ)言輸出系統(tǒng)語(yǔ)言切英文數(shù)字顯示“1.2M”、日期顯示“3 hours ago”Locale 格式兼容系統(tǒng)返回 zh-CN / zh_CN統(tǒng)一按中文規(guī)則輸出數(shù)字邊界10000 / 99999999 / 100000000萬(wàn)、億單位切換正確無(wú) 10000.0萬(wàn) 類文案相對(duì)時(shí)間未來(lái)now 5 分鐘顯示“5分鐘后”文件大小進(jìn)制1536 bytes顯示“1.50 KB”而不是“2 KB”或“1.536 KB”字體回退精簡(jiǎn)字體設(shè)備“萬(wàn)”“億”不出現(xiàn)豆腐塊語(yǔ)言切換熱切換后立即返回列表頁(yè)所有格式化文案同步更新性能千條列表滾動(dòng)幀率無(wú)掉幀無(wú)格式化器重復(fù)構(gòu)建告警自動(dòng)化用例覆蓋前六項(xiàng)后三項(xiàng)必須在真機(jī)上人工過(guò)一遍。我把自動(dòng)化用例直接放到了項(xiàng)目的格式化單元測(cè)試目錄里每次修改語(yǔ)言表都會(huì)先跑這組用例避免只改英文導(dǎo)致中文回歸。最后再分享一個(gè)小技巧適配這類通用包別迷信“開箱即用”。把語(yǔ)言當(dāng)作配置項(xiàng)而不是環(huán)境變量所有格式化結(jié)果都通過(guò)統(tǒng)一入口產(chǎn)出后續(xù)維護(hù)會(huì)輕松很多。