当前位置：首页 > news >正文

高德地图 Flutter 插件：跨 Android / iOS / HarmonyOS 的完整实现

news 2026/6/18 7:18:28

高德地图 Flutter 插件：跨 Android / iOS / HarmonyOS 的完整实现

背景

高德官方提供了amap_flutter_map插件，但仅支持 Android 和 iOS 平台。随着 HarmonyOS NEXT 的发布，Flutter 开发者在鸿蒙生态中缺少一份可用的高德地图插件。

本项目在官方插件的基础上，完整实现了 HarmonyOS 原生适配，使同一套 Flutter 代码可以同时运行在 Android、iOS 和 HarmonyOS 三端。

插件地址：https://gitee.com/dileber/amap_flutter_map

接入方式

在pubspec.yaml中通过 Git 依赖引入：

dependencies:amap_flutter_map:git:url:https://gitee.com/dileber/amap_flutter_map.git

支持的功能

地图基础能力

功能	说明
地图类型切换	普通地图、卫星图、导航图等
手势控制	缩放、滑动、旋转、倾斜
相机控制	移动、缩放、动画过渡
缩放级别限制	最小/最大缩放范围
地图边界限制	限制可滑动区域
自定义地图样式	支持自定义主题切换
定位蓝点	真实 GPS 定位 + 精度圈
截图	地图快照
POI 点击	地图 POI 交互

覆盖物

类型	说明
Marker	支持自定义图标、信息窗口、拖拽
Polyline	支持颜色、线宽、虚线、大地曲线、纹理
Polygon	支持填充色、边框色、边框宽度

与官方插件的核心差异：自定义地图样式

这是本插件与官方版本最重要的区别。

官方方案：二进制数据传输

官方CustomStyleOptions使用styleData和styleExtraData字段传输二进制数据：

// 官方方式ByteDatastyleByteData=awaitrootBundle.load('assets/default_style.data');_customStyleOptions.styleData=styleByteData.buffer.asUint8List();

Flutter 层将几 MB 的样式文件通过 Platform Channel 序列化传输到原生层。

本插件方案：路径引用

本插件将styleData/styleExtraData替换为styleDataPath/styleExtraDataPath，仅传递文件名：

// 本插件方式_customStyleOptions.styleDataPath="default_style.data";_customStyleOptions.styleExtraDataPath="default_style_extra.data";

原生层收到路径后，直接从本地资源目录读取文件：

Android：从assets/目录读取
HarmonyOS：从resources/rawfile/目录读取

为什么这样做？

1. 性能瓶颈

Uint8List.toString()会将每个字节逐一输出为字符串。一个 2MB 的样式文件，toString()会生成类似[0,1,2,...,255,0,1,...]的超长字符串，耗时数秒。在setState触发的组件重建中，如果CustomStyleOptions携带了二进制数据，每次重建都会触发这个比较操作，导致明显的 UI 卡顿。

2. 传输开销

Platform Channel 的StandardMessageCodec在序列化大数据时会产生额外的内存拷贝和 GC 压力。样式文件通常有几 MB，每次切换自定义地图都会触发一次完整的序列化-反序列化流程。

3. 路径方案的优势

维度	二进制传输	路径引用
Flutter→原生传输大小	几 MB	几十字节
`toString()`比较耗时	数秒	瞬间
内存占用	双倍（Flutter + Channel）	仅原生侧
切换流畅度	明显卡顿	无感知

资源文件放置

使用路径方案时，需要将样式文件放到原生资源目录：

example/android/app/src/main/assets/ ├── default_style.data └── default_style_extra.data example/ohos/entry/src/main/resources/rawfile/ ├── default_style.data └── default_style_extra.data

架构设计

┌─────────────────────────────────────────────┐ │ Flutter (Dart) │ │ AMapWidget ──→ MethodChannel ──→ Events │ └──────────────┬──────────────┬───────────────┘ │ │ ┌──────────▼──────┐ ┌───▼──────────────┐ │ Android │ │ HarmonyOS │ │ (Java/Kotlin) │ │ (ArkTS) │ │ │ │ │ │ MapController │ │ MapController │ │ AMapPlatformView│ │ AMapView │ │ ConvertUtil │ │ ConvertUtil │ └─────────────────┘ └──────────────────┘

三端共用同一套 Dart 接口，原生层各自实现。开发者无需关心平台差异，调用方式与官方插件完全一致。

快速开始

1. 配置 API Key

AMapWidget(apiKey:'your_android_ios_key',ohosApiKey:'your_harmonyos_key',initialCameraPosition:CameraPosition(target:LatLng(39.90882,116.39747),zoom:13,),onMapCreated:(controller){_mapController=controller;},)

2. 添加 Marker

AMapWidget(markers:{Marker(position:LatLng(39.90882,116.39747),title:'北京',icon:BitmapDescriptor.defaultMarker,),},)

3. 自定义地图样式

// 设置路径（在 initState 中调用）_customStyleOptions.styleDataPath="default_style.data";_customStyleOptions.styleExtraDataPath="default_style_extra.data";// 切换开关setState((){_customStyleOptions.enabled=true;});