概述

flutter_tencent_map 是腾讯位置服务提供的官方 Flutter 地图插件，一份 Dart 代码即可在 Android 和 iOS 双端渲染腾讯地图，并提供丰富的覆盖物、相机控制、事件交互等能力。

本文档介绍插件的核心能力、平台支持情况、文档结构，以及一个最小可运行的代码示例。

---

核心能力

能力	说明
地图渲染	支持普通地图、卫星地图切换，可配置指南针、比例尺、Logo 位置等 UI 控件
相机控制	提供中心点、缩放级别、旋转角、倾斜角的精确控制，支持 8 种 CameraUpdate 工厂方法
点标记 Marker	支持自定义图标、旋转、透明度、拖拽、InfoWindow、碰撞控制、固定屏幕位置
折线 Polyline	支持实线、虚线、纹理线、渐变色、分段着色等多种样式
多边形 Polygon	支持填充、描边、虚线、纹理描边、带洞多边形
圆形 Circle	支持实线/虚线边框、填充色、描边色
弧线 Arc	支持两点间弧线绘制
定位图层	支持定位蓝点显示、精度圆、自定义图标，位置数据由业务层推送
个性化地图样式	支持通过 styleId 切换自定义地图样式
手势冲突处理	提供手势竞技场策略配置，解决地图嵌入可滚动容器的手势竞争
多地图实例	支持同一页面展示多个独立地图实例，可使用不同 API Key

---

平台支持

平台	状态	底层 SDK
Android	✅ 已支持	腾讯地图 Android SDK 5.9.0+
iOS	✅ 已支持	腾讯地图 iOS SDK 5.7.7+
HarmonyOS	规划中	待原生 SDK 接入后提供支持

注意：当前版本仅 Android/iOS 可用。在 HarmonyOS 平台调用插件 API 会抛出 MissingPluginException。

---

SDK 版本矩阵

插件采用"低版本编译基准 + 高版本反射兼容"的双版本策略：

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

低版本作为 compileOnly / podspec 依赖基准，保证插件在低版本 SDK 上可编译运行；高版本新增的 API 通过 Compat 反射层按需启用，无需升级插件即可享受新特性。

---

文档结构

• 入门指南
  • 概述（当前页）
  • 兼容性说明
  • 集成 Flutter 插件
  • 隐私合规接口
  • 快速开始
• 功能介绍
  • 地图显示与配置
  • 相机控制
  • 地图事件
  • 地图查询与截图
  • 点标记 Marker
  • 折线 Polyline
  • 多边形 Polygon
  • 圆形 Circle
  • 弧线 Arc
  • 定位图层
  • 个性化地图样式
  • 自定义纹理与 BitmapDescriptor
  • 手势冲突处理
  • Android 渲染模式
  • 多地图实例
• 参考
  • Demo下载

---

最小代码示例

以下代码展示了从创建地图到显示的最小流程：

import 'package:flutter/material.dart';
import 'package:flutter_tencent_map/flutter_tencent_map.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 隐私合规（国内应用必需，详见隐私合规接口文档）
  await TencentMapInitializer.setAgreePrivacy(true);
  await TencentMapInitializer.start();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('腾讯地图')),
        body: TencentMap(
          apiKey: TencentMapApiKey(
            androidKey: 'YOUR_ANDROID_KEY',
            iosKey: 'YOUR_IOS_KEY',
          ),
          initialCameraPosition: const CameraPosition(
            target: LatLng(39.9087, 116.3975), // 天安门
            zoom: 12,
          ),
          onMapCreated: (controller) {
            // 地图创建完成，可在此获取 controller 进行后续操作
          },
          onMapLoaded: () {
            // 地图加载完成
          },
        ),
      ),
    );
  }
}

示例流程：传入 API Key → 设置初始相机位置 → 地图创建回调 → 地图加载完成。

详细的集成步骤请参考集成 Flutter 插件，完整可运行示例请参考快速开始。