Flutter/OpenHarmony 三方库适配实战:google_maps_flutter 地图
一、项目信息
| 项目 | 内容 |
|---|---|
| 仓库名称 | google_maps_flutter |
| 仓库地址 | https://atomgit.com/oh-flutter/google_maps_flutter |
| 基于版本 | google_maps_flutter 2.19.0 |
| 适配 TAG | 2.19.0-ohos-1.0.1 |
| OHOS 插件包 | google_maps_flutter_ohos |
| OHOS 原生入口 | AMapFlutterMapPlugin |
| Dart 注册类 | GoogleMapsFlutterOhos |
| OHOS 地图 SDK | @amap/amap_lbs_map3d 11.1.104 |
google_maps_flutter 的 Dart API 定义了地图 Widget、相机、标记、折线、多边形和
事件模型,但 OpenHarmony 不提供 Google Maps 原生服务。本次适配保留
GoogleMap 的使用方式,在 OHOS 平台使用高德地图 SDK 渲染原生地图。
适配不是把 Dart 地图对象重写为 ArkTS 组件,而是建立一层模型转换:
GoogleMap Widget
|
v
Dart Platform Interface
|
v
GoogleMapsFlutterOhos
|
v
PlatformView + 每个地图实例独立 MethodChannel
|
v
AMapMethodChannel / Controller / Overlay Controller
|
v
MapViewComponent + AMap OHOS SDK

环境搭建与版本
下面是本次适配实际使用的环境。环境搭建过程这里不再展开,直接看 Flutter OH 环境搭建指南。
| 项目 | 版本/说明 |
|---|---|
| Flutter OH | 3.44.9+ohos-0.0.1-canary1 |
| Dart | 3.12.2 |
| DevEco Studio | 26.0.0 |
| HarmonyOS SDK | API 26 |
| 目标仓库 | google_maps_flutter |
二、适配边界
本次实现支持:
- 使用
GoogleMap创建原生地图 PlatformView。 - 初始相机位置和
onMapCreated回调。 moveCamera、animateCamera和相机事件。- Marker、Polyline、Polygon 的创建、更新和删除。
- 地图点击、长按和基本手势事件。
- 定位蓝点配置所需的能力接入。
以下能力需要业务侧额外验证或暂不作为稳定能力:
- 需要精确匹配 Google Maps SDK 的高级瓦片能力。
- 未在当前模拟器完成有效 Key 下的地图瓦片截图。
- 路径规划、搜索、POI 和 Google 专有云服务。
- 依赖特定 Google Maps 行为的业务插件。
三、依赖与 TAG
业务工程引用 AtomGit 仓库:
dependencies:
google_maps_flutter:
git:
url: https://atomgit.com/oh-flutter/google_maps_flutter.git
path: packages/google_maps_flutter/google_maps_flutter
ref: 2.19.0-ohos-1.0.1
执行:
flutter pub get
OHOS 平台包在 pubspec.yaml 中同时声明原生插件类和 Dart 注册类:
flutter:
plugin:
platforms:
ohos:
package: com.amap.flutter.map
pluginClass: AMapFlutterMapPlugin
dartPluginClass: GoogleMapsFlutterOhos
pluginClass 负责注册 PlatformView 工厂,dartPluginClass 将
GoogleMapsFlutterPlatform.instance 指向 OHOS 实现。
OHOS 工程目录创建
本次适配前,上游仓库没有 ohos/ 目录。适配分支上按 Flutter OH 的插件工程约束创建平台目录,再把 ArkTS 入口接入 pubspec.yaml:
git switch -c <your-ohos-adaptation-branch>
flutter create --platforms ohos .
工程生成后至少保留以下边界:
ohos/
├── index.ets
├── oh-package.json5
└── src/main/
├── module.json5
└── ets/components/plugin/
示例工程还需要生成 example/ohos/,并在插件 pubspec.yaml 的 flutter.plugin.platforms.ohos 中声明 pluginClass;只创建目录、没有注册入口,Dart 方法通道仍然不会工作。
四、注册 PlatformView 工厂
原生插件在引擎附加时注册地图视图类型:
const VIEW_TYPE = 'plugins.flutter.io/google_maps';
export default class AMapFlutterMapPlugin implements FlutterPlugin {
onAttachedToEngine(binding: FlutterPluginBinding): void {
AMapCreateListener.getInstance().init();
ConvertUtil.init();
binding.getPlatformViewRegistry()?.registerViewFactory(
VIEW_TYPE,
new AMapPlatformViewFactory(
binding.getBinaryMessenger(),
StandardMessageCodec.INSTANCE,
),
);
}
}
地图工厂为每个 viewId 创建独立的 AMapPlatformView:
create(
viewId: number,
args: Object,
messenger: BinaryMessenger,
): PlatformView {
return new AMapPlatformView(viewId, args, messenger);
}
每个视图使用自己的通道:
plugins.flutter.io/google_maps_<viewId>
这种设计可以同时创建多张地图,也避免一个地图的相机、覆盖物和点击事件错误地
发送给另一个地图。
五、ArkTS 地图组件
PlatformView 最终渲染 ArkUI 的地图组件:
@Component
export default struct AMapView {
@Prop params: Params;
customView: AMapPlatformView =
this.params.platformView as AMapPlatformView;
viewId: number = this.customView.getViewId();
aboutToDisappear(): void {
AMapCreateListener.getInstance().destroyView(this.viewId);
}
build(): void {
MapViewComponent({
mapViewName: this.viewId.toString(),
})
.width('100%')
.height('100%');
}
}
mapViewName 与 viewId 一一对应。地图 SDK 创建 AMap 对象后通过事件通知对应
的 AMapMethodChannel,通道再完成控制器初始化和初始参数应用。
组件销毁时必须反注册监听并销毁 MapView,否则页面退出后可能残留原生地图对象。
六、地图就绪与方法分发
AMapMethodChannel 为每个视图创建 MethodChannel,并把方法分发给相机、Marker、
Polyline、Polygon 等控制器:
constructor(
viewId: number,
args: Object,
binaryMessenger: BinaryMessenger,
) {
this.viewId = viewId;
this.args = args as Map<string, Object>;
this.channel = new MethodChannel(
binaryMessenger,
METHOD_CHANNEL_PREFIX + viewId,
);
this.channel.setMethodCallHandler(this);
this.registerAMapCreateEvent();
}
如果 Dart 在地图组件尚未创建时调用 waitForMap,原生侧缓存当前 MethodResult,
等地图创建完成后统一回复:
if (call.method === UserEvent.METHOD_MAP_WAIT_FOR_MAP) {
if (this.aMap) {
result.success(null);
} else {
this.mapReadyResult = result;
}
return;
}
这种方式可以避免业务在 onMapCreated 之前过早控制相机时出现随机失败。
七、隐私初始化和 Key 配置
高德 SDK 要求在创建地图前处理隐私合规。宿主 Ability 在窗口创建阶段调用:
AMapFlutterMapPlugin.initializePrivacy(this.context);
插件内部完成一次性初始化:
static initializePrivacy(context: common.Context): void {
MapsInitializer.initialize(context);
MapsInitializer.updatePrivacyShow(
AMapPrivacyShowStatus.DidShow,
AMapPrivacyInfoStatus.DidContain,
context,
);
MapsInitializer.updatePrivacyAgree(
AMapPrivacyAgreeStatus.DidAgree,
context,
);
}
隐私状态必须由宿主应用根据真实交互流程设置,插件不能替业务绕过用户授权。
地图还需要 OHOS Key。不要把 Key 写入源码,应通过构建参数传入:
flutter build hap \
--debug \
--dart-define=AMAP_OHOS_KEY=<你的高德OHOS Key>
Key 必须与 HAP 的 Bundle Name 和签名信息匹配。调试包与发布包应按地图服务提供方
的规则分别配置。
在线地图还需要网络权限;使用定位蓝点时还需要声明定位权限、用途说明和
usedScene:
{
module: {
requestPermissions: [
{ name: 'ohos.permission.INTERNET' },
{ name: 'ohos.permission.APPROXIMATELY_LOCATION' },
{ name: 'ohos.permission.LOCATION' },
],
},
}
八、Dart 业务示例
业务代码继续使用原库 API:
class MapDemoPage extends StatefulWidget {
const MapDemoPage({super.key});
State<MapDemoPage> createState() => _MapDemoPageState();
}
class _MapDemoPageState extends State<MapDemoPage> {
GoogleMapController? _controller;
Widget build(BuildContext context) {
return GoogleMap(
initialCameraPosition: const CameraPosition(
target: LatLng(39.909187, 116.397416),
zoom: 12,
),
markers: <Marker>{
Marker(
markerId: const MarkerId('demo'),
position: const LatLng(39.909187, 116.397416),
),
},
onMapCreated: (controller) {
_controller = controller;
},
onTap: (position) {
debugPrint('map tap: $position');
},
);
}
void dispose() {
_controller?.dispose();
super.dispose();
}
}
地图移动可以直接复用 CameraUpdate:
await _controller?.animateCamera(
CameraUpdate.newLatLng(
const LatLng(31.230416, 121.473701),
),
);
适配过程 FAQ 与解决方案
为什么地图适配不能只返回一个空 PlatformView?
解决方案: Flutter 需要拿到真实的地图纹理或平台视图,并把相机、标记和点击事件回传。空视图只能证明页面能打开,不能证明地图 SDK 已经初始化。
地图白屏时先检查 Key、MapReady 还是 PlatformView?
解决方案: 按初始化顺序检查:隐私协议和 Key -> OHOS 地图 SDK 初始化 -> MapReady 回调 -> PlatformView 创建 -> Dart 事件通道。只改 Dart 层的尺寸或背景会掩盖底层初始化失败。
相机移动事件为什么需要独立 EventChannel?
解决方案: 相机状态是连续事件,不适合用一次 MethodChannel 返回值表达。独立事件流还要在页面销毁时解绑,否则地图移动会不断向旧 Dart 对象发事件。
模拟器地图截图能证明什么?
解决方案: 它可以证明地图组件能创建、相机方法能调用和事件链路能返回;真实导航、定位精度、地图瓦片和权限策略仍要在真机上验证。
九、构建和模拟器结果
验证环境:
- Flutter:
3.44.9+ohos-0.0.1-canary1 - OHOS SDK:
26 - DevEco Studio:
26.0.0 - 模拟器:
emulator 7.0.0.107(SP8DEVC00E999R4P11)
验证结果:
flutter analyze --no-pub通过。- 2 个 Dart 测试通过。
- HAP 构建、安装和启动成功。
- PlatformView 工厂已注册,地图容器已经创建。
- 模拟器日志出现
AMapErrorInvaildUserKey 10001。
业务接入时应:
- 在高德开放平台申请 OHOS Key。
- 确认 Key 的 Bundle Name 与宿主 HAP 一致。
- 调试签名和发布签名分别配置。
- 通过
--dart-define注入 Key 后重新构建安装。 - 检查日志中不再出现
10001,再进行地图渲染验收。
十、资源释放
引擎分离时,插件按顺序释放通道、定位监听和地图对象:
onDetachedFromEngine(binding: FlutterPluginBinding): void {
AMapMethodChannel.releaseAll();
AMapCreateListener.getInstance().unregisterMapViewCreatedCallback();
LocationHelper.getInstance().stopAllLocate();
AMapCreateListener.getInstance().clearAll();
ConvertUtil.reset();
}
每个 AMapMethodChannel 也会解绑自身方法处理器并清空控制器。这样页面销毁、热
重启或引擎重建时,不会继续向旧地图发送方法调用。
十一、代码提交与协作
本次适配已推送到 AtomGit main 分支,并创建 TAG:
main: 39c5b9ff1dfbae9753b63bd90c95d98e3958bafa
tag: 2.19.0-ohos-1.0.1
欢迎加入 CPF-Flutter 鸿蒙社区,参与 Flutter
OHOS 地图适配、PlatformView 和模拟器/真机 Key 验证经验交流。
- 仓库地址:https://atomgit.com/oh-flutter/google_maps_flutter
- 提交 Issue:https://atomgit.com/oh-flutter/google_maps_flutter/issues
- 提交 Pull Request:https://atomgit.com/oh-flutter/google_maps_flutter/pulls
版本与提交基线
| 项目 | 版本/地址 |
|---|---|
| 上游包 | google_maps_flutter |
| 上游最新版本 | 2.19.0 |
| 文章目标基线 | 2.19.0-ohos-1.0.1 |
| 当前已发布 TAG | 2.19.0-ohos-1.0.1 |
| 适配分支 | main |
| 目标最新 TAG | 2.19.0-ohos-1.0.1 |
| 最终提交 | d400df2 |
版本号更新只代表文章和适配分支的基线已对齐;涉及上游 API 变更时,仍需在该 TAG 上重新运行 Dart 测试、ArkTS 编译、HAP 安装和真机回归。
参考资料和仓库地址
- 适配仓库主页
- 适配分支 main
- 当前已发布 TAG 2.19.0-ohos-1.0.1
- 目标最新 TAG 2.19.0-ohos-1.0.1
- 最终提交 d400df2
- ArkTS 通道实现
- 鸿蒙适配说明
- pub.dev 包页面
- pub.dev 2.19.0 版本页
- 上游仓库
- Flutter 官方插件与平台通道文档
- Flutter OH 鸿蒙 SDK 仓库
欢迎加入 CPF-Flutter 鸿蒙社区。
转载自 CSDN-专业IT技术社区
原文链接:https://blog.csdn.net/2501_93573294/article/details/168561733




