flutter_amap_navi

面向 Android、iOS 的 Flutter 高德导航插件，支持驾车、步行、骑行导航，路线规划页面、智能巡航与导航事件流。

本包可独立使用，不依赖 flutter_amap_plus。如果应用同时需要地图，请分别初始化两个插件，并向两边传入相同的平台 Key 与隐私授权状态。

功能清单

以下清单与仓库根目录 example/lib/features/navigation/index.dart 的菜单保持一致。✅ 表示示例已经实现，— 表示尚未实现或该平台不支持。

导航组件（新）

功能 Android iOS
起终点算路 ✅ ✅
无起点算路 ✅ ✅
途经点算路 ✅ ✅
组件直接导航 ✅ ✅
自定义 Activity 的导航组件（Android 原生容器） ✅ —
选取地点（POI）示例 ✅ ✅

路径规划

功能 Android iOS
驾车路径规划 ✅ ✅
步行路径规划 ✅ ✅
骑行路径规划 ✅ ✅
货车导航路径规划 ✅ ✅
独立路径规划 ✅ ✅

多类型导航

功能 Android iOS
内置语音导航 — —
实时导航 — —
模拟导航 — —
货车导航 — —
智能巡航 ✅ ✅
HUD 导航 — —

导航 UI 自定义

功能 Android iOS
自定义车标 — —
自定义路线 UI — —
自定义路线纹理 — —
自定义路口转向提示 — —
正北模式 — —
自定义全览模式 — —
自定义指南针 — —
自定义路况按钮 — —
自定义放大缩小按钮 — —
自定义路口放大图 — —
自定义导航光柱（new） — —
自定义车道信息 — —

导航完全自定义示例

功能 Android iOS
自车改变位置和绘制路线示例 — —
路名、剩余距离、转向图标示例 — —
绘制导航路况条示例 — —
自定义车道信息示例 — —
路口放大图示例 — —
摄像头违章提醒示例 — —
各组件整合导航示例 — —

导航扩展

功能 Android iOS
传入 GPS 数据导航 — —
展示导航路径详情 — —
主辅路切换 — —
科大讯飞语音集成 — —

自定义 Activity 是 Android 原生容器能力；选取地点示例由联合示例中的 flutter_amap_plus 提供地点选择，再将坐标传给本导航包。

安装

dependencies:
  flutter_amap_navi: ^1.0.3

初始化与启动导航

import 'package:flutter_amap_navi/flutter_amap_navi.dart';

await AMapNavi.init(
  config: const NaviSdkConfig(
    apiKey: NaviApiKey(
      iosKey: 'your-ios-key',
      androidKey: 'your-android-key',
    ),
    agreePrivacy: true,
    preloadNaviIcons: true,
  ),
);

await AMapNavi.startNavigation(
  config: NaviConfig(
    naviType: NaviType.driver,
    start: NaviPoint(
      name: '起点',
      position: NaviPosition(latitude: 39.9841, longitude: 116.3075),
    ),
    end: NaviPoint(
      name: '终点',
      position: NaviPosition(latitude: 39.9087, longitude: 116.3975),
    ),
    drivingStrategy: NaviDrivingStrategy.drivingMultipleRoutesDefault,
  ),
);

AMapNavi.init 可重复调用，后一次配置会重新应用。未初始化就启动导航或巡航会抛出 StateError；插件不会替应用静默同意隐私协议。

Android 自定义导航 Activity

自定义容器需继承 AMapFlutterRouteActivity（间接继承高德 AmapRouteActivity）并在宿主 Manifest 注册，然后传入完整类名：

await AMapNavi.startNavigation(
  config: NaviConfig(
    end: destination,
    androidActivityClassName: 'com.example.app.CustomNaviActivity',
  ),
);

插件会在启动前检查类是否存在、是否继承正确且已启用。该参数仅在 Android 生效；为空时继续使用插件默认容器。

与地图包联合使用

两个包刻意不共享 Dart 模型。请在应用边界显式转换：

NaviPosition toNaviPosition(Position value) => NaviPosition(
  latitude: value.latitude,
  longitude: value.longitude,
);

final naviStrategy = NaviDrivingStrategy.fromId(mapStrategy.id);

平台配置

Android

  • minSdk 24，Java/JVM 17。
  • 宿主按业务声明网络、粗略/精确定位、前后台定位和 WAKE_LOCK 权限，并在运行时请求定位权限。
  • 插件 Manifest 自动合并 AMapFlutterRouteActivity 及导航主题。
  • 导航 SDK 作为 Android API 依赖暴露，以便宿主实现自定义 AmapRouteActivity 容器。
  • 本包固定使用 com.amap.api:navi-3dmap-location-search:11.2.100_3dmap11.2.100_loc11.2.100_sea9.8.1。
  • 与 flutter_amap 联合使用时，插件会自动用该导航合包替换纯地图合包，防止重复类。

Release 混淆配置

导航合包内含地图与定位能力。高德 11.2.100 定位库会通过 JNI 和反射访问内部类；若宿主 release 构建启用了 R8/ProGuard，而规则没有覆盖新版的 com.amap.location 与 com.amap.api.col 命名空间，可能出现 debug 正常、release 首次定位、路线规划或启动导航时直接闪退。典型日志包含 libapssdk.so、JNI DETECTED ERROR IN APPLICATION: java_class == null 和 SIGABRT。

插件源码已通过 consumer-rules.pro 自动向宿主传递规则。仍固定使用 flutter_amap_navi 1.0.2 或更早版本的应用，还应在 android/app/proguard-rules.pro 中确认包含：

-keep class com.amap.api.col.** { *; }
-keep class com.amap.location.** { *; }
-dontwarn com.amap.**
-dontwarn com.autonavi.**
-dontwarn net.jafama.**

前两条防止 JNI/反射目标被改名或移除；后三条只忽略高德合包中未提供的可选能力告警，避免 R8 因 GnssSoftLocator、FastMath 等非当前合包必需类终止构建。

修改后必须用 release 包在真机上验证定位、路线规划与导航启动；仅验证 debug 包不能覆盖这类问题。

iOS

  • 最低 iOS 12.0。
  • 在 Info.plist 中声明定位用途；巡航或导航需要后台定位时，再启用 Location Background Mode 并提供 Always 权限说明。
  • Pod 固定使用 AMapNavi 11.2.100。
  • 与 flutter_amap 联合使用时，在宿主 Podfile 的 flutter_ios_podfile_setup 之前设置 ENV['FLUTTER_AMAP_USE_NAVI_SDK'] = 'true'，避免同时引入 AMap3DMap。

可运行的最小工程见 example。从原单包 API 迁移请阅读 2.0 迁移指南。

License

见 LICENSE。

Libraries

flutter_amap_navi