# 位置

# openLocation

iOS需依赖扩展SDK或MapSDK,如果同时依赖了扩展SDK和MapSDK,则优先使用MapSDK提供的openLocation。

Android需依赖MapSDK(暂不支持谷歌方案)

openLocation(Object object)

使用内置地图查看位置。

参数

Object object

属性 类型 默认值 必填 说明
latitude number 纬度,范围为-90~90,负数表示南纬。使用 gcj02 国测局坐标系
longitude number 经度,范围为-180~180,负数表示西经。使用 gcj02 国测局坐标系
scale number 16 缩放比例,范围5~18
name string 位置名
address string 地址的详细说明
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

示例代码

ft.getLocation({
 type: 'gcj02', //返回可以用于wx.openLocation的经纬度
 success (res) {
   const latitude = res.latitude
   const longitude = res.longitude
   ft.openLocation({
     latitude,
     longitude,
     scale: 18
   })
 }
})

注意

  • 接口授权失败(iOS):
  1. 用户拒绝授权,会返回错误信息: unauthorized,用户未授予位置权限
  2. 宿主App禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK被禁止申请位置权限
  • 接口授权失败(Android):
  1. 用户拒绝授权,则地图View定位到默认位置,后续可手动搜索、选择位置

# getLocation

基础库1.3.9开始支持,iOS版本2.1.23

iOS需依赖扩展SDK

Android需依赖扩展SDK或MapSDK,如果同时依赖了扩展SDK和MapSDK,则优先使用MapSDK提供的getLocation。

Android使用扩展SDK如果碰到定位慢、定位成功率不满足需求的情况,可以集成MapSDK,使用第三方定位SDK(高德、百度、腾讯、谷歌)提供的定位能力,否则建议使用扩展SDK提供的getLocation。

getLocation(Object object)

获取当前的地理位置等信息。当用户离开小程序后,此接口无法调用。

参数

Object object

属性 类型 默认值 必填 说明
type string wgs84 wgs84 返回 gps 坐标,gcj02 返回可用于 wx.openLocation 的坐标
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

注意

  • 接口授权失败(iOS):
  1. 用户拒绝授权,会返回错误信息: unauthorized,用户未授予位置权限
  2. 宿主App禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK被禁止申请位置权限
  • 接口授权失败(Android):
  1. 用户拒绝授权,会返回错误信息:unauthorized 用户未授予获取位置信息权限
  2. 宿主App禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized SDK被禁止了主动发起权限申请

# choosePoi

iOS需依赖扩展SDK

Android需依赖MapSDK(暂不支持谷歌方案)

choosePoi(Object object)

打开POI列表选择位置,支持模糊定位(精确到市)和精确定位混选。

参数

Object object

属性 类型 默认值 必填 说明
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性 类型 说明
type number 选择不显示位置时,值为0,选择城市时,值为 1,选择精确位置时,值为 2
city string 城市名称
name string 位置名称
address string 详细地址
latitude string 纬度,浮点数,范围为-90~90,负数表示南纬。使用 gcj02 国测局坐标系
longitude string 经度,浮点数,范围为-180~180,负数表示西经。使用 gcj02 国测局坐标系

注意

  • 接口授权失败(iOS):
  1. 用户拒绝授权,会返回错误信息: unauthorized,用户未授予位置权限
  2. 宿主App禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK被禁止申请位置权限
  • 接口授权失败(Android):
  1. 用户拒绝授权,则地图View定位到默认位置,后续可手动搜索、选择位置

# chooseLocation

基础库1.3.9开始支持,iOS版本2.1.23

iOS需依赖扩展SDK或MapSDK,如果同时依赖了扩展SDK和MapSDK,则优先使用MapSDK提供的openLocation。

Android需依赖MapSDK(暂不支持谷歌方案)

chooseLocation(Object object)

打开地图选择位置。

参数

Object object

属性 类型 默认值 必填 说明
latitude number 目标地纬度
longitude number 目标地经度
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

object.success 回调函数

参数

Object res

属性 类型 说明
name string 位置名称
address string 详细地址
latitude string 纬度,浮点数,范围为-90~90,负数表示南纬。使用 gcj02 国测局坐标系
longitude string 经度,浮点数,范围为-180~180,负数表示西经。使用 gcj02 国测局坐标系

注意

  • 接口授权失败(iOS):
  1. 用户拒绝授权,会返回错误信息: unauthorized,用户未授予位置权限
  2. 宿主App禁止小程序主动申请权限,会返回错误信息:unauthorized disableauthorized,SDK被禁止申请位置权限
  • 接口授权失败(Android):
  1. 用户拒绝授权,则地图View定位到默认位置,后续可手动搜索、选择位置

# stopLocationUpdate

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

stopLocationUpdate(Object object)

关闭监听实时位置变化,前后台都停止消息接收。

参数

Object object

属性 类型 默认值 必填 说明
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

# startLocationUpdateBackground

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

startLocationUpdateBackground(Object object)

开启小程序进入前后台时均接收位置消息。

参数

Object object

属性 类型 默认值 必填 说明
type string gcj02 wgs84 返回 gps 坐标,gcj02 返回可用于 wx.openLocation 的坐标
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

# startLocationUpdate

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

startLocationUpdate(Object object)

开启小程序进入前台时接收位置消息。

参数

Object object

属性 类型 默认值 必填 说明
type string gcj02 wgs84 返回 gps 坐标,gcj02 返回可用于 wx.openLocation 的坐标
success function 接口调用成功的回调函数
fail function 接口调用失败的回调函数
complete function 接口调用结束的回调函数(调用成功、失败都会执行)

# onLocationChange

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

onLocationChange(Object object)

监听实时地理位置变化事件。

参数

Object object

属性 类型 默认值 必填 说明
latitude number 纬度,范围为 -90~90,负数表示南纬。使用 gcj02 国测局坐标系
longitude number 经度,范围为 -180~180,负数表示西经。使用 gcj02 国测局坐标系
speed number 速度,单位 m/s
accuracy number 位置的精确度
altitude number 高度,单位 m
verticalAccuracy number 垂直精度,单位 m(Android 无法获取,返回 0)
horizontalAccuracy number 水平精度,单位 m

# offLocationChange

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

offLocationChange(Object object)

移除实时地理位置变化事件的监听函数。

参数

Object object

属性 类型 默认值 必填 说明
listener function onLocationChange 传入的监听函数。不传此参数则移除所有监听函数。

# onLocationChangeError

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

onLocationChangeError(Object object)

监听持续定位接口返回失败时触发。

参数

Object object

属性 类型 默认值 必填 说明
errCode number 错误码

# offLocationChangeError

基础库3.0.18开始支持,iOS版本2.39.0-alpha20221127v01,Android版本2.39.0-alpha20221209v11

offLocationChangeError(Object object)

移除持续定位接口返回失败时触发。的监听函数。

参数

Object object

属性 类型 默认值 必填 说明
listener function

# convertCoordinateFromMap

基础库3.0.19开始支持

该接口是通过注册自定义小程序同步API实现,基础库本身并未直接提供该接口。

convertCoordinateFromMap(Object object)

将sdk返回的经纬度通过该接口做转换。

参数

Object object

属性 类型 默认值 必填 说明
latitude number 目标地纬度
longitude number 目标地经度

注意

  1. 该接口为同步接口需要在 APP 实现该接口之后, 基础库会在相关接口与组件自动调用该接口转换经纬度
  2. 基础库会转换的接口: chooseLocation、choosePoi、MapContext相关的接口
  3. 地图组件相关事件与属性也会被转换,比如: bindtap、bindmarkertap中携带的经纬度...

# convertCoordinateFromApplet

基础库3.0.19开始支持

该接口是通过注册自定义小程序同步API实现。

convertCoordinateFromApplet(Object object)

将用户输入的经纬度通过该接口做转换。

参数

Object object

属性 类型 默认值 必填 说明
latitude number 目标地纬度
longitude number 目标地经度

注意

  1. 该接口为同步接口需要在 APP 实现该接口之后, 基础库会在相关接口与组件自动调用该接口转换经纬度
  2. 基础库会转换的接口: openLocation、MapContext相关的接口
  3. 地图组件相关事件与属性也会被转换,比如: latitude、longitude、polyline等属性...