集成 Flutter 插件
本文档介绍如何在你的 Flutter 项目中集成腾讯定位 Flutter 插件，包括添加依赖、配置 ApiKey、声明权限三部分。
集成前请先阅读 兼容性说明 确认你的开发环境与运行环境满足版本要求。
申请 ApiKey
在 腾讯位置服务开放平台 注册账号并创建应用，分别为 Android / iOS / HarmonyOS 平台申请 ApiKey。
申请到的 ApiKey 后续会传递给插件的 TencentLocationSDK.init 方法。
添加插件依赖
在你的 Flutter 项目根目录的 pubspec.yaml 中加入插件依赖：
dependencies:
tencent_location_flutter_plugin: ^0.2.2
执行：
flutter pub get
在 Dart 代码中通过单一 import 即可使用插件全部公开 API：
import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';
Android 配置
声明权限
在 android/app/src/main/AndroidManifest.xml 的 <manifest> 节点下声明定位需要的权限：
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION 属于运行时权限，需要在应用运行时按 Android 规范向用户申请，被授予后插件才能正常工作。
如需后台定位，请额外声明 ACCESS_BACKGROUND_LOCATION 权限并按系统要求处理用户授权。
配置 ApiKey
推荐通过运行时调用 TencentLocationSDK.init 传入 ApiKey（见下文「快速开始」一节示例）。
如果你倾向于在 manifest 中声明，也可以在 <application> 节点下添加：
<meta-data
android:name="TencentMapSDK"
android:value="YOUR_ANDROID_API_KEY" />
两种方式只需任选其一即可生效。运行时 init 设置的 ApiKey 会覆盖 manifest 中的配置。
iOS 配置
声明定位用途字符串
iOS 系统要求应用在请求定位权限前，必须在 ios/Runner/Info.plist 中声明对应的用途字符串。请按你的业务需求选择：
<!-- 仅在使用期间访问位置（绝大多数业务场景使用本项即可） -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>用于获取当前位置以便为您提供基于位置的服务</string>
<!-- 始终允许访问位置（仅在确实需要后台定位时申请） -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>用于在应用进入后台后继续提供基于位置的服务</string>
如果应用需要后台定位，还需要在 Info.plist 的 UIBackgroundModes 中勾选 location：
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
配置 ApiKey
iOS 端的 ApiKey 通过运行时调用 TencentLocationSDK.init 传入即可，无需在 Info.plist 中额外声明。
关于 CocoaPods
首次集成或更新插件版本后，进入 ios/ 目录执行：
pod install --repo-update
让 CocoaPods 拉取插件依赖的腾讯定位 iOS SDK。
HarmonyOS 配置
HarmonyOS 端集成需要使用 OpenHarmony 社区维护的鸿蒙分支 Flutter（不是官方 Flutter）。同一份插件仓库可同时被官方 Flutter（用于 Android / iOS）与鸿蒙分支 Flutter（用于 HarmonyOS）识别，Dart 代码完全共用。
准备鸿蒙分支 Flutter
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git flutter_ohos
cd flutter_ohos
git checkout 3.22.0-ohos
建议为它单独创建一个命令别名（例如 fohos），与官方 Flutter 并存。编 HarmonyOS 时使用 fohos，编 Android / iOS 时使用官方 flutter。
声明权限
在鸿蒙工程的 entry/src/main/module.json5 中声明定位所需的权限：
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.LOCATION" },
{ "name": "ohos.permission.APPROXIMATELY_LOCATION" },
{ "name": "ohos.permission.INTERNET" }
]
}
}
如需后台定位，请额外声明 ohos.permission.LOCATION_IN_BACKGROUND 并在系统申请中说明使用场景。
ohos.permission.LOCATION 与 ohos.permission.APPROXIMATELY_LOCATION 属于用户级授权，需要在应用运行时按 HarmonyOS 规范向用户申请授权。
配置 ApiKey
HarmonyOS 端的 ApiKey 通过运行时调用 TencentLocationSDK.init 传入 harmonyApiKey 参数即可。
关于 ohpm
@tencentmap/location_sdk 与 @ohos/flutter_ohos 由鸿蒙分支 Flutter tool 与 hvigor 自动通过 ohpm 拉取，一般无需手动干预
首次运行前请确认 DevEco Studio 5.0.3.900+ 与 HarmonyOS SDK 5.0.0(12) 已安装完成、ohpm 命令可用。
验证集成
完成上述步骤后，可以在 main.dart 中加入以下代码验证插件是否就绪：
import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';
Future<void> verify() async {
final version = await TencentLocationSDK.getVersion();
print('腾讯定位 SDK 版本：$version');
}
如果能正常打印版本号，说明插件集成成功。
有帮助
没帮助