鸿蒙定位 SDK
    开发指南
  • 下载
    • 合规说明
    鸿蒙定位 SDK
    开发指南
    核心类

    01. TencentLocationRequest

    无论是请求连续定位还是单次定位都需要创建 TencentLocaitonRequest 实例，并传给相关 API 来请求定位，每种定位都只有一部分属性可用：

    1.1 连续定位的 Request

    // 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别
private enableSensorForDirection: boolean  // [1.0.7 新增] 开启后, 通过 TencentLocation 中的 directionFromSensor 获取方向信息
private firstLocationCachePolicy: number   // [1.0.8 连续和单次定位都生效, 1.0.7 仅连续定位有效] -1: 不使用缓存; 0: 使用缓存, 但忽略缓存点的时间, 即多老的缓存都要; >0: 使用缓存, 但在此时间之内的缓存才要, 单位: 秒

// 连续定位
private enableBackgroundLocation: boolean  // 是否开启后台定位
private userActivityScenario?: TencentLocationConstant.UserActivityScenario
private powerConsumptionScenario?: TencentLocationConstant.PowerConsumptionScenario
private interval: number       // 腾讯连续定位回调间隔, 由开发者监听, 单位: 秒
private innerInterval: number  // 系统连续定位回调间隔, 由 sdk 监听, 单位: 秒
private reverseGeocodeRequestInterval: number  // 连续定位时, 逆地址解析请求的间隔, 单位: 秒, level != GEO 时有效

    1.2 单次定位的 Request

    // 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别
private enableSensorForDirection: boolean  // [1.0.7 新增] 开启后, 通过 TencentLocation 中的 directionFromSensor 获取方向信息

// 单次定位
private locatingPriority: TencentLocationConstant.LocatingPriority
private singleLocationTimeout: number  // 单次定位超时时间, 单位: 秒

    1.3 默认的 TencentLocationRequest 和修改默认值

    TencentLocationRequest 实例只能通过类方法 default 来获取，下面是所有的属性和默认值：

    // 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型：GCJ02
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别：ADMIN_AREA
private enableSensorForDirection: boolean  // [1.0.7 新增] 开启后, 通过 TencentLocation 中的 directionFromSensor 获取方向信息: false
private firstLocationCachePolicy: number   // [1.0.8 连续和单次定位都生效, 1.0.7 仅连续定位有效] -1: 不使用缓存; 0: 使用缓存, 但忽略缓存点的时间, 即多老的缓存都要; >0: 使用缓存, 但在此时间之内的缓存才要, 单位: 秒

// 连续定位
private enableBackgroundLocation: boolean  // 是否开启后台定位: false
private userActivityScenario?: TencentLocationConstant.UserActivityScenario  // undefined
private powerConsumptionScenario?: TencentLocationConstant.PowerConsumptionScenario  // HIGH_POWER_CONSUMPTION
private interval: number       // 腾讯连续定位回调间隔, 由开发者监听, 单位: 秒，默认：1
private innerInterval: number  // 系统连续定位回调间隔, 由 sdk 监听, 单位: 秒，默认：1
private reverseGeocodeRequestInterval: number  // 连续定位时, 逆地址解析请求的间隔, level != GEO 时有效, 单位: 秒, 默认: 10

// 单次定位
private locatingPriority: TencentLocationConstant.LocatingPriority  // PRIORITY_LOCATING_SPEED
private singleLocationTimeout: number  // 单次定位超时时间, 单位: 秒，默认：5

    修改默认值只需要使用链式调用对应的 setter 方法即可:

    const request = TencentLocationRequest
  .default()
  .setCoordinateType(TencentLocationConstant.CoordinateType.WGS84)
  .setRequestLevel(TencentLocationConstant.RequestLevel.POI)

    下面是 TencentLocationRequest 配置的详细说明

    • coordinateType：支持 2 种坐标系：GCJ02 和 WGS84。
    • requestLevel：支持 4 种级别：GEO，NAME，ADMIN_AREA，POI。详见第 3 小节。
    • enableSensorForDirection: [1.0.7 新增] 开启后, 通过 TencentLocation 中的 directionFromSensor 获取方向信息
    • enableBackgroundLocation: 是否开启后台定位。
    • userActivityScenario：详见华为官方文档。
    • powerConsumptionScenario：详见华为官方文档。
    • interval：SDK 回调位置给开发者的间隔。
    • innerInterval：系统回调位置给 SDK 的间隔，可用来降低使用系统位置的频率，以降低隐私风险。
    • locatingPriority：详见华为官方文档。
    • singleLocationTimeout：单次定位的超时时间。
    • reverseGeocodeRequestInterval: 连续定位时, 逆地址解析请求的间隔, level != GEO 时有效
    • firstLocationCachePolicy: [1.0.8 连续和单次定位都生效, 1.0.7 仅连续定位有效] -1: 不使用缓存; 0: 使用缓存, 但忽略缓存点的时间, 即多老的缓存都要; >0: 使用缓存, 但在此时间之内的缓存才要, 单位: 秒

    02. TencentLocationManager

    有了 TencentLocationRequest，传给 TencentLocationManager 的方法就可以使用 SDK 的各种功能了。SDK 支持多实例，通过 SDK 提供的 getInstance 方法获取。

    struct HomePage {
  locationManager_01?: TencentLocationManager = TencentLocationManager.getInstance()
  locationManager_02?: TencentLocationManager = TencentLocationManager.getInstance()  // 不同的实例
  onPageShow(): void {
    // other code 
  }
}

    所有接口

    // 连续定位
startContinuousLocation(request: TencentLocationRequest, success: Callback<TencentLocation>, failure: ErrorCallback<TencentLocationError>): void
stopContinuousLocation(): void

// 获取设备状态
startReceivingDeviceStatus(callback: Callback<TencentLocationConstant.DeviceStatus>): void
stopReceivingDeviceStatus(): void

// 单次定位
startSingleLocation(request: TencentLocationRequest, success: Callback<TencentLocation>, failure: ErrorCallback<TencentLocationError>): void

// 最后定位
getLastLocation(): TencentLocation | undefined

// 后台定位
startBackgroundLocationTask(wantAgentInfo?: wantAgent.WantAgentInfo): void
stopBackgroundLocationTask(): void

// 地理围栏
addGeofence(geofenceRequest: TencentGeofenceRequest): Promise<number>;
removeGeofence(geofenceID?: number): Promise<void>;

    03. TencentLocation

    连续定位和单次定位的结果被封装为 TencentLocation，下面是其所有属性。

    interface TencentLocation {
  latitude?: number           // 纬度
  longitude?: number          // 经度

  altitude?: number           // 海拔
  accuracy?: number           // 精度
  direction?: number          // 方向, GNSS 点才有值, 单位: 度, 范围: [0, 360)
  directionFromSensor?: number  // [1.0.7新增] 方向, request 中开启了 enableSensorForDirection 才有值, 单位: 度, 范围: [0, 360), 0 为正北方向
  speed?: number                // 速度

  source?: TencentLocationConstant.LocationSource  // 定位结果来源

  geoAddress?: TencentGeoAddress
  poiList?: Array<TencentPOI>

  // [1.0.7 新增] 附加信息: 楼层等信息
  additions?: Array<string>
  additionSize?: number
  additionsMap?: Map<string, string>

  timeStamp?: number          // 时间戳, 单位: 毫秒

  // [1.0.8 新增]获取缓存来源信息. 
  // - TencentLocationConstant.CacheSource.NONE: 定位结果不来自缓存
  // - TencentLocationConstant.CacheSource.SDK: 定位结果来自 sdk 缓存
  // - TencentLocationConstant.CacheSource.SYSTEM: 定位结果来自系统缓存
  getCacheSource(): string
}

interface TencentGeoAddress {
  name?: string      // 名称
  address?: string   // 地址

  nation?: string    // 国家
  province?: string  // 省
  city?: string      // 市
  district?: string  // 区
  town?: string      // 镇
  village?: string   // 乡
  street?: string    // 街道
  streetNo?: string  // 街道号
}

interface TencentPOI {
  latitude?: number   // 纬度
  longitude?: number  // 经度

  uid?: string        // 此 POI 的 uid
  name?: string       // 名称
  address?: string    // 地址
  catalog?: string    // 此 POI 的类别
  distance?: number   // 此 POI 距离当前位置的距离, 单位: 米
}

    在 TencentLocationRequest 中设置不同 RequestLevel，获取的 TencentLocation 有所不同。

    enum RequestLevel {
  GEO         = 0,  // 精度, 纬度, 海拔, 精度
  NAME        = 1,  // 精度, 纬度, 海拔, 精度, 名称, 地址
  ADMIN_AREA   = 3,  // 精度, 纬度, 海拔, 精度, 名称, 地址, 国家, 省, 市, 区, 镇, 村, 街道, 门号
  POI         = 4   // 精度, 纬度, 海拔, 精度,          , 国家, 省, 市, 区, 镇, 村, 街道, 门号, POI 列表. 名称和地址取第一个 POI 中的名称和地址
}
    本页内容