amap_fl_plugin 0.1.2

Flutter plugin for AMap (Gaode) with 2D map, marker and location support.

amap_fl_plugin

一个用于接入高德地图（AMap/Gaode）的 Flutter 插件，支持 Android / iOS。

当前版本聚焦 MVP 能力（0.1.1 含 Android 混淆保留规则修复）：

• 2D 地图显示（PlatformView）
• Marker 添加与清空
• 用户定位蓝点展示
• 地图点击事件回调
• 定位事件回调
• 轨迹折线绘制与清除

---

1. 环境要求

• Flutter: >=3.9.2
• Dart SDK: ^3.9.2
• Android minSdk: 24
• iOS: 13.0+

---

2. 安装

在业务项目 pubspec.yaml 中添加：

dependencies:
  amap_fl_plugin: ^0.1.0

然后执行：

flutter pub get

---

3. 平台配置

3.1 Android 配置

在你的 App AndroidManifest.xml（通常是 android/app/src/main/AndroidManifest.xml）中添加权限与 Key：

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

<meta-data
    android:name="com.amap.api.v2.apikey"
    android:value="YOUR_ANDROID_AMAP_KEY" />

注意：Android 6.0+ 仍需运行时动态申请定位权限。

3.2 iOS 配置

在 ios/Runner/Info.plist 中添加：

<key>MAMapAPIKey</key>
<string>YOUR_IOS_AMAP_KEY</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>用于在地图上展示您的当前位置</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>用于持续定位服务</string>

---

4. 快速开始

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

class AMapSimplePage extends StatefulWidget {
  const AMapSimplePage({super.key});

  @override
  State<AMapSimplePage> createState() => _AMapSimplePageState();
}

class _AMapSimplePageState extends State<AMapSimplePage> {
  AMapFlPluginController? _controller;

  static const _beijing = AMapLatLng(latitude: 39.909187, longitude: 116.397451);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AMap Demo')),
      body: AMapView(
        initialCenter: _beijing,
        initialZoom: 14,
        myLocationEnabled: true,
        markers: const [
          AMapMarker(
            id: 'm1',
            position: _beijing,
            title: '天安门',
            snippet: '示例点',
          ),
        ],
        onMapCreated: (controller) {
          _controller = controller;

          controller.onMapTap.listen((point) {
            debugPrint('tap => ${point.latitude}, ${point.longitude}');
          });

          controller.onLocationChanged.listen((point) {
            debugPrint('location => ${point.latitude}, ${point.longitude}');
          });
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          _controller?.setCenter(_beijing, zoom: 16);
        },
        child: const Icon(Icons.my_location),
      ),
    );
  }
}

---

5. API 文档

5.1 数据模型

AMapLatLng

const AMapLatLng({required double latitude, required double longitude})

• latitude: 纬度
• longitude: 经度

AMapMarker

const AMapMarker({
  required String id,
  required AMapLatLng position,
  String? title,
  String? snippet,
})

• id: Marker 唯一标识
• position: 坐标
• title: 标题
• snippet: 副标题

5.2 地图组件

AMapView

AMapView({
  Key? key,
  AMapLatLng initialCenter = const AMapLatLng(latitude: 39.909187, longitude: 116.397451),
  double initialZoom = 15.0,
  bool myLocationEnabled = true,
  List<AMapMarker> markers = const <AMapMarker>[],
  ValueChanged<AMapFlPluginController>? onMapCreated,
})

• initialCenter: 初始中心点
• initialZoom: 初始缩放
• myLocationEnabled: 是否显示定位蓝点
• markers: 初始 Marker 列表
• onMapCreated: 地图创建完成回调

5.3 控制器

setCenter

Future<void> setCenter(AMapLatLng center, {double zoom = 15.0})

将地图移动到指定中心点。

setMyLocationEnabled

Future<void> setMyLocationEnabled(bool enabled)

开启/关闭定位蓝点。

addMarker

Future<void> addMarker(AMapMarker marker)

动态添加或覆盖同 id 的 Marker。

clearMarkers

Future<void> clearMarkers()

清空当前所有 Marker。

setTrack

Future<void> setTrack(
  List<AMapLatLng> points, {
  int color = 0xFF1976D2,
  double width = 8,
})

绘制轨迹折线。要求 points.length >= 2。

clearTrack

Future<void> clearTrack()

清除当前轨迹。

onMapTap

Stream<AMapLatLng> get onMapTap

监听地图单击坐标。

onLocationChanged

Stream<AMapLatLng> get onLocationChanged

监听定位更新坐标。

---

6. 轨迹测试建议

你可以通过以下方式验证轨迹能力：

1. 固定轨迹绘制：传入预设点集 setTrack(points)。
2. 手动偏移模拟：每次基于当前点做小范围经纬度偏移，并持续追加点集后重绘轨迹。
3. 模拟定位/真机移动：使用模拟器 GPS 或真机移动，收到定位流后累积绘制轨迹。

当前实现机制：

• Flutter 端维护轨迹点集合；
• 每次调用 setTrack，原生端移除旧折线并重建新折线；
• clearTrack 删除原生折线对象。

---

7. 常见问题

Q1: 地图显示正常，但“定位到我”偶发跳到空白区域？

可能收到了无效定位点（例如 (0,0)）。建议业务层对坐标做有效性校验后再 setCenter。

Q2: Android 日志出现 isHighTextContrastEnabled 相关报错怎么办？

这是部分机型/ROM 下高德 SDK 内部兼容日志，常见为 warning。如果地图与定位功能正常，可暂时忽略；后续可尝试升级高德 SDK 版本验证是否改善。

Q3: 为什么地图上有蓝点，但 Dart 层还未收到定位流？

蓝点绘制与 Dart 事件回传不一定完全同步，首帧阶段可能有短暂延迟。

---

8. 发布说明（维护者）

发布前建议执行：

flutter analyze
flutter test
dart pub publish --dry-run

并确保：

• README.md / CHANGELOG.md / LICENSE 完整
• example/ 可运行
• 平台 Key 配置说明清晰

---

9. License

See LICENSE.