hs_amap_map 1.0.2

A Flutter plugin for AMap (AutoNavi) maps. Supports 2D/3D map rendering, marker customization, camera position control, and zoom/rotation gestures for both iOS and Android.

hs_amap_map

https://img.shields.io/pub/v/hs_amap_map.svg

一个生产级的 Flutter 高德地图插件，支持 3D 地图、丰富标记（Marker）、相机控制、手势检测及 UI 控件。内置完善的隐私合规与 API Key 动态配置，适用于需要深度集成高德地图的移动端应用。

特性速览

• ✅ 显示高德 2D/3D 地图，支持标准模式
• ✅ 添加自定义 Marker，支持 Asset / 网络 / 本地文件 / 字节数组图标
• ✅ Marker 动画：缩放弹出（grow）、从上方掉落（drop）
• ✅ 图标缩放，动态调整标记大小
• ✅ 相机控制：移动、动画、视角限制、获取当前可视区域
• ✅ 完整事件：地图点击/长按、Marker 点击、相机移动开始/移动中/移动结束，精确区分手势拖动与代码调用
• ✅ UI 控件：当前位置蓝点、缩放按钮、指北针（可单独开关）
• ✅ 双端统一 API Key 设置与隐私合规方法
• ✅ 支持多地图实例

---

安装

在你的 pubspec.yaml 中添加：

yaml

dependencies:
  hs_amap_map: ^1.0.0

然后执行 flutter pub get。

---

配置

Android

1. 注册高德 Android Key 在 android/app/src/main/AndroidManifest.xml 中 <application> 标签内添加：

   xml

   <meta-data
       android:name="com.amap.api.v2.apikey"
       android:value="你的 Android Key" />
   

2. 权限（插件已默认声明，若主工程未覆盖可手动添加）：

   xml

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
   <uses-permission android:name="android.permission.READ_PHONE_STATE" />
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
   

3. 隐私合规（必须） 在创建任何地图之前调用 HsAmapMap.setPrivacyAgreed(true)。

iOS

1. 注册高德 iOS Key 在 main() 中调用：

   dart

   HsAmapMap.setApiKey(iosKey: '你的 iOS Key');
   

2. 隐私合规（必须） 同样需要调用：

   dart

   HsAmapMap.setPrivacyAgreed(true);
   

3. 权限描述 在 ios/Runner/Info.plist 中添加：

   xml

   <key>NSLocationWhenInUseUsageDescription</key>
   <string>需要使用您的位置信息</string>
   <key>NSLocationAlwaysUsageDescription</key>
   <string>需要使用您的位置信息</string>
   

---

基本使用

dart

import 'package:flutter/material.dart';
import 'package:hs_amap_map/hs_amap_map.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 必须先同意隐私政策
  await HsAmapMap.setPrivacyAgreed(true);
  // 设置 iOS Key（Android Key 通过 Manifest 配置）
  await HsAmapMap.setApiKey(iosKey: '你的 iOS Key');
  runApp(MyApp());
}

class MapPage extends StatefulWidget { ... }

class _MapPageState extends State<MapPage> {
  HSAmapController? _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: HSAmapView(
        initialCameraPosition: HSCameraPosition(
          target: HSLatLng(39.904989, 116.405285),
          zoom: 12,
        ),
        onMapCreated: (controller) {
          _controller = controller;
        },
        onMapClick: (latLng) => print('点击地图: $latLng'),
        onMarkerClick: (id) => print('点击标记: $id'),
        // 手势拖动监听
        onCameraMoveStarted: (reason) {
          if (reason == HSCameraMoveReason.gesture) {
            print('用户开始拖拽地图');
          }
        },
        onCameraMoveEnded: (position, reason) {
          if (reason == HSCameraMoveReason.gesture) {
            print('拖拽结束，中心点: ${position.target}');
          }
        },
      ),
    );
  }
}

---

API 概览

全局配置类 HsAmapMap

方法	说明
setApiKey({required String iosKey})	设置高德 API Key（Android 建议用 Manifest，此处仅 iOS 生效）
setPrivacyAgreed(bool agreed)	设置隐私合规同意（Android 必须调用）

地图视图 HSAmapView

参数	类型	说明
initialCameraPosition	HSCameraPosition?	初始相机位置
initialMarkers	Set<HSMarker>	初始标记集合
mapType	HSMapType	地图类型：standard, satellite, night
styleJson	String?	自定义地图样式 JSON
showMyLocation	bool	是否显示当前位置蓝点，默认 false
showZoomControls	bool	是否显示缩放按钮（Android），默认 true
showCompass	bool	是否显示指北针，默认 true

事件回调

回调	触发时机
onMapCreated	地图创建完成，返回 HSAmapController
onMapClick	点击地图空白处
onMapLongPress	长按地图
onMarkerClick	点击标记，返回 markerId
onCameraMoveStarted	相机开始移动，返回 HSCameraMoveReason（gesture/api）
onCameraMove	相机移动中（高频）
onCameraMoveEnded	相机移动结束，返回最终位置和原因

控制器 HSAmapController

方法	说明
moveCamera(HSCameraUpdate)	无动画移动相机
animateCamera(HSCameraUpdate, {int durationMs})	动画移动相机
updateMarkers(Set<HSMarker>)	全量更新标记
getVisibleRegion()	获取当前地图可视区域
setMapStyle(String? styleJson)	设置自定义样式（null 恢复默认）
setMapType(HSMapType)	切换地图类型
setMyLocationEnabled(bool)	开启/关闭当前位置显示
setZoomControlsEnabled(bool)	开启/关闭缩放按钮
setCompassEnabled(bool)	开启/关闭指北针
dispose()	销毁当前地图资源

数据类型

• HSLatLng：经纬度
• HSLatLngBounds：经纬度范围
• HSCameraPosition：相机位置（目标、缩放、倾斜、旋转）
• HSCameraUpdate：相机移动目标（支持点、点+缩放、区域）
• HSMarker：标记点，包含 id、位置、图标、锚点、动画等
• HSBitmapDescriptor：图标描述（支持 Asset / 网络 / 文件 / 字节）
• HSCameraMoveReason：相机移动原因（gesture / api）

高级功能：带动画的 Marker

dart

HSMarker(
  id: 'animated',
  position: HSLatLng(39.9, 116.4),
  icon: HSBitmapDescriptor.fromNetwork('https://example.com/pin.png', scale: 1.5),
  animationType: HSMarkerAnimationType.drop,  // drop / grow
  animationDuration: 500,
)

---

完整示例

见项目 example/lib/main.dart，包含地图初始化、添加标记、事件监听和 UI 控件切换的完整演示。

---

注意事项

• Android 必须在 AndroidManifest.xml 中配置 API Key，否则地图不显示。
• 隐私合规：必须调用 HsAmapMap.setPrivacyAgreed(true)，否则 Android 直接崩溃，iOS 地图黑屏。
• iOS 需要设置 AMapFoundationKit 版本 ≥1.6.0，否则隐私方法可能不同。
• 自定义网络图标仅在 Android 端自动下载缓存，iOS 需自行扩展或后续版本支持。
• 地图 Widget 需要明确的尺寸，否则可能显示为 0 高度。

---

许可证

MIT License. 查看 LICENSE 文件。