接入指南
    定位Flutter插件
    地图Flutter插件
接入指南
地图Flutter插件
入门指南
概述

概述

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

HarmonyOS 通过鸿蒙专项版（1.0.1-ohos.N）提供，需使用 flutter-ohos 编译，详见 HarmonyOS 专项指南。

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

核心能力

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

部分能力在 HarmonyOS 端暂未实现或有降级，详见各功能介绍页末尾的「鸿蒙（HarmonyOS）差异」小节。

平台支持

平台 状态 底层 SDK
Android ✅ 已支持 腾讯地图 Android SDK 5.9.0+
iOS ✅ 已支持 腾讯地图 iOS SDK 5.7.7+
HarmonyOS ✅ 已支持（鸿蒙专项版） 腾讯地图鸿蒙 SDK（@tencentmap/map）2.6.0

注意：HarmonyOS 以专项版（pre-release）1.0.1-ohos.1 发布，必须使用 flutter-ohos fork SDK 编译，且需在 pubspec.yaml 中精确锁定版本。Android/iOS 请继续使用 ^1.0.0。安装与配置见 HarmonyOS 专项指南。

SDK 版本矩阵

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

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

低版本作为 compileOnly / podspec 依赖基准，保证插件在低版本 SDK 上可编译运行；高版本新增的 API 通过 Compat 反射层按需启用，无需升级插件即可享受新特性。HarmonyOS 不使用双版本策略，专项版锁定 @tencentmap/map 2.6.0。

文档结构

最小代码示例

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

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 → 设置初始相机位置 → 地图创建回调 → 地图加载完成。

HarmonyOS 的鉴权入口不同：须在创建地图前调用 TencentMapInitializer.setApiKey(...) 传入 ohosKey，TencentMap 上无需再传 apiKey。详见 HarmonyOS 专项指南。

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

本页内容