uni.onLocationChange(FUNCTION CALLBACK)

展示全部

# uni.onLocationChange(FUNCTION CALLBACK)

监听实时地理位置变化事件，需结合 uni.startLocationUpdate 或 uni.startLocationUpdateBackground 使用。

注意

Web平台本API之前调用了腾讯地图的gcj02坐标免费转换接口，该接口从2024年7月18日起被腾讯逐步下线，导致老版本中本API无法使用。请立即升级到 uni-app 4.24版。

升级后注意：

cli项目需升级cli
manifest中配置好自己的地图厂商key
确保在地图厂商那里配额足够
确保在地图厂商那里有周边服务的权限。否则无法获取周围地址
确保自己的域名在地图厂商那里正确配置了域名白名单

如果运行在微信浏览器中，可以使用微信的jssdk的定位能力。这个是微信向腾讯地图申请的key，开发者无需配置自己的key。

地图厂商的商业授权较贵，如需购买，请点击获取优惠。

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序	元服务	小红书小程序
√（3.6.8+）	√（3.6.8+）	√	x	√	√	x	√	x	√	√

# onLocationChange 兼容性

HarmonyOS
HBuilderX 4.25

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
latitude	Number	纬度，范围为 -90~90，负数表示南纬。
longitude	Number	经度，范围为 -180~180，负数表示西经。
speed	Number	速度 (m/s)	H5不支持
accuracy	number	位置的精确度
altitude	number	高度 (m)	H5不支持
verticalAccuracy	number	垂直精度 (m)	抖音小程序、快手小程序 Android 无法获取，返回 0
horizontalAccuracy	number	水平精度 (m)	抖音小程序不支持
city	string	定位到的城市信息	百度小程序、抖音小程序（iOS 不支持）
cityCode	String	城市编码	百度小程序
street	String	街道名称
city	String	城市名称	百度小程序
country	String	国家	百度小程序
countryCode	String	国家代码	百度小程序
province	String	省份	百度小程序
streetNumber	String	街道号码	百度小程序
district	String	区	百度小程序
isFullAccuracy	Boolean	是不是精确定位信息	百度小程序
altitudeAccuracy	Number	海拔的精确度信息	App

注意

该方法会持续监听地理位置信息的变化，建议在不需要监听地理位置信息变化后，直接调用 uni.stopLocationUpdate 方法取消监听。
微信小程序若使用该接口，需要在 app.json 中进行声明，否则将无法正常使用该接口，详情
抖音小程序调用此 API 需要申请高精度权限，具体信息见高精度定位运营规范。
HarmonyOS Next平台调用此 API 需要申请定位权限ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION，需自行在项目中配置权限。具体位置在 harmony-configs/entry/src/main/module.json5 中的 requestPermissions 字段。该配置文件在构建产物中原始鸿蒙工程相同目录内。

示例

uni.onLocationChange(function (res) {
	console.log('纬度：' + res.latitude);
	console.log('经度：' + res.longitude);
});

# uni.offLocationChange(FUNCTION CALLBACK)

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

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√（3.6.8+）	√（3.6.8+）	√	x	√	√	x	√	x

# offLocationChange 兼容性

HarmonyOS
HBuilderX 4.25

注意：App端及H5端callback参数为必填。

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
latitude	number	纬度，范围 [-90, 90]，负数表示南纬	快手小程序
longitude	number	经度，范围 [-180, 180]，负数表示西经	快手小程序
speed	number	速度 (m/s)	快手小程序
accuracy	number	位置的精确度	快手小程序
altitude	number	高度 (m)	快手小程序
verticalAccuracy	number	垂直精度 (m)（Android 无法获取，返回 0）	快手小程序
horizontalAccuracy	number	水平精度 (m)	快手小程序

# uni.onLocationChangeError(FUNCTION CALLBACK)

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

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√（3.6.8+）	√（3.6.8+）	√	x	x	√	x	x	x

# onLocationChangeError 兼容性

HarmonyOS
HBuilderX 4.25

FUNCTION CALLBACK 参数

参数名	类型	说明	平台差异说明
errCode	Number	错误	微信小程序
errMsg	String	错误信息	抖音小程序

# uni.offLocationChangeError(FUNCTION CALLBACK)

取消注册位置更新错误回调。

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√（3.6.8+）	√（3.6.8+）	√	x	x	√	x	x	x

# offLocationChangeError 兼容性

HarmonyOS
HBuilderX 4.25

注意：App端及H5端callback参数为必填。

FUNCTION CALLBACK 参数

无返回值。

# uni.startLocationUpdate(OBJECT)

开启应用进入前台时接收位置消息。

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√（3.6.8+）	√（3.6.8+）	√	x	√	√	x	√	x

# startLocationUpdate 兼容性

HarmonyOS
HBuilderX 4.25

OBJECT 参数

参数名	类型	必填	说明	平台差异说明
type	String	否	指定坐标系类型，可以是 wgs84 或 gcj02	微信小程序、抖音小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）
needFullAccuracy	Boolean	否	针对 iOS14/Android12 及以上的新特性，其他情况本参数忽略。默认情况宿主是精确定位就返回精确定位信息。传入 true 会强制使用精确定位信息，iOS14/Android12 及以上如果没有精确定位权限，会弹出精确定位授权弹框。	百度小程序

示例

uni.startLocationUpdate({
  success: res => console.log('开启应用接收位置消息成功'),
  fail: err => console.error('开启应用接收位置消息失败：', err),
  complete: msg => console.log('调用开启应用接收位置消息 API 完成')
});

# uni.stopLocationUpdate(OBJECT)

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

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
√（3.6.8+）	√（3.6.8+）	√	x	√	√	x	√	x

# stopLocationUpdate 兼容性

HarmonyOS
HBuilderX 4.25

OBJECT 参数

参数名	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# uni.startLocationUpdateBackground(OBJECT)

开始监听实时地理位置信息变化事件，应用进入前后台时均接收实时地理位置信息。

平台差异说明

App	HarmonyOS Next	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序
x	HBuilderX 4.31	x	√	x	x	x	x	√	x

OBJECT 参数

参数名	类型	必填	说明	平台差异说明
type	String	否	指定坐标系类型，可以是 wgs84 或 gcj02	微信小程序、抖音小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

注意

HarmonyOS Next平台调用此 API 需要申请定位权限ohos.permission.APPROXIMATELY_LOCATION、ohos.permission.LOCATION及后台定位权限ohos.permission.LOCATION_IN_BACKGROUND，需自行在项目中配置权限。具体位置在 harmony-configs/entry/src/main/module.json5 中的 requestPermissions 字段。该配置文件在构建产物中原始鸿蒙工程相同目录内。