兼容性说明

本文档介绍 flutter_tencent_map 插件对 Flutter 版本、Android/iOS/HarmonyOS 系统版本、以及腾讯地图 SDK 版本的兼容性要求。

---

Flutter 与 Dart 版本

项目	最低版本	推荐版本
Flutter	2.0.0	3.16.0+
Dart SDK	2.14.0	3.2.0+

注意：插件使用了 Set<T> diff、Factory<T> 等需要 Dart 2.14+ 的语言特性。

HarmonyOS 不适用上表：鸿蒙专项版必须使用 flutter-ohos fork（Flutter 3.22.1-ohos-1.0.9 / Dart 3.4.0），见下文「HarmonyOS 版本要求」。

---

Android 版本要求

项目	值
minSdkVersion	21（Android 5.0）
compileSdkVersion	31（Android 12）
targetCompatibility	Java 1.8
原生语言	Java（不使用 Kotlin）

---

iOS 版本要求

项目	值
Deployment Target	13.0
原生语言	Objective-C

---

HarmonyOS 版本要求

仅适用于鸿蒙专项版 1.0.1-ohos.N，详见 HarmonyOS 专项指南。

项目	值
Flutter SDK	flutter-ohos fork 3.22.1-ohos-1.0.9（主线 Flutter 无法编译）
Dart SDK	3.4.0（随 flutter-ohos 自带）
compatibleSdkVersion	5.0.0(12)（OpenHarmony 5.0.0.71+ / API 12+）
runtimeOS	HarmonyOS
DevEco Studio	最新稳定版，其内置 OpenHarmony SDK 需 ≥ API 18
构建工具链	hvigor，JDK 17
原生语言	ArkTS
签名	签名三件套（.cer / .p7b / .p12），必须配置

---

腾讯地图 SDK 版本

插件采用双版本兼容策略：

平台	低版本（编译基准）	高版本（反射目标）
Android	5.9.0	6.10.0+
iOS	5.7.7	6.9.0+
HarmonyOS	2.6.0（锁定）	-

兼容策略说明

• 低版本：作为 compileOnly（Android）/ podspec（iOS）的依赖基准。插件编译时只引用低版本 SDK 中已有的 API，保证插件能在低版本 SDK 环境下正常编译和运行。
• 高版本：SDK 升级到高版本后，新增的 API 通过 Compat 反射层（respondsToSelector / 反射调用）按需启用，无需升级插件即可享受新特性。
• HarmonyOS：不使用双版本策略，鸿蒙专项版锁定 @tencentmap/map 2.6.0 与 @tencentmap/base 2.3.3，由插件通过 ohpm 依赖自动引入。

---

环境检查清单

在开始集成前，请确认以下环境已就绪：

• Flutter SDK 已安装（flutter doctor 无错误）
• Android Studio / Xcode 已安装
• 已在腾讯位置服务控制台申请 API Key
• Android 包名 / iOS Bundle ID 已在控制台正确配置
• （HarmonyOS）已安装 flutter-ohos fork 与 DevEco Studio，并配置了签名三件套
• （HarmonyOS）已申请 HarmonyOS 平台 Key，Bundle Name 与签名指纹已在控制台配置