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 配置

在业务 App 的 ios/Runner/Info.plist 中添加（注意是业务项目，不是插件项目）：

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

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

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

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

注意事项：

  • NSAppTransportSecurity 只保留一段，避免重复定义。
  • 不需要额外开启 iOS Capabilities 的网络权限。
  • 若地图空白但定位有值，优先检查：MAMapAPIKey、Bundle ID 绑定、网络连通性。

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.

Libraries

amap_fl_plugin
amap_plugins
amap_plugins_platform_interface