接入指南
    定位Flutter插件
    地图Flutter插件
接入指南
地图Flutter插件
入门指南
集成插件

集成 Flutter 插件

本文档介绍如何将 flutter_tencent_map 插件集成到你的 Flutter 项目中，包括添加依赖、获取 API Key、以及 Android/iOS 平台配置。

HarmonyOS 的集成步骤略有不同，下文「HarmonyOS 配置」给出概要，完整说明请参考 HarmonyOS 专项指南。

添加依赖

在项目的 pubspec.yaml 中添加依赖：

dependencies:
  flutter_tencent_map: ^1.0.0

然后执行：

flutter pub get

HarmonyOS：鸿蒙专项版需使用 flutter-ohos，并精确锁定版本 flutter_tencent_map: 1.0.1-ohos.1（不能写 ^），详见 HarmonyOS 专项指南。

获取 API Key

  1. 前往腾讯位置服务控制台
  2. 创建应用，获取 Key
  3. 在 Key 设置中配置 Android 包名和 iOS Bundle ID

注意：Android 和 iOS 需要分别创建 Key，或使用同一个 Key 但分别配置平台信息。HarmonyOS 需要单独创建 HarmonyOS 平台的 Key，并绑定应用的 Bundle Name 与签名指纹。

Android 配置

1. 添加 API Key

在 android/app/src/main/AndroidManifest.xml 的 <application> 标签内添加：

<meta-data
    android:name="TencentMapSDK"
    android:value="YOUR_ANDROID_API_KEY" />

2. 添加权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

3. 确认编译配置

在 android/app/build.gradle 中确认：

android {
    compileSdkVersion 31
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 31
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

注意：插件使用 Java 实现（不依赖 Kotlin），如果你的项目启用了 Kotlin，无需额外配置。

iOS 配置

1. 确认 Podfile

插件的 podspec 已自动配置腾讯地图 iOS SDK 依赖，正常执行 pod install 即可：

cd ios && pod install

注意：如果遇到 SDK 版本冲突，请在 Podfile 中锁定版本：pod 'QMapKit', '5.7.7'（低版本）或 pod 'QMapKit', '6.9.0'（高版本）。

HarmonyOS 配置

仅适用于鸿蒙专项版，需使用 flutter-ohos。以下为概要，完整步骤与常见问题见 HarmonyOS 专项指南。

1. 精确锁定插件版本

dependencies:
  flutter_tencent_map: 1.0.1-ohos.1   # 不能写 ^1.0.1-ohos.1

2. 声明网络权限

在 ohos/entry/src/main/module.json5 的 requestPermissions 中添加：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" }
]

如需通过 updateMyLocation 推送设备位置，还需声明并动态申请位置权限，插件本身不申请位置权限。

3. 开启字节码 HAR 支持

在 ohos/build-profile.json5 的 products 下添加：

"buildOption": {
  "strictMode": {
    "useNormalizedOHMUrl": true
  }
}

4. 配置签名

鸿蒙工程必须配置签名三件套，推荐在 DevEco Studio 中通过 File → Project Structure → Signing Configs 自动生成。

5. 在 Dart 中完成鉴权

await TencentMapInitializer.setAgreePrivacy(true);
await TencentMapInitializer.setApiKey(const TencentMapApiKey(
  ohosKey: 'YOUR_OHOS_KEY',
));
await TencentMapInitializer.start();

setApiKey 必须在创建任何地图 Widget 之前调用。

两种 Key 配置方式

插件支持两种 API Key 配置方式，任选其一：

方式一：平台原生配置

  • Android：AndroidManifest.xml 中的 <meta-data android:name="TencentMapSDK" android:value="YOUR_KEY"/>
  • iOS：iOS 端没有独立的原生 Key 配置入口，推荐使用方式二（Dart 层 Widget 参数传入）
  • HarmonyOS：没有平台原生配置入口，Key 只能通过 TencentMapInitializer.setApiKey 设置（见上文「HarmonyOS 配置」）

此方式下，Android SDK 会自动从 AndroidManifest 读取 Key，Dart 层的 TencentMap Widget 无需传 apiKey 参数。

方式二：Dart 层传入

TencentMap(
    apiKey: TencentMapApiKey(
        androidKey: 'YOUR_ANDROID_KEY',
        iosKey: 'YOUR_IOS_KEY',
    ),
    ...
)

此方式适合多地图实例使用不同 Key 的场景。

注意：iOS 当前版本不支持多地图实例使用不同的 Key（同一 App 内所有地图实例共享同一个 Key）。后续版本会支持。Android 端已支持。HarmonyOS 的鉴权为全局单例，同一应用内所有地图实例共用同一个 ohosKey，TencentMap(apiKey:) 中的 ohosKey 不会生效。

验证集成

运行项目，如果地图正常渲染出北京天安门附近的地图瓦片，说明集成成功：

flutter run

HarmonyOS 请使用 flutter-ohos：flutter-ohos run，或 flutter-ohos build hap --debug 构建 HAP 后安装。

如果地图中心显示"鉴权失败，请检查你的 Key"文字，请检查 Key 是否正确、包名/Bundle ID 是否与控制台一致。

本页内容