amap_flutter_location_plus_x_maintained 1.0.1

维护版高德定位 SDK Flutter 插件，支持 Android 和 iOS。

amap_flutter_location_plus_x_maintained

高德定位 SDK 的 Flutter 插件，封装 Android 和 iOS 原生定位能力。插件支持多实例、连续定位、单次定位、逆地理信息、iOS 14+ 定位精度授权和高德隐私合规初始化。

当前维护版本针对以下 SDK 版本验证：

• Android：高德定位 SDK 11.1.000
• iOS：CocoaPods AMapLocation 2.11.1
• Flutter：>=3.29.0

安装

在应用的 pubspec.yaml 中添加：

dependencies:
  amap_flutter_location_plus_x_maintained: ^1.0.1

然后执行：

flutter pub get

使用前配置

插件不负责申请系统定位权限，也不会替应用保存 API Key。宿主应用需要按照自己的隐私合规流程完成以下配置。

1. 配置高德 API Key

分别在高德开放平台申请 Android 和 iOS Key，并在应用运行时传入。不要把真实 Key 写入插件源码、示例代码或日志。

2. 配置 Android

宿主应用的 android/app/src/main/AndroidManifest.xml 至少声明定位权限：

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

如果应用需要后台定位，还需要根据 Android 版本配置 ACCESS_BACKGROUND_LOCATION、前台服务权限及对应的前台服务。定位权限仍须由宿主应用在运行时申请。

由于插件的 Android 原生依赖使用 compileOnly，宿主应用必须提供高德 Android 定位 SDK 运行时依赖：

dependencies {
    implementation 'com.amap.api:location:11.1.000'
}

如果宿主应用同时使用其他高德插件，请确认它们使用的高德 SDK 版本和类没有重复打包；版本冲突时以宿主应用的统一依赖策略为准。

3. 配置 iOS

在宿主应用的 Info.plist 中配置用途说明：

<key>NSLocationWhenInUseUsageDescription</key>
<string>用于获取当前位置。</string>

需要后台定位时，再按业务和系统版本补充 NSLocationAlwaysAndWhenInUseUsageDescription、后台 Location Updates 能力等配置。需要从模糊定位临时提升到精确定位时，配置 NSLocationTemporaryUsageDescriptionDictionary，并让字典中的 Key 与 fullAccuracyPurposeKey 一致。

基本用法

建议在用户同意隐私政策后，按顺序完成隐私状态、API Key、监听、定位参数和启动：

import 'package:amap_flutter_location_plus_x_maintained/amap_flutter_location_plus.dart';
import 'package:amap_flutter_location_plus_x_maintained/amap_location_option.dart';

final location = AMapFlutterLocation();

Future<void> start() async {
  await AMapFlutterLocation.updatePrivacyShow(true, true);
  await AMapFlutterLocation.updatePrivacyAgree(true);
  await AMapFlutterLocation.setApiKey(
    androidKey,
    iosKey,
  );

  final subscription = location.onLocationChanged().listen((result) {
    final errorCode = result['errorCode'];
    if (errorCode != null) {
      // 根据业务展示或记录定位失败原因。
      return;
    }

    final latitude = result['latitude'];
    final longitude = result['longitude'];
    // 使用 latitude、longitude 以及可选的地址字段。
  });

  final option = AMapLocationOption(
    onceLocation: true,
    needAddress: true,
  )..fullAccuracyPurposeKey = 'AMapLocationScene';
  await location.setLocationOption(option);
  await location.startLocation();

  // 页面销毁时：
  // await location.stopLocation();
  // await subscription.cancel();
  // await location.destroy();
}

onLocationChanged() 返回 Stream<Map<String, Object>>。常见字段包括：

• callbackTime：插件回调时间；
• locationTime：原生定位时间；
• latitude、longitude、accuracy：坐标和精度；
• locationType：高德定位类型；
• country、province、city、district、street、streetNumber：逆地理信息；
• address、description：格式化地址和位置语义；
• addressSource：地址来源，可能为 amap_native 或 amap_native_regeo；
• errorCode、errorInfo：定位失败时的错误信息。

生命周期和注意事项

• updatePrivacyShow、updatePrivacyAgree 必须在定位接口前调用，并且应与应用自己的隐私同意流程一致。
• setApiKey、setLocationOption、startLocation、stopLocation 和 destroy 都返回 Future<void>，调用方应等待执行完成并处理 PlatformException。
• AMapFlutterLocation 支持多实例；每个实例只接收自己的定位事件。
• 页面销毁时应停止定位、取消监听并调用 destroy()，避免原生定位客户端和 Dart 订阅泄漏。
• AMapLocationOption.androidLocationScene 设置为 AMapAndroidLocationScene.SignIn 时，Android 会使用单次高精度签到场景预设。
• 插件只负责原生 SDK 桥接，不负责业务层的权限申请、隐私弹窗、Key 管理、坐标持久化或地址展示。

许可证

本项目保留高德定位插件原有 LICENSE 文件中的许可和免责声明。使用高德 SDK 时，还应遵守高德开放平台及其 SDK 的服务条款、隐私政策和合规要求。