简体中文
简体中文
# 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 | √ |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| 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，需自行在项目中配置权限。
示例
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 |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| 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 |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| 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 |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| HBuilderX 4.25 |
注意：App端及H5端callback参数为必填。
FUNCTION CALLBACK 参数
无返回值。
# uni.startLocationUpdate(OBJECT)
开启应用进入前台时接收位置消息。
平台差异说明
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 抖音小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
|---|---|---|---|---|---|---|---|---|
| √（3.6.8+） | √（3.6.8+） | √ | x | √ | √ | x | √ | x |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| 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 |
HarmonyOS Next 兼容性
| HarmonyOS Next |
|---|
| 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，需自行在项目中配置权限。
# 三方定位和地图服务收费说明
使用三方定位或者地图服务，需向服务提供商（如：高德地图、百度地图、腾讯地图、谷歌地图）申请商业授权和缴纳费用（5万/年）。
DCloud为开发者争取了福利，可优惠获取高德、腾讯的商业授权。如有需求请发邮件到bd@dcloud.io（注明你的公司名称、应用介绍、HBuilder账户）；你也可以直接通过uni-im发起在线咨询，在线咨询地址：DCloud地图服务专员。
详见：https://uniapp.dcloud.net.cn/tutorial/app-geolocation.html#lic
