flutter_tencent_map 1.0.1

A Flutter plugin for Tencent Maps on Android and iOS, providing map display, overlays, camera control, location, and more with declarative API design.

flutter_tencent_map

腾讯地图 Flutter 插件，基于腾讯位置服务地图 SDK 封装，支持 Android 与 iOS，提供地图显示、覆盖物、定位图层、相机控制、地图事件等完整能力，采用声明式 API 设计。

官方开发指南：lbs.qq.com/flutter

平台支持

平台	状态	底层 SDK
Android	✅ 已实装	Tencent-MapSDK（编译基准 5.9.0，兼容 6.10.0+）
iOS	✅ 已实装	QMapKit（编译基准 5.7.7，兼容 6.9.0+）

环境要求

平台	要求
Flutter	>= 3.16.0
Dart	>= 3.2.0
Android	minSdkVersion 21，compileSdkVersion 31
iOS	Deployment Target 13.0+

功能概览

功能模块	核心类	说明
地图显示与配置	TencentMap	地图类型（普通/卫星/夜间等）、路况图层、缩放范围、指南针、比例尺、手势开关
相机控制	TencentMapController	moveCamera / animateCamera，支持中心点、缩放、倾斜、旋转、可视范围（LatLngBounds）适配
地图事件	TencentMap	点击、长按、POI 点击、相机移动、地图加载完成等回调
覆盖物	Marker / Polyline / Polygon / Circle / Arc	声明式 Set Diff 更新，对象不可变，通过 copyWith 更新
Marker 能力	Marker / BitmapDescriptor	自定义图标、锚点、旋转、透明度、拖拽、InfoWindow、碰撞控制
定位图层	MyLocationStyleOptions	自定义蓝点样式，通过 Controller 更新定位
个性化地图样式	CustomStyleOptions	接入腾讯地图样式配置平台
地图查询与截图	TencentMapController	坐标与屏幕坐标互转、可视区域获取、地图截图
多地图实例	—	同一页面可同时承载多个地图

SDK 版本兼容

本插件采用"低版本编译基准 + 高版本反射兼容"设计，同时支持腾讯地图 SDK 的多个版本，开发者无需关心底层 SDK 版本差异，插件内部自动处理版本兼容。

平台	编译基准版本	兼容高版本
Android	5.9.0	6.x
iOS	5.7.7	6.x

安装

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter_tencent_map: ^1.0.0

然后执行：

flutter pub get

获取 API Key

1. 前往腾讯位置服务控制台注册账号并创建应用
2. 分别创建 Android 平台和 iOS 平台的 Key
3. 在 Key 设置中配置 Android 包名和 iOS Bundle ID

平台配置

Android

在 android/app/src/main/AndroidManifest.xml 的 <application> 标签内添加 Key，并声明网络权限：

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

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

iOS

1. 在腾讯位置服务控制台申请 iOS 平台的 ApiKey。
2. 插件的 podspec 已配置腾讯地图 iOS SDK 依赖，执行 cd ios && pod install。
3. ApiKey 推荐在 Dart 层通过 TencentMap 的 apiKey 参数传入（见下方示例）。

Apple Silicon 模拟器构建配置

腾讯地图 SDK 的 podspec 通过 user_target_xcconfig 设置了 EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64。这条设置会被 Flutter 检测到（Pods 工程中含 EXCLUDED_ARCHS.*arm64），进而影响 Flutter 在 Apple Silicon Mac 上为模拟器选择构建架构的策略。

在部分场景（首次 pod install、DerivedData 被清理后等）下，这条设置可能与 Flutter/Xcode 的架构选择产生冲突，导致 Pods_Runner.framework 无法生成，链接报错 Framework 'Pods_Runner' not found；即使不报错，也可能导致应用被迫通过 Rosetta 以 x86_64 运行，而非 Apple Silicon 原生的 arm64。

SDK 6.x 的 QMapKit.framework 为 fat binary（含 arm64 + x86_64 切片），可以在 Apple Silicon 模拟器上原生运行，无需这条排除规则。在 ios/Podfile 的 post_install 中移除该架构限制即可从根本上避免上述问题：

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings.delete('EXCLUDED_ARCHS[sdk=iphonesimulator*]')
    end
  end
end

修改后执行 cd ios && pod install 重新生成 Pods 工程。

快速开始

示例 1：初始化与隐私合规

⚠️ 调用任何地图 API 前，必须先同意隐私政策并完成初始化。

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 const MaterialApp(home: MapPage());
  }
}

示例 2：显示地图并添加 Marker

class MapPage extends StatefulWidget {
  const MapPage({super.key});

  @override
  State<MapPage> createState() => _MapPageState();
}

class _MapPageState extends State<MapPage> {
  TencentMapController? _controller;
  Set<Marker> _markers = {};

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('腾讯地图')),
      body: TencentMap(
        // iOS 推荐在此传入 Key；Android 已在 AndroidManifest 配置
        apiKey: TencentMapApiKey(iosKey: 'YOUR_IOS_KEY'),
        initialCameraPosition: const CameraPosition(
          target: LatLng(39.9087, 116.3975), // 天安门
          zoom: 12,
        ),
        markers: _markers,
        onMapCreated: (controller) => _controller = controller,
        onMapLoaded: () {
          setState(() {
            _markers = {
              const Marker(
                id: 'm1',
                position: LatLng(39.9087, 116.3975),
                infoWindow: InfoWindow(title: '天安门', snippet: '北京市东城区'),
              ),
            };
          });
        },
      ),
    );
  }
}

示例 3：相机控制

// 移动到新位置（带动画）
_controller?.animateCamera(
  CameraUpdate.newCameraPosition(
    const CameraPosition(
      target: LatLng(31.2304, 121.4737), // 上海
      zoom: 14,
      tilt: 30,
      bearing: 45,
    ),
  ),
);

// 适配可视范围
_controller?.animateCamera(
  CameraUpdate.newLatLngBounds(
    LatLngBounds(
      southwest: const LatLng(31.0, 121.0),
      northeast: const LatLng(32.0, 122.0),
    ),
    padding: 50,
  ),
);

示例 4：声明式更新覆盖物

覆盖物通过 Set 声明式管理，插件在 Widget 重建时自动 diff 新旧集合并推送增/删/改。对象不可变，更新需用 copyWith 创建新对象：

setState(() {
  _markers = {
    for (final m in _markers)
      if (m.id == 'm1') m.copyWith(rotation: 90) else m,
  };
});

文档

• 官方开发指南：Flutter 地图插件
• API 参考：API Reference
• 示例工程：见插件 example/（较高版本 SDK）、example_low_sdk/（较低版本 SDK）目录

许可证

详见 LICENSE。