flutter_tencent_map 1.0.1-ohos.1
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 #
- 前往腾讯位置服务控制台注册账号并创建应用
- 分别创建 Android 平台和 iOS 平台的 Key
- 在 Key 设置中配置 Android 包名和 iOS Bundle ID
- 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 #
- 在腾讯位置服务控制台申请 iOS 平台的 ApiKey。
- 插件的
podspec已配置腾讯地图 iOS SDK 依赖,执行cd ios && pod install。 - 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。