鸿蒙操作系统使用 i18n Kit 实现多区域数字货币与日期格式化实战
一、背景说明
鸿蒙生态终端用户规模正式突破 1 亿,出海多区域分发成为原生应用的新增刚需——同一份数据,在中国显示"¥12,800"、在德国就会因逗号分隔符被误读。本文聚焦一个具体技术点:使用 Localization Kit 的 @ohos.i18n 与 @ohos.intl 两个模块,实现系统区域检测、数字/货币/单位格式化、日期顺序适配的完整国际化方案,全部代码可直接编译运行。
二、技术原理
鸿蒙的国际化能力由两个互补模块组成:
@ohos.intl:实现 ECMA 402 标准定义的基础能力——Intl.NumberFormat(数字/货币/单位格式化)、Intl.DateTimeFormat(日期时间格式化)、Intl.Collator(排序)。@ohos.i18n:ECMA 402 之外的增强能力——i18n.System.getSystemRegion()获取系统区域、I18NUtil.unitConvert()度量衡换算、I18NUtil.getDateOrder()获取年月日排列顺序等。
核心数据流:getSystemLanguage/getSystemRegion 读系统设置 → 以区域 ID(如 zh-Hans-CN)构造 Formatter → 数据进 format() → 按当地习惯输出 → 监听 COMMON_EVENT_LOCALE_CHANGED 响应用户切区。
底层基于 CLDR 国际化数据库,输出格式随标准演进可能调整——官方明确要求不要对格式化结果做硬编码解析,只用于展示。
三、实现步骤
工程为 Stage 模型(API 12+),国际化能力无需任何权限,module.json5 保持默认。
1. 区域化格式化工具 I18nFormatter.ets
import { i18n, intl } from '@kit.LocalizationKit';
export class I18nFormatter {
private static region: string = 'CN';
// 应用启动时初始化:读取系统语言与区域
static init(): void {
const lang = i18n.System.getSystemLanguage(); // 如 'zh-Hans-CN'
I18nFormatter.region = i18n.System.getSystemRegion(); // 如 'CN'
console.info(`system lang=${lang}, region=${I18nFormatter.region}`);
}
// 数字格式化:1,000 分组分隔符随区域变化
static formatNumber(num: number): string {
const formatter = new intl.NumberFormat();
return formatter.format(num);
}
// 货币格式化:传入 ISO-4217 货币代码
static formatCurrency(amount: number, currency: string): string {
const formatter = new intl.NumberFormat({
style: 'currency',
currency: currency, // 'CNY' → ¥12,800.00;'EUR' → 12.800,00 €
currencyDisplay: 'symbol' // 'code'→CNY / 'narrowSymbol'→¥ / 'name'→人民币
});
return formatter.format(amount);
}
// 单位格式化:配合 unitUsage 可按场景自动选单位(如文件大小、行驶速度)
static formatUnit(value: number, unit: string, usage: string = 'default'): string {
const formatter = new intl.NumberFormat({
style: 'unit',
unit: unit, // 'meter'、'hectare'、'beat-per-minute' 等
unitUsage: usage,
unitDisplay: 'short'
});
return formatter.format(value);
}
// 度量衡换算:美制 cup → 公制 liter,并按目标区域格式化
static convertUnit(value: number, fromUnit: string, fromSystem: string,
toUnit: string, toSystem: string, locale: string): string {
const from: i18n.UnitInfo = { unit: fromUnit, measureSystem: fromSystem };
const to: i18n.UnitInfo = { unit: toUnit, measureSystem: toSystem };
return i18n.I18NUtil.unitConvert(from, to, value, locale, 'long');
}
// 日期格式化:年月日顺序、时制自动按区域适配
static formatDate(date: Date, locale: string = 'zh-CN'): string {
const formatter = new intl.DateTimeFormat(locale, {
dateStyle: 'medium',
timeStyle: 'short'
});
return formatter.format(date); // zh-CN: 2026年11月16日 20:30;en-US: Nov 16, 2026, 8:30 PM
}
// 获取区域日期顺序:'y-L-d'(中国)/ 'M-d-y'(美国)——自定义日期选择器时必须使用
static getDateOrder(locale: string): string {
return i18n.I18NUtil.getDateOrder(locale);
}
}
2. UI 调用示例 Index.ets
import { i18n, intl } from '@kit.LocalizationKit';
import { commonEventManager } from '@kit.BasicServicesKit';
import { I18nFormatter } from '../model/I18nFormatter';
@Entry
@Component
struct Index {
@State result: string = '';
build() {
Column({ space: 12 }) {
Button('按系统区域格式化').onClick(() => {
I18nFormatter.init();
const lines: string[] = [
`数字:${I18nFormatter.formatNumber(1234567.89)}`,
`人民币:${I18nFormatter.formatCurrency(12800, 'CNY')}`,
`欧元:${I18nFormatter.formatCurrency(12800, 'EUR')}`,
`单位:${I18nFormatter.formatUnit(42, 'kilometer', 'length-road')}`,
`日期顺序(zh-CN):${I18nFormatter.getDateOrder('zh-CN')}`,
`日期:${I18nFormatter.formatDate(new Date(), 'zh-CN')}`
];
this.result = lines.join('\n');
})
// 出海对照:同一组数据在三个区域的展示差异
Button('多区域对照').onClick(() => {
const rows: string[] = ['zh-CN|CNY', 'de-DE|EUR', 'en-US|USD'].map((row: string) => {
const [locale, currency] = row.split('|');
const nf = new intl.NumberFormat({ style: 'currency', currency: currency });
const df = new intl.DateTimeFormat(locale, { dateStyle: 'full' });
return `${locale}: ${nf.format(12800)} | ${df.format(new Date())}`;
});
this.result = rows.join('\n');
})
Text(this.result || '点击按钮体验')
.fontSize(13)
.width('90%')
.height(200)
.backgroundColor('#F2F3F5')
.padding(12)
.borderRadius(8)
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}
3. 监听用户切换系统区域
用户切区后格式化结果需要即时刷新,订阅系统公共事件即可:
import { commonEventManager } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';
let subscriber: commonEventManager.CommonEventSubscriber | null = null;
commonEventManager.createSubscriber({
events: ['usual.event.LOCALE_CHANGED']
}, (err: BusinessError, data: commonEventManager.CommonEventSubscriber) => {
subscriber = data;
subscriber.on('onCommonEvent', () => {
I18nFormatter.init(); // 重读系统区域
this.refreshAllFormatters(); // 重建各处 Formatter 并刷新 UI
});
});
四、应用场景示例
跨境电商订单页:金额、运费(含度量衡换算)、下单时间一并按买家区域渲染:
import { i18n, intl } from '@kit.LocalizationKit';
function renderOrder(amount: number, weightGram: number, locale: string, currency: string): string {
const currencyText = new intl.NumberFormat({
style: 'currency', currency: currency
}).format(amount);
// 500g 按目标区域习惯换算展示(英制显示盎司,公制显示千克)
const weightText = i18n.I18NUtil.unitConvert(
{ unit: 'gram', measureSystem: 'SI' },
locale === 'en-US' ? { unit: 'ounce', measureSystem: 'US' } : { unit: 'kilogram', measureSystem: 'SI' },
weightGram, locale, 'short');
const dateText = new intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date());
return `${currencyText} | ${weightText} | ${dateText}`;
}
// renderOrder(12800, 500, 'en-US', 'USD') → "$12,800.00 | 17.637 oz | Nov 16, 2026"
五、技术要点
1. 区域 ID 的规范
locale 由"语言-脚本-地区"组成(zh-Hans-CN),传入非法 ID 时 Formatter 会按 best fit 策略回退到最近匹配区域——结果可能不符合预期,建议始终基于 i18n.System.getSystemLanguage() 的返回值构造,不要硬编码。
2. CLDR 数据版本
格式化输出基于 CLDR 数据库,随系统版本演进可能调整(API 12 对应 CLDR 42)。官方明确:返回值仅用于界面展示,禁止对其做正则解析或相等性判断做业务逻辑,否则系统升级后行为可能变化。
3. 错误处理
try {
const nf = new intl.NumberFormat({ style: 'currency', currency: 'CNY' });
} catch (err) {
const e = err as BusinessError;
if (e.code === 401) {
console.error('区域 ID 非法或 options 参数错误');
} else {
console.error(`i18n error code=${e.code}`);
}
}
4. 使用限制
DateTimeFormat(旧类名)自 API 20 起废弃,统一使用Intl.DateTimeFormat;Date构造的月份从 0 开始计数(0 表示一月),传 1 会得到二月;- 部分接口自 API 11 起支持在 ArkTS 卡片中使用,桌面卡片内可直接格式化展示。
六、扩展建议
- 文本排序:用
Intl.Collator按区域规则对商品名排序——拼音序、笔画序由 locale 决定:
const collator = new intl.Collator('zh-Hans-CN');
const sorted = names.sort((a: string, b: string) => collator.compare(a, b)); // 拼音升序
- 时区感知:
Intl.DateTimeFormat配合timeZone选项展示目的地时间,机票、酒店类应用必备; - 字体管理:API 26.0.1 起 Localization Kit 新增第三方字体安装/卸载能力,可为不同语言市场动态加载专属字体。
结语
本文用 @ohos.i18n 与 @ohos.intl 完成了鸿蒙应用从系统区域检测、数字/货币/单位格式化、日期顺序适配到区域切换监听的完整国际化实现,核心代码约 150 行,均可直接编译运行。掌握 Formatter 的选项体系与区域 ID 规范后,应用出海只需准备翻译文本,数字、金额、日期的本地化呈现交给系统即可。
openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构
更多推荐


所有评论(0)