01. TencentLocationRequest

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

1.1 连续定位的 Request

// 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别

// 连续定位
private enableBackgroundLocation: boolean  // 是否开启后台定位
private userActivityScenario?: TencentLocationConstant.UserActivityScenario
private powerConsumptionScenario?: TencentLocationConstant.PowerConsumptionScenario
private interval: number       // 腾讯连续定位回调间隔, 由开发者监听, 单位: 秒
private innerInterval: number  // 系统连续定位回调间隔, 由 sdk 监听, 单位: 秒

1.2 单次定位的 Request

// 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别

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

1.3 默认的 TencentLocationRequest 和修改默认值

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

// 公共
private coordinateType: TencentLocationConstant.CoordinateType  // 坐标类型：GCJ02
private requestLevel: TencentLocationConstant.RequestLevel      // 请求级别：ADMIN_AREA

// 连续定位
private enableBackgroundLocation: boolean  // 是否开启后台定位
private userActivityScenario?: TencentLocationConstant.UserActivityScenario  // undefined
private powerConsumptionScenario?: TencentLocationConstant.PowerConsumptionScenario  // HIGH_POWER_CONSUMPTION
private interval: number       // 腾讯连续定位回调间隔, 由开发者监听, 单位: 秒，默认：1
private innerInterval: number  // 系统连续定位回调间隔, 由 sdk 监听, 单位: 秒，默认：1

// 单次定位
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 小节。
• enableBackgroundLocation: 是否开启后台定位。
• userActivityScenario：详见华为官方文档。
• powerConsumptionScenario：详见华为官方文档。
• interval：SDK 回调位置给开发者的间隔。
• innerInterval：系统回调位置给 SDK 的间隔，可用来降低使用系统位置的频率，以降低隐私风险。
• locatingPriority：详见华为官方文档。
• singleLocationTimeout：单次定位的超时时间。

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          // 方向
  speed?: number              // 速度

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

  geoAddress?: TencentGeoAddress
  poiList?: Array<TencentPOI>

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

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 列表
}