Skip to main content

flutter_tencent_map 1.0.1-ohos.1 copy "flutter_tencent_map: ^1.0.1-ohos.1" to clipboard
flutter_tencent_map: ^1.0.1-ohos.1 copied to clipboard

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

flutter_tencent_map #

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

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

⚠️ BREAKING(鸿蒙专项版 1.0.1-ohos.1):HarmonyOS 平台支持必须使用 flutter-ohos fork SDK 编译 (Flutter 3.22.1-ohos-1.0.9 / Dart 3.4.0 及以上)。主线 Google Flutter SDK 编译 1.0.1-ohos.1 会失败 (lib/ 内含 TargetPlatform.ohos / OhosView 等 flutter-ohos 独有符号)。 Android/iOS 主线用户请继续使用 ^1.0.0,pub 会自动回避鸿蒙 pre-release 版本。

平台支持 #

平台 状态 底层 SDK
Android ✅ 已实装 Tencent-MapSDK(编译基准 5.9.0,兼容 6.10.0+)
iOS ✅ 已实装 QMapKit(编译基准 5.7.7,兼容 6.9.0+)
HarmonyOS ✅ 已实装 @tencentmap/map 2.6.0(仅 1.0.1-ohos.N 专项版)

环境要求 #

平台 要求
Flutter >= 3.16.0;HarmonyOS 需 flutter-ohos fork(3.22.1-ohos-1.0.9)
Dart >= 3.2.0;HarmonyOS 需 3.4.0
Android minSdkVersion 21,compileSdkVersion 31
iOS Deployment Target 13.0+
HarmonyOS compatibleSdkVersion 5.0.0(12) / API 12+,需 DevEco Studio + 签名三件套(.cer/.p7b/.p12)

关于 flutter-ohos:它是 OpenHarmony 社区 fork (flutter_flutter)的命令封装,不是 fork 自带的命令名。 fork 安装后其 bin/ 目录里的命令是 flutter(与主线同名),推荐配置别名避免与主线冲突:

# 推荐:配置别名(不影响主线 flutter)
alias flutter-ohos="$HOME/path/to/flutter_flutter/bin/flutter"

本文档中所有 flutter-ohos 命令,请按你的实际配置替换(或直接调用 fork 的 flutter)。 安装 flutter_flutter fork:git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git, 切换到对应分支(本插件适配 3.22.1-ohos-1.0.9)。

功能概览 #

功能模块 核心类 说明
地图显示与配置 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
HarmonyOS @tencentmap/map 2.6.0(配套 @tencentmap/base 2.3.3) 鸿蒙专项版锁定该版本

安装 #

在 pubspec.yaml 中添加依赖,按目标平台选择:

Android / iOS(主线版本) #

dependencies:
  flutter_tencent_map: ^1.0.0   # pub 自动回避鸿蒙 pre-release 版本

然后执行:

flutter pub get

HarmonyOS(鸿蒙专项版 1.0.1-ohos.1) #

dependencies:
  flutter_tencent_map: 1.0.1-ohos.1   # ⚠️ 必须精确锁定,不能写 ^1.0.1-ohos.1

⚠️ 为什么必须精确锁定:^1.0.1-ohos.1 允许解析到 >=1.0.1-ohos.1 <2.0.0 范围内任意版本,未来主线 stable(如 1.0.2)会静默覆盖鸿蒙版。 鸿蒙开发者必须写精确版本号。

然后执行:

flutter-ohos pub get          # 鸿蒙需使用 flutter_flutter fork SDK
                              # (flutter-ohos 为社区推荐别名,请按你的实际配置替换,
                              #   见上方"环境要求 → 关于 flutter-ohos")

鸿蒙工程要求:compatibleSdkVersion 5.0.0(12) / API 12+,并配置签名三件套 (.cer / .p7b / .p12)。详见 example/ohos/ 工程。

获取 API Key #

  1. 前往腾讯位置服务控制台注册账号并创建应用
  2. 分别创建 Android 平台和 iOS 平台的 Key
  3. 在 Key 设置中配置 Android 包名和 iOS Bundle ID
  4. HarmonyOS 专项版还需创建 HarmonyOS 平台的 Key(绑定应用的 Bundle Name 与签名指纹)。ohosSecretKey 是可选的签名增强:不填走普通鉴权;若填写则走签名鉴权,必须是真实值,填占位符会导致鉴权失败

平台配置 #

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 工程。

HarmonyOS #

HarmonyOS 的平台配置与 Android/iOS 完全不同,需要完成以下步骤:

1. 声明权限

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

"requestPermissions": [
  { "name": "ohos.permission.APPROXIMATELY_LOCATION" },
  { "name": "ohos.permission.LOCATION" },
  { "name": "ohos.permission.INTERNET" },
  // 如需后台定位(导航):
  // { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" },
  // { "name": "ohos.permission.LOCATION_IN_BACKGROUND" }
]

2. 配置签名

鸿蒙工程必须配置签名三件套(.cer / .p7b / .p12),在 ohos/build-profile.json5 的 signingConfig 中配置。参考 example/ohos/ 工程。

3. 编译要求

  • compatibleSdkVersion:5.0.0(12)(OpenHarmony 5.0.0.71+ / API 12+)
  • runtimeOS:HarmonyOS
  • 使用 flutter-ohos fork SDK 编译(flutter-ohos build hap --debug)

4. 初始化与鉴权

隐私合规(Privacy.setUserAgreePrivacy)与鉴权(AuthService.setKey/setSecretKey)在 Dart 层通过 TencentMapInitializer.setAgreePrivacy + setApiKey 完成(见示例 1), 插件原生层自动处理 MapSDK.Prepare(ctx) 与 EntryAbility 生命周期,开发者无需在鸿蒙原生侧写代码。

5. 鸿蒙端功能差异(与 Android/iOS 对比)

以下能力在鸿蒙端暂未实现或有降级(接口保持一致,设置后被忽略或降级,不会报错):

模块 差异
Marker draggable 拖拽及 onDragStart/onDrag/onDragEnd 回调不生效;fixedToScreen / fixedScreenPoint 不生效
Polyline lineCap 不生效;textureLineType: footprint(足迹线)降级为实线
Polygon strokeTexture / strokeTextureSpacing(描边纹理)不生效
Arc showArrow 不生效
个性化样式 customStyleOptions 的 styleId 须 ≥ 1;enabled: false / null 无法恢复默认样式
地图查询 TencentMapInitializer.clearCache 恒返回 false
相机 moveCamera / animateCamera 的 duration 参数被忽略
多地图实例 鉴权为全局单例,同一应用内所有地图共用同一个 ohosKey,不支持多 Key

快速开始 #

示例 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);

  // API Key 设置
  // ⚠️ HarmonyOS 必需:AuthService 全局单例鉴权,必须在任何地图 Widget 创建前调用。
  //    Android/iOS 为 no-op(Key 在 AndroidManifest / Info.plist / TencentMap(apiKey:) 传入)。
  //    ohosSecretKey 为可选项,不填走普通鉴权;若填写必须是真实 SecretKey,不要填占位符。
  await TencentMapInitializer.setApiKey(const TencentMapApiKey(
    androidKey: 'YOUR_ANDROID_KEY',
    iosKey: 'YOUR_IOS_KEY',
    ohosKey: 'YOUR_OHOS_KEY',
  ));

  await TencentMapInitializer.start();

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(home: MapPage());
  }
}

⚠️ HarmonyOS 特殊要求:TencentMapInitializer.setApiKey 是鸿蒙端真正的鉴权入口 (AuthService 全局单例),必须在任何地图 Widget 创建前调用,否则地图无法显示。 Android/iOS 端此方法为 no-op,因此三端 main.dart 代码可完全统一,无需平台分支。

示例 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 配置;
        // HarmonyOS 已通过 TencentMapInitializer.setApiKey 设置(见示例 1),此处无需重复
        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。

2
likes
0
points
241
downloads

Publisher

unverified uploader

Weekly Downloads

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

Homepage

License

unknown (license)

Dependencies

flutter, flutter_plugin_android_lifecycle, meta, plugin_platform_interface, stream_transform

More

Packages that depend on flutter_tencent_map

Packages that implement flutter_tencent_map