Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 google_api_availability
Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 google_api_availability
很多 Flutter 插件并不是“有 Android 代码就能原样搬到鸿蒙”。google_api_availability 的目标是检查 Android 设备上的 Google Play Services，而鸿蒙设备没有这套服务。适配时，正确做法是保留原有 Dart API，把鸿蒙端结果准确映射为 notAvailableOnPlatform。
本文使用 google_api_availability 5.0.1、Flutter OH 3.47.4-ohos-1.0.4，从拉取代码、声明 OHOS 平台、补齐 MethodChannel、编译 HAP 到真机运行，完整走一遍。
一、最终效果
图 1：HarmonyOS API 26 真机启动适配后的 Demo。
图 2：检查后返回 notAvailableOnPlatform，数值为 6。
图 3：getErrorString() 返回平台说明。
| 验证点 | 真机结果 |
|---|---|
| Flutter | 3.47.4-ohos-1.0.4 |
| HarmonyOS | 7.0.0.105，API 26 |
| HAP | signed HAP 构建通过 |
| 服务状态 | notAvailableOnPlatform，value=6 |
| 平台说明 | Google Play Services are unavailable on OpenHarmony |
二、库的作用和适配结论
原库提供以下调用：
final result = await GoogleApiAvailability.instance
.checkGooglePlayServicesAvailability();
final message = await GoogleApiAvailability.instance.getErrorString();
状态值来自 google_api_availability_platform_interface：
| 状态 | value | 含义 |
|---|---|---|
success | 0 | 服务可用 |
serviceMissing | 1 | 服务缺失 |
serviceUpdating | 2 | 更新中 |
serviceVersionUpdateRequired | 3 | 需要更新 |
serviceDisabled | 4 | 已禁用 |
serviceInvalid | 5 | 无效 |
notAvailableOnPlatform | 6 | 当前平台不可用 |
unknown | 7 | 无法判断 |
鸿蒙端返回 6，不返回 success，也不把鸿蒙描述成 Android 服务缺失。这样业务层可以明确进行平台降级。
三、准备工具和设备
本文实际环境：
| 工具 | 版本 |
|---|---|
| Flutter OH | 3.47.4-ohos-1.0.4 |
| Dart | 3.13.3 |
| DevEco Studio | 26.0.0 Release |
| HarmonyOS SDK | API 26 |
| 测试设备 | 127.0.0.1:5555，HarmonyOS 7.0.0.105 |
环境没有准备好时，先看 Flutter OH 环境搭建指南。
检查版本和设备：
export PATH=/Users/von/Developer/flutter-oh-3.47.4/bin:$PATH
flutter --version
hdc list targets
第一条命令应看到 3.47.4-ohos，第二条命令应看到 ohos-arm64。公开文章中不要暴露设备序列号和本机证书路径。
四、拉取 AtomGit 适配分支
本文使用以下仓库和提交：
- 仓库：https://atomgit.com/oh-flutter/google_api_availability
- 分支：feat/ohos_google_api_availability_5.0.1
- 受测提交：3e05b0a4399f2d791c8087956ca0fd6af94e354d
git clone https://atomgit.com/oh-flutter/google_api_availability.git
cd google_api_availability
git switch feat/ohos_google_api_availability_5.0.1
git log -1 --oneline
锁定提交是为了让读者以后仍能复现本文这一版代码。
五、注册 OHOS 平台
在 pubspec.yaml 中声明：
flutter:
plugin:
platforms:
android:
default_package: google_api_availability_android
ohos:
pluginClass: GoogleApiAvailabilityPlugin
入口文件是：
ohos/index.ets
ohos/src/main/ets/components/plugin/GoogleApiAvailabilityPlugin.ets
ohos/index.ets：
import GoogleApiAvailabilityPlugin from './src/main/ets/components/plugin/GoogleApiAvailabilityPlugin';
export default GoogleApiAvailabilityPlugin;
如果只新增 ArkTS 文件而忘记 pubspec.yaml，Flutter 不会加载 OHOS 插件。
六、补齐 Dart MethodChannel
原平台接口包默认实例可能没有注册到鸿蒙插件，因此适配层使用自己的 MethodChannel 实现，调用同一个通道：
const MethodChannel('google_api_availability');
核心实现：
Future<GooglePlayServicesAvailability> checkGooglePlayServicesAvailability([
bool showDialogIfNecessary = false,
]) async {
final value = await methodChannel.invokeMethod<int>(
'checkGooglePlayServicesAvailability',
showDialogIfNecessary,
);
return GooglePlayServicesAvailability.byValue(value ?? 7);
}
Future<String> getErrorString() async {
return await methodChannel.invokeMethod<String>('getErrorString') ?? '';
}
Dart 层返回整数再转换为枚举，是为了复用上游已经定义好的状态对象。这样业务代码仍然可以写：
final result = await GoogleApiAvailability.instance
.checkGooglePlayServicesAvailability();
if (result == GooglePlayServicesAvailability.notAvailableOnPlatform) {
// 切换到鸿蒙侧替代方案
}
七、实现 ArkTS 平台语义
ArkTS 插件注册通道：
this.channel = new MethodChannel(
binding.getBinaryMessenger(),
'google_api_availability',
);
this.channel.setMethodCallHandler(this);
鸿蒙端检查状态：
case 'checkGooglePlayServicesAvailability':
result.success(6);
return;
平台说明：
case 'getErrorString':
result.success('Google Play Services are unavailable on OpenHarmony');
return;
其他 API 的处理如下：
| 方法 | OHOS 行为 |
|---|---|
makeGooglePlayServicesAvailable | 空操作成功返回 |
isUserResolvable | 返回 false |
showErrorNotification | 不发送 Android 风格通知 |
showErrorDialogFragment | 返回 false |
| 未知方法 | notImplemented() |
这不是把所有 API 都伪装成成功，而是保留调用契约并准确表达平台边界。
八、制作新手 Demo
Demo 页面只有两个按钮：检查服务状态、读取平台说明。初始化时自动检查一次：
void initState() {
super.initState();
_check();
}
检查方法：
Future<void> _check() async {
try {
final result = await GoogleApiAvailability.instance
.checkGooglePlayServicesAvailability();
if (!mounted) return;
setState(() {
_status = result.toString().split('.').last;
_detail = 'value=${result.value}，鸿蒙端返回 notAvailableOnPlatform';
});
} catch (error) {
if (!mounted) return;
setState(() {
_status = '调用失败';
_detail = '$error';
});
}
}
这里的 mounted 用来避免页面退出后异步回调继续调用 setState。
九、构建、签名和安装
先检查依赖、分析和 HAP：
flutter pub get
flutter analyze
cd example
flutter test
flutter build hap --debug --no-codesign
未签名 HAP 只证明编译通过。安装真机前，在 DevEco Studio 打开 example/ohos，进入 File -> Project Structure -> Signing Configs，勾选自动生成调试签名，然后执行：
flutter build hap --debug
hdc list targets
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo
签名证书、密码和本机绝对路径不要提交到公开仓库。
十、真机验证
启动后页面显示 notAvailableOnPlatform 和 value=6。点击“读取平台说明”后显示 Google Play Services are unavailable on OpenHarmony。
这验证了四层链路：
- Flutter 页面调用 Dart API。
- Dart MethodChannel 发出方法名。
- ArkTS 插件收到方法调用。
- ArkTS 返回的整数被 Dart 转成官方枚举。
这不代表鸿蒙可以运行依赖 Google Play Services 的业务。业务应该根据状态切换到鸿蒙等价服务，或者隐藏依赖 Google 服务的入口。
十一、常见问题
Q1：为什么不能返回 success
鸿蒙没有 Google Play Services。返回 success 会让业务误以为 Google Maps、Firebase 或其他 Google SDK 可以直接使用。
Q2：为什么显示 Unsupported operation
平台接口包的默认实现会抛出“不支持平台”。检查 Dart 端是否使用适配后的 MethodChannel 实现，以及 pubspec.yaml 是否注册了 ohos。
Q3：为什么状态是 unknown
检查 ArkTS 返回值是否为 0 到 7，以及 Dart 是否使用 GooglePlayServicesAvailability.byValue()。
Q4：为什么不弹“请安装 Google 服务”
鸿蒙设备不能通过 Android 的 Google Play Services 安装流程解决问题。返回平台不可用比给用户一个无法执行的安装建议更准确。
十二、复现命令
git clone https://atomgit.com/oh-flutter/google_api_availability.git
cd google_api_availability
git switch feat/ohos_google_api_availability_5.0.1
export PATH=/Users/von/Developer/flutter-oh-3.47.4/bin:$PATH
flutter pub get
flutter analyze
cd example
flutter test
flutter build hap --debug --no-codesign
十三、总结
这次适配的重点不是复制 Android 代码，而是先确认能力边界，再保持原有 API。Flutter 3.47 鸿蒙端继续提供 google_api_availability 的调用入口，但结果明确返回 notAvailableOnPlatform，让业务可以在正确的位置做降级。
十四、参考资料与仓库地址
本文适配仓库
上游和包信息
- pub.dev：google_api_availability
- pub.dev：版本记录
- pub.dev：API 文档
- pub.dev：平台接口包
- 平台接口 API 文档
- 上游 GitHub 仓库
- 上游源码目录
- 上游许可证
Flutter 和鸿蒙资料
- Flutter 官方插件开发文档
- Flutter MethodChannel 文档
- Flutter PlatformInterface 文档
- Flutter OH 环境搭建指南
- HarmonyOS 开发者官网
- HarmonyOS ArkTS 文档
- HarmonyOS API 参考
- HarmonyOS 签名和调试文档
欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter
作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。
更多推荐
0
0- 0
已为社区贡献12条内容
所有评论(0)