集成 Flutter 插件

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

---

添加依赖

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

dependencies:
  flutter_tencent_map: ^1.0.0

然后执行：

flutter pub get

---

获取 API Key

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

注意：Android 和 iOS 需要分别创建 Key，或使用同一个 Key 但分别配置平台信息。

---

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'（高版本）。

---

两种 Key 配置方式

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

方式一：平台原生配置

• Android：AndroidManifest.xml 中的 <meta-data android:name="TencentMapSDK" android:value="YOUR_KEY"/>
• iOS：iOS 端没有独立的原生 Key 配置入口，推荐使用方式二（Dart 层 Widget 参数传入）

此方式下，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 端已支持。

---

验证集成

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

flutter run

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