tencent_location_flutter_plugin 0.1.0

Tencent Location SDK plugin for Flutter, providing cross-platform location, geocoding and geofencing APIs. Currently supports Android and iOS; HarmonyOS coming soon.

tencent_location_flutter_plugin

腾讯定位服务（腾讯位置服务开放平台）的官方 Flutter 插件，对原生 SDK 的连续定位、单次定位、地理围栏与常用坐标 / 距离工具做了统一封装。

平台支持

平台	状态	底层 SDK
🅰️ Android	已实装	TencentLocationSdk-openplatform
🍏 iOS	已实装	TencentLBS
🔶 HarmonyOS	规划中	@tencent/locationsdk

当前版本仅 Android / iOS 可用，HarmonyOS 实装将在后续版本随原生 SDK 一并发布。各公开 API 注释中 🔶 Harmony 行描述的是规划中的目标行为，不代表当前版本已实装。

安装

在你的 pubspec.yaml 中加入依赖：

dependencies:
  tencent_location_flutter_plugin: ^0.1.0

然后执行：

flutter pub get

Android 配置

1. 在 腾讯位置服务开放平台 申请 Android 平台的 ApiKey。
2. 在 android/app/src/main/AndroidManifest.xml 的 <application> 节点中声明 ApiKey，或在运行时通过 TencentLocationSDK.init 传入。
3. 申请定位所需权限（ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION 等），并按 Android 运行时权限规则向用户请求。

iOS 配置

1. 在 腾讯位置服务开放平台 申请 iOS 平台的 ApiKey。
2. 在 ios/Runner/Info.plist 中声明定位用途字符串（NSLocationWhenInUseUsageDescription 等）。
3. ApiKey 可通过 Info.plist 配置或运行时通过 TencentLocationSDK.init 传入。

快速开始

1. 同意隐私政策并初始化 SDK

调用任何其他 API 前，必须先同意隐私政策并完成 SDK 初始化。

import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';

Future<void> setupSdk() async {
  await TencentLocationSDK.setPrivacyPolicyAgreement(true);
  await TencentLocationSDK.init(
    androidApiKey: 'YOUR_ANDROID_API_KEY',
    iosApiKey: 'YOUR_IOS_API_KEY',
  );
}

2. 单次定位

Future<void> requestSingleLocation() async {
  final manager = TencentLocationManager();
  try {
    final request = TencentLocationRequest.create()
      ..setRequestLevel(RequestLevel.geo)
      ..setCoordinateType(CoordinateType.gcj02);
    final location = await manager.startSingleLocation(request);
    print('单次定位：${location.latitude}, ${location.longitude}');
  } on TencentLocationError catch (error) {
    print('定位失败：${error.code} ${error.message}');
  } finally {
    await manager.dispose();
  }
}

3. 连续定位

Future<void> startContinuousLocation() async {
  final manager = TencentLocationManager();

  manager.onLocationChanged.listen((location) {
    print('位置更新：${location.latitude}, ${location.longitude}');
  });
  manager.onLocationError.listen((error) {
    print('定位错误：${error.code} ${error.message}');
  });

  final request = TencentLocationRequest.create()
    ..setRequestLevel(RequestLevel.geo)
    ..setCoordinateType(CoordinateType.gcj02)
    ..setInterval(const Duration(seconds: 3));
  await manager.startContinuousLocation(request);

  // 不再需要时停止并释放：
  // await manager.stopContinuousLocation();
  // await manager.dispose();
}

4. 地理围栏

Future<void> watchGeofence() async {
  final manager = TencentGeofenceManager();

  manager.onEvent.listen((event) {
    print('围栏事件：${event.transition} -> ${event.geofenceId}');
  });

  await manager.addGeofence(
    TencentGeofence.circle(
      id: 'office',
      center: const TencentLocationCoordinate(
        latitude: 39.984120,
        longitude: 116.307484,
      ),
      radius: 200,
    ),
  );
  await manager.startMonitoring();

  // 不再需要时清理：
  // await manager.stopMonitoring();
  // await manager.dispose();
}

功能概览

• 全局配置（TencentLocationSDK）：隐私合规、ApiKey 初始化、版本信息、日志开关、iOS 权限申请等。
• 连续 / 单次定位（TencentLocationManager）：可配置坐标系、回调间隔、逆地址、设备状态、设备朝向；支持前台服务与后台任务。
• 地理围栏（TencentGeofenceManager）：圆形 / 多边形围栏的增删改查、进出停留事件回调、监听暂停 / 恢复。
• 工具方法（TencentLocationUtils）：坐标系互转、两点间距离计算、判断点是否在围栏内等。
• 多实例：同一应用内可创建多个管理器实例，事件流互相隔离。

完整 API 文档见 pub.dev 的 API reference。

许可

BSD 3-Clause License。