flutter_amap_position 0.0.1
flutter_amap_position: ^0.0.1 copied to clipboard
Flutter plugin for one-shot and foreground location with the native AMap SDKs on Android, iOS and HarmonyOS NEXT.
flutter_amap_position #
通过高德原生定位 SDK 获取手机位置。Android、iOS 和 HarmonyOS NEXT 共用 Dart API。应用自行申请系统权限。定位插件可以单独运行。需要显示地图、标记和轨迹时,可同时安装地图插件。 flutter_amap_map
首版包含前台单次定位、持续定位和停止。地图蓝点、后台定位、地理围栏及轨迹存储属于首版范围之外。
安装 #
在宿主的 pubspec.yaml 中添加下面的依赖,再运行 flutter pub get。
dependencies:
flutter_amap_position: ^0.0.1
也可以运行 flutter pub add flutter_amap_position。本地开发时,在 flutter_amap_position 项下可改用 path: ../flutter_amap_location,路径以实际检出目录为准。
从 GitHub 标签 v0.0.1 迁移时,把原来的 flutter_amap_location Git 依赖换成上面的 pub.dev 依赖,并更新 Dart 导入及下方的 iOS Podfile 路径。
本仓库的 example 已配置本地依赖。用标准 Flutter 运行 Android、iOS,用支持 HarmonyOS NEXT 的 Flutter SDK 运行鸿蒙。同一份示例 Dart 代码可以在三端启动。
| 平台 | 插件最低系统 | 本轮构建 SDK |
|---|---|---|
| Android | Android 7.0(API 24) | compileSdk 36,JDK 17 |
| iOS | iOS 13 | 示例用 iOS 15,CocoaPods,Xcode 27.2 |
| HarmonyOS NEXT | HarmonyOS 5.1.0(API 18) | Harmony SDK API 22,OHOS Flutter 3.41.9 |
配置 Key 和权限 #
在高德控制台为实际安装的 App 申请各端 Key。Android 绑定 applicationId 与签名 SHA-1,iOS 绑定 Bundle ID,HarmonyOS NEXT 绑定签名后的 AppID。两包共装时给同一平台的两个插件传相同的 Key。
Android 在宿主应用的 AndroidManifest.xml 中声明以下前台权限。宿主在定位前申请运行时权限,Android 12 起应同时请求这两项,由用户选择精确或大致位置。定位插件的 Manifest 提供网络权限和 SDK 所需的 APSService。
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
iOS 在宿主 Info.plist 设置 NSLocationWhenInUseUsageDescription,由宿主调用 requestWhenInUseAuthorization()。在 CocoaPods 的 Runner target 中,保留 Flutter 的安装逻辑,并添加定位 SDK 的来源声明。随后执行 flutter pub get 和 pod install。
use_frameworks! :linkage => :static
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
pod 'AMapLocation', :podspec => '.symlinks/plugins/flutter_amap_position/ios/sdk/AMapLocation.podspec.json'
HarmonyOS NEXT 在宿主 entry 的 module.json5 中声明 ohos.permission.APPROXIMATELY_LOCATION 和 ohos.permission.LOCATION,分别填写权限用途 reason 和 usedScene.when: "inuse",由宿主请求授权。在工程的 build-profile.json5 产品配置里启用 buildOption.strictMode.useNormalizedOHMUrl。可直接参考 示例权限配置 和 构建配置。
初始化 #
宿主向用户展示含高德定位 SDK 内容的隐私政策,把用户的实际选择传给插件。拒绝时返回 privacyNotAgreed。接到同意后,插件按顺序更新高德隐私展示状态、同意状态,再设置 Key。初始化完成表示配置已交给 SDK,实际定位仍取决于权限、手机设置和 SDK 响应。
import 'package:flutter_amap_position/flutter_amap_position.dart';
await AMapLocation.initialize(
apiKey: platformKey,
privacyAgreed: userConsent,
);
单次定位 #
final fix = await AMapLocation.getCurrentPosition(
timeout: const Duration(seconds: 12),
);
final latitude = fix.latitude;
final longitude = fix.longitude;
final accuracyInMeters = fix.horizontalAccuracy;
final timestamp = fix.timestamp; // UTC DateTime
final coordinateSystem = fix.coordinateSystem;
默认超时 15 秒。单次请求结束后会释放原生定位资源。
持续定位与停止 #
final subscription = AMapLocation.watchPosition().listen(
updatePosition,
onError: (Object error) => showLocationError(error),
);
// 按下停止按钮。
await AMapLocation.stop();
// 也可由页面自己的订阅触发清理。
await subscription.cancel();
开始监听时才启用原生定位,回调频率取决于系统和 SDK。同一时间只运行一个单次请求或一个持续会话。重复启动或并发请求会收到 busy,当前会话继续运行。停止和取消订阅都会释放会话,迟到的回调会被丢弃。后台、原生出错或撤回同意会结束会话,回到前台后由宿主重新启动。
错误 #
捕获 AMapLocationException 后根据 code 给用户提示。SDK 有提供原生错误码时,可读 nativeCode 和 nativeDomain。
code |
含义 |
|---|---|
notInitialized / privacyNotAgreed |
还未初始化 / 用户未同意隐私政策 |
permissionDenied / locationServicesDisabled |
应用没有所需的定位权限 / 手机的系统定位开关关闭 |
timeout / sdkFailure |
请求超时 / 原生 SDK 报错或给出无效位置 |
busy / notInForeground |
已有定位请求 / 应用离开前台 |
cancelled |
原生会话因引擎断开或重建被取消 |
invalidArgument / unsupportedPlatform |
Key 或参数不符合要求 / 当前运行平台没有对应的原生实现 |
与地图一起使用 #
先看每条位置的 coordinateSystem。只有 gcj02 可以直接用于地图插件的坐标参数。Android 读取 SDK 的 getCoordType(),HarmonyOS NEXT 读取返回值中的 coordType,缺失时返回 unknown。高德说明中国大陆及港澳台通常返回 GCJ-02,海外返回 WGS84。iOS 的回调对象没有逐次坐标系字段,插件保留原始坐标并标记为 unknown。 高德坐标说明 · Android 定位结果 API · iOS 回调 API
两包共装与标记示例 · 第三方依赖与原生 SDK · 验证记录