晚霞的不甘头像
Flutter/OpenHarmony 三方库适配实战:google_maps_flutter 地图封面图

Flutter/OpenHarmony 三方库适配实战:google_maps_flutter 地图

Flutter/OpenHarmony 三方库适配实战:google_maps_flutter 地图

一、项目信息

项目内容
仓库名称google_maps_flutter
仓库地址https://atomgit.com/oh-flutter/google_maps_flutter
基于版本google_maps_flutter 2.19.0
适配 TAG2.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 OH3.44.9+ohos-0.0.1-canary1
Dart3.12.2
DevEco Studio26.0.0
HarmonyOS SDKAPI 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。

业务接入时应:

  1. 在高德开放平台申请 OHOS Key。
  2. 确认 Key 的 Bundle Name 与宿主 HAP 一致。
  3. 调试签名和发布签名分别配置。
  4. 通过 --dart-define 注入 Key 后重新构建安装。
  5. 检查日志中不再出现 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
当前已发布 TAG2.19.0-ohos-1.0.1
适配分支main
目标最新 TAG2.19.0-ohos-1.0.1
最终提交d400df2

版本号更新只代表文章和适配分支的基线已对齐;涉及上游 API 变更时,仍需在该 TAG 上重新运行 Dart 测试、ArkTS 编译、HAP 安装和真机回归。

参考资料和仓库地址

欢迎加入 CPF-Flutter 鸿蒙社区。

转载自 CSDN-专业IT技术社区

原文链接:https://blog.csdn.net/2501_93573294/article/details/168561733

文章来源转载

评论

评论列表

微信小程序
QQ小程序

关于作者

点赞数:0
关注数:0
粉丝:0
文章:0
关注标签:0
加入于:--