country_codes_ohos

国家代码辅助插件：Flutter 国家代码插件（country_codes），支持 HarmonyOS NEXT / OpenHarmony 平台。提供根据当前设备语言环境获取国家详细信息（拨号代码、ISO 3166 双字母/三字母代码、国家名称）的能力。

Android 和 iOS 的使用方法请参考 README.md。

1. 安装与使用

1.1 安装方式

在工程目录的 pubspec.yaml 中添加依赖：

方式一：Git 依赖（推荐）

dependencies:
  country_codes:
    git:
      url: https://gitcode.com/oh-flutter/country_codes.git
      ref: main

方式二：本地路径依赖

dependencies:
  country_codes:
    path: ../country_codes

然后执行：

flutter pub get

1.2 使用案例

使用示例见 example 目录。

import 'package:country_codes/country_codes.dart';

// 1. 初始化插件，获取设备语言环境
await CountryCodes.init();

// 2. 获取设备当前语言环境
final Locale? deviceLocale = CountryCodes.getDeviceLocale();
// 输出示例：Locale('zh', 'CN')

// 3. 获取当前国家的详细信息
final CountryDetails details = CountryCodes.detailsForLocale();
// 输出：United States, US, +1

// 4. 获取所有国家数据
final List<CountryDetails> allCountries = CountryCodes.countryCodes();

// 5. 根据国家代码查询
final CountryDetails cn = CountryCodes.detailsFromAlpha2('CN');

2. 功能特性

功能	说明	ohos 支持
获取设备语言 getLanguage	返回系统当前语言代码（如 zh、en）	yes
获取设备国家/地区 getRegion	返回系统当前地区代码（如 CN、US）	yes
获取完整的设备语言环境 getLocale	返回 [语言, 地区, 本地化国家名称映射]	yes
本地化国家名称	根据指定语言环境获取各国本地化名称	yes
拨号代码查询	获取各国国际电话区号	yes（纯 Dart 实现）
ISO 3166 代码查询	获取国家双字母/三字母代码	yes（纯 Dart 实现）
子地区映射	将子地区代码映射到主国家代码	yes（纯 Dart 实现）

说明：ohos 平台通过 @ohos.i18n 系统 API 获取语言和国家信息，无需额外权限。

3. 约束与限制

3.1 兼容性

在以下版本中已测试通过：

项目	版本
Flutter	3.41.10-ohos-0.0.1-canary1
Dart	3.11.5
HarmonyOS SDK	5.1.0(18)
IDE	DevEco Studio 6.1.0
设备 ROM	ALN-AL00 6.1.0.117(SP6C00E115R4P9)

3.2 依赖

依赖	版本	说明
@ohos/flutter_ohos	最新	Flutter OHOS 平台引擎绑定
@ohos.i18n	系统内置	HarmonyOS 国际化能力 API

4. API

4.1 CountryCodes 类

主要工具类，提供国家代码查询和本地化支持。

参数/方法	类型/返回值	说明	默认值	ohos 支持
init([Locale? appLocale])	Future<bool>	初始化插件，获取设备语言环境	null	yes
getDeviceLocale()	Locale?	返回当前设备 Locale	-	yes
detailsForLocale([Locale? locale])	CountryDetails	获取指定语言环境的国家详情	设备 locale	yes
detailsFromAlpha2(String alpha2)	CountryDetails	根据双字母国家代码查询	-	yes（纯 Dart）
countryCodes()	List<CountryDetails>	获取所有国家的完整列表	-	yes（纯 Dart）
dialNumbers()	List<String?>	获取所有国际区号列表	-	yes（纯 Dart）
alpha2Code([Locale? locale])	String?	获取双字母国家代码	设备 locale	yes
dialCode([Locale? locale])	String?	获取国际区号	设备 locale	yes
name({Locale? locale})	String?	获取国家名称	设备 locale	yes

4.2 init 配置

参数	类型	说明	默认值
appLocale	Locale?	应用当前使用的语言环境（用于获取本地化国家名称）	null（使用系统语言）

4.3 原生方法通道

方法名	说明	OHOS 实现	Android 实现
getLanguage	获取系统语言代码	i18n.System.getSystemLanguage()	Locale.getDefault().language
getRegion	获取系统地区代码	i18n.System.getSystemRegion()	Locale.getDefault().country
getLocale	获取完整语言环境及本地化名称	i18n.System.getSystemLanguage() + i18n.System.getSystemRegion() + i18n.getDisplayCountry()	Locale.getDefault().language + Locale.getDefault().country + Locale.getDisplayCountry()

5. 其他

实现原理

插件的整体架构为：Flutter Dart 层通过 MethodChannel 调用原生平台 API，获取设备语言和国家信息。返回的数据在 Dart 层结合内置的 ISO 3166 国家代码数据（codes.dart）进行整合处理。

在 OHOS 平台上：

• 使用 @ohos.i18n 系统 API 替代 Android 的 java.util.Locale 类
• 通过 i18n.System.getSystemLanguage() 获取系统语言
• 通过 i18n.System.getSystemRegion() 获取系统地区
• 通过 i18n.getDisplayCountry() 获取本地化国家显示名称
• 内置完整 ISO 3166-1 国家代码列表，确保与 Android 端数据一致

项目结构

ohos/
├── src/main/ets/components/plugin/
│   └── CountryCodesPlugin.ets   # 原生插件实现
├── src/main/module.json5        # HAR 模块配置
├── index.ets                    # 模块入口
├── oh-package.json5             # 包配置
└── build-profile.json5          # 构建配置

原生方法对照

方法名	OHOS 实现	Android 实现
getLanguage	i18n.System.getSystemLanguage()	Locale.getDefault().language
getRegion	i18n.System.getSystemRegion()	Locale.getDefault().country
getLocale	i18n 系统 API 组合	Java Locale 类组合

OHOS 适配说明

本插件在适配 OHOS 平台时主要做了以下修改：

1. 原生插件实现（CountryCodesPlugin.ets）：

   • 使用 @ohos.i18n 替代 Android 的 java.util.Locale
   • i18n.System.getSystemLanguage() 替代 Locale.getDefault().language
   • i18n.System.getSystemRegion() 替代 Locale.getDefault().country
   • i18n.getDisplayCountry(code, localeTag, false) 替代 Locale.getDisplayCountry(Locale.forLanguageTag(tag))
   • 内置 ISO 3166-1 国家代码列表（ArkTS 侧硬编码），对齐 Android 的 Locale.getISOCountries()
   • 使用 call.args（ArkTS 语法）获取方法调用参数，替代 call.arguments

2. Dart 层适配（lib/src/country_codes.dart）：

   • Dart 层无需改动，MethodChannel 调用签名完全一致
   • 唯一改动：原生返回的数据格式与 Android 保持相同（[String, String, Map]）

参考文档

• country_codes 官方文档
• HarmonyOS Flutter 适配指南
• @ohos.i18n API 参考

6. 遗留问题

• getLocale 方法中本地化国家名称的获取使用了内置的国家代码列表，该列表为静态硬编码。如果未来需要支持更多国家或动态更新，需考虑从系统 API 动态获取国家列表。
• 当前版本使用了 call.args as string 直接强转参数类型，如果传入参数类型非字符串会抛出异常，后续可增加参数类型校验。

7. 开源协议

本项目采用 Apache-2.0 协议，详见 LICENSE 文件。