# hs_amap_map

**Repository Path**: rongxin90/hs_amap_map

## Basic Information

- **Project Name**: hs_amap_map
- **Description**: 给予高德SDK实现的地图功能
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- @format -->

## 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](https://license/) 文件。