OpenHarmony图表如何进行国际化支持

OpenHarmony图表国际化支持

一 总体思路

• 将图表中所有可本地化的内容拆分为两类：
  1. 资源类文本（如标题、轴标签、单位、图例项、空数据提示等），放入工程的 resources 多语言资源目录，通过 $r(‘app.string.xxx’) 或 $(‘app.string.xxx’) 在 ArkUI 中引用；
  2. 格式化类数据（如数字千分位、百分比、货币、日期时间），在运行时使用 @ohos.intl 按当前 locale 进行格式化。
• 图表库（如 MPChart）通常不直接提供多语言 API，做法是在将数据喂给图表前完成文本与格式的国际化处理，图表只负责渲染。这样既与 ArkUI 资源体系解耦，又能覆盖绝大多数图表场景。

二 资源与文本的国际化

• 资源目录与文件：在 resources 下创建对应语言与地区目录（如 zh/element/string.json、en/element/string.json、以及 base/element/string.json 作为默认资源），以 name/value 形式维护键值对。
• 在 ArkUI 中引用：
  • 使用 $r(‘app.string.chart_title’) 获取资源 ID 对应的本地化字符串；
  • 或使用 $(‘app.string.xxx’) 快捷方式（部分版本/模板支持）。
• 在图表中使用：将标题、轴标签、单位、图例名、空数据文案等全部替换为资源引用，避免硬编码。
• 运行时语言变更：系统会自动选择对应语言资源；如需在代码中获取当前语言，可调用 i18n.getSystemLanguage() 等 API 做分支或日志。
• 示例（ArkTS + 资源引用）：
  • zh/element/string.json { “name”: “chart_title”, “value”: “销售趋势” }
  • en/element/string.json { “name”: “chart_title”, “value”: “Sales Trend” }
  • index.ets @Entry @Component struct SalesChart { build() { Column() { Text($r(‘app.string.chart_title’)) .fontSize(20) // 将 chart.setTitle($r(‘app.string.chart_title’)) 等交给图表配置 } } }
    上述做法依赖 ArkUI 的资源机制与 $r/$(‘app.string.xxx’) 语法，系统会在语言切换时自动匹配对应资源。

三 数字日期与单位的本地化

• 原则：数值、百分比、货币、千分位、日期时间等一律在业务层格式化后再送入图表（轴标签、数据点的 tooltip/标注、注释等）。
• 常用 API：
  • Intl.NumberFormat 用于数字、百分比、货币千分位与符号本地化；
  • Intl.DateTimeFormat 用于日期时间格式（如 “en-GB”、“zh-Hans-CN” 等 locale 下的不同格式）。
• 示例（ArkTS）：
  • 千分位与百分比 const nf = new intl.NumberFormat($r(‘app.string.number_locale’), { style: ‘decimal’, minimumFractionDigits: 2, maximumFractionDigits: 2 }); const pf = new intl.NumberFormat($r(‘app.string.percent_locale’), { style: ‘percent’, minimumFractionDigits: 1 }); const sales = 1234567.89; const percent = 0.135; console.info(nf.format(sales)); // 1,234,567.89（随 locale 变化） console.info(pf.format(percent)); // 13.5%（随 locale 变化）
  • 日期时间 const df = new intl.DateTimeFormat($r(‘app.string.date_locale’), { year: ‘numeric’, month: ‘short’, day: ‘numeric’ }); console.info(df.format(new Date())); // 06 Nov 2025（随 locale 变化）
  • 货币（示例） const cf = new intl.NumberFormat($r(‘app.string.currency_locale’), { style: ‘currency’, currency: ‘CNY’ }); console.info(cf.format(1234.56)); // ¥1,234.56（随 locale 变化）
    通过 Intl 格式化后，再设置到图表的轴标签、数据点的标签或 Tooltip 中，即可实现全链路本地化。

四 与图表库集成示例 MPChart

• 安装：使用 ohpm 安装 @ohos/mpchart。
• 思路：在构造数据前，对以下项做本地化：
  • DataSet label（图例项）；
  • Axis valueFormatter（轴刻度与标签）；
  • Entry 的 data（用于自定义 Tooltip/MarkerView 显示）。
• 示例（ArkTS 伪代码）：

  • 资源 zh/element/string.json: { “name”: “unit_sales”, “value”: “销售额（元）” } en/element/string.json: { “name”: “unit_sales”, “value”: “Sales (CNY)” }

  • 数据与格式化 import i18n from ‘@ohos.i18n’; import intl from ‘@ohos.intl’; import { BarChart, BarDataSet, BarEntry, IBarDataSet } from ‘@ohos/mpchart’;

    // 1) 读取当前语言，用于数字/单位本地化 const langTag = i18n.getSystemLanguage(); // 如 zh-Hans-CN / en-US const numFmt = new intl.NumberFormat(langTag, { style: ‘decimal’, minimumFractionDigits: 0, maximumFractionDigits: 2 }); const unit = $r(‘app.string.unit_sales’);

    // 2) 构造数据（示例） const entries: BarEntry[] = [ new BarEntry(0, 1234567.89), new BarEntry(1, 987654.32) ];

    // 3) 图例与轴标签本地化 const set = new BarDataSet(entries, $r(‘app.string.company_a’)); // 图例项来自资源 const data = new BarData([set]);

    // 4) 轴格式化：千分位 + 单位 leftAxis.setValueFormatter((value: number) => ${numFmt.format(value)} ${unit});

    // 5) 绑定到图表 model.setData(data);
    上述示例展示了在将数据送入 MPChart 前完成文本与数字本地化的关键步骤；图例名、单位、轴标签均来自资源或 Intl 格式化结果，从而在不同语言环境下正确显示。

五 进阶与注意事项

• 动态语言切换：系统会自动选择 resources 下对应语言资源；若需要在运行时读取或响应语言变化，可使用 i18n 获取当前 locale 并触发图表重绘（如重建数据或刷新适配器）。
• 时区与日期：涉及跨时区展示时，使用 i18n.TimeZone 与时区 ID 获取本地化城市/时区名，再用 Intl.DateTimeFormat 格式化，避免硬编码时区与格式。
• 权限提示：如需在应用内主动变更系统语言/时区/时间，需在 module.json5 中声明 ohos.permission.UPDATE_CONFIGURATION、ohos.permission.SET_TIME_ZONE、ohos.permission.SET_TIME；仅做图表本地化一般不需要这些权限。
• 默认资源：建议始终维护 base 目录下的默认资源，作为未匹配语言时的兜底。
• 性能建议：对频繁刷新的轴标签，缓存 Intl.NumberFormat/DateTimeFormat 实例，避免重复创建。