uniapp 获取当前的地理位置
一、uni.getLocation(OBJECT)
获取当前的地理位置、速度。
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
type | String | 否 | 默认为 wgs84 返回 gps 坐标,gcj02 返回国测局坐标,可用于 uni.openLocation 和 map 组件坐标,App 和 H5 需配置定位 SDK 信息才可支持 gcj02。 |
|
altitude | Boolean | 否 | 传入 true 会返回高度信息,由于获取高度需要较高精确度,会减慢接口返回速度 | 字节跳动小程序、飞书小程序、支付宝小程序不支持 |
geocode | Boolean | 否 | 默认false,是否解析地址信息 | 仅App平台支持(安卓需指定 type 为 gcj02 并配置三方定位SDK) |
highAccuracyExpireTime | Number | 否 | 高精度定位超时时间(ms),指定时间内返回最高精度,该值3000ms以上高精度定位才有效果 | App (3.2.11+)、H5 (3.2.11+)、微信小程序 (基础库 2.9.0+) |
timeout | String | 否 | 默认为 5,定位超时时间,单位秒 | 仅飞书小程序支持 |
cacheTimeout | Number | 否 | 定位缓存超时时间,单位秒;每次定位缓存当前定位数据,并记下时间戳,当下次调用在cacheTimeout之内时,返回缓存数据 | 仅飞书小程序、支付宝小程序支持 |
accuracy | String | 否 | 默认为 high,指定期望精度,支持 high,best。当指定 high 时,期望精度值为100m,当指定 best 时期望精度值为20m。当定位得到的精度不符合条件时,在timeout之前会继续定位,尝试拿到符合要求的定位结果 | 仅飞书小程序支持 |
isHighAccuracy | Boolean | 否 | 开启高精度定位 | App (3.4.0+)、H5 (3.4.0+)、微信小程序 (基础库 2.9.0+) |
success | Function | 是 | 接口调用成功的回调函数,返回内容详见返回参数说明。 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
success 返回参数说明
参数 | 说明 |
---|---|
latitude | 纬度,浮点数,范围为-90~90,负数表示南纬 |
longitude | 经度,浮点数,范围为-180~180,负数表示西经 |
speed | 速度,浮点数,单位m/s |
accuracy | 位置的精确度 |
altitude | 高度,单位 m |
verticalAccuracy | 垂直精度,单位 m(Android 无法获取,返回 0) |
horizontalAccuracy | 水平精度,单位 m |
address | 地址信息(仅App端支持,需配置geocode为true) |
address 地址信息说明
属性 | 类型 | 描述 | 说明 |
---|---|---|---|
country | String | 国家 | 如“中国”,如果无法获取此信息则返回undefined |
province | String | 省份名称 | 如“北京市”,如果无法获取此信息则返回undefined |
city | String | 城市名称 | 如“北京市”,如果无法获取此信息则返回undefined |
district | String | 区(县)名称 | 如“朝阳区”,如果无法获取此信息则返回undefined |
street | String | 街道信息 | 如“酒仙桥路”,如果无法获取此信息则返回undefined |
streetNum | String | 获取街道门牌号信息 | 如“3号”,如果无法获取此信息则返回undefined |
poiName | String | POI信息 | 如“电子城.国际电子总部”,如果无法获取此信息则返回undefined |
postalCode | String | 邮政编码 | 如“100016”,如果无法获取此信息则返回undefined |
cityCode | String | 城市代码 | 如“010”,如果无法获取此信息则返回undefined |
示例
uni.getLocation({
type: 'wgs84',
success: function (res) {
console.log('当前位置的经度:' + res.longitude);
console.log('当前位置的纬度:' + res.latitude);
}
});
#注意
H5 平台
- 在较新的浏览器上,H5 端获取定位信息,要求部署在 https 服务上,本地预览(localhost)仍然可以使用 http 协议。
- 国产安卓手机上,H5若无法定位,检查手机是否开通位置服务、GPS,ROM是否给该浏览器位置权限、浏览器是否对网页弹出请求给予定位的询问框。
安卓手机
在原生App内嵌H5时,无法定位需要原生App处理Webview。移动端浏览器
普遍仅支持GPS定位,在GPS信号弱的地方可能定位失败。PC 设备
使用 Chrome 浏览器的时候,位置信息是连接谷歌服务器获取的,国内用户可能获取位置信息失败。- 微信公众号可使用微信js sdk,详见(opens new window)
2.9.9 版本以上
,优化 uni.getLocation 支持通过 IP 定位。默认通过 GPS 获取,如果获取失败,备选方案是通过 IP 定位获取,需填写三方地图服务平台的秘钥(key)。key配置:manifest.json ---> H5配置 ---> 定位和地图 ---> key。
App 平台
- Android由于谷歌服务被墙,或者手机上没有GMS,想正常定位就需要向高德等三方服务商申请SDK资质,获取AppKey。否则打包后定位就会不准。云打包时需要在manifest的SDK配置中填写 Appkey。在 manifest 可视化界面有详细申请指南,详见:https://ask.dcloud.net.cn/article/29 (opens new window)。离线打包自行在原生工程中配置。注意包名、appkey、证书信息必须匹配。真机运行可以正常定位,是因为真机运行基座使用了DCloud向高德申请的sdk配置,打包后必须由开发者自己申请。如果手机自带GMS且网络环境可以正常访问google定位服务器,此时无需在 manifest 填写高德定位的 sdk 配置。
<map>
组件默认为国测局坐标 gcj02,调用uni.getLocation
返回结果传递给<map>
组件时,需指定 type 为 gcj02。- 定位 和 map 是两个东西。通过
getLocation
得到位置坐标后,可以在任意map地图上展示,比如定位使用高德,地图使用 google 的 webview 版地图。如果坐标系不同时,注意转换坐标系。 - 如果使用
web-view
加载地图,无需在manifest里配地图的sdk配置。 - 持续定位方案:iOS端可以申请持续定位权限,参考 (opens new window)。Android如果进程被杀,代码无法执行。可以使用 unipush (opens new window),通过服务器激活App,执行透传消息,让App启动然后采集位置。Android上,即使自己写原生插件做后台进程,也很容易被杀,unipush是更合适的方案
3.3.0 版本以上
优化系统定位模块,可不使用三方定位SDK的进行高精度定位,具体参考:系统定位。
小程序平台
- api默认不返回详细地址中文描述。需要中文地址有2种方式:1、使用高德地图小程序sdk,在app和微信上都可以获得中文地址,参考 (opens new window)。2、只考虑app,使用
plus.geolocation
也可以获取中文地址。manifest里的App SDK配置仅用于app,小程序无需在这里配置。 - 可以通过用户授权API来判断用户是否给应用授予定位权限,详见(opens new window)
- 在
微信小程序
中,当用户离开应用后,此接口无法调用,需要申请 后台持续定位权限 (opens new window),另外新版本中需要使用 wx.onLocationChange (opens new window)监听位置信息变化;当用户点击“显示在聊天顶部”时,此接口可继续调用。
- api默认不返回详细地址中文描述。需要中文地址有2种方式:1、使用高德地图小程序sdk,在app和微信上都可以获得中文地址,参考 (opens new window)。2、只考虑app,使用
二、uni.chooseLocation(OBJECT)
打开地图选择位置。
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | √ | x | x |
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
latitude | Number | 否 | 目标地纬度 | 微信小程序(2.9.0+)、H5-Vue3(3.2.10+) |
longitude | Number | 否 | 目标地经度 | 微信小程序(2.9.0+)、H5-Vue3(3.2.10+) |
keyword | String | 否 | 搜索关键字,仅App平台支持 | |
success | Function | 是 | 接口调用成功的回调函数,返回内容详见返回参数说明。 | |
fail | Function | 否 | 接口调用失败的回调函数(获取定位失败、用户取消等情况下触发) | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
注意
- 因平台差异,如果SDK配置百度地图,需要设置keyword,才能显示相关地点
nvue
下支持高德地图和Google地图(3.4+),不支持百度地图HBuilderX 2.4.0+
非 weex 编译模式仅支持高德地图
success 返回参数说明
参数 | 说明 |
---|---|
name | 位置名称 |
address | 详细地址 |
latitude | 纬度,浮点数,范围为-90~90,负数表示南纬,使用 gcj02 国测局坐标系。 |
longitude | 经度,浮点数,范围为-180~180,负数表示西经,使用 gcj02 国测局坐标系。 |
示例
uni.chooseLocation({
success: function (res) {
console.log('位置名称:' + res.name);
console.log('详细地址:' + res.address);
console.log('纬度:' + res.latitude);
console.log('经度:' + res.longitude);
}
});
注意
- 不同端,使用地图选择时基于的底层地图引擎不一样,详见地图map组件的地图服务商支持。
app
中也可以使用百度定位,在 manifest 中配置,打包后生效。app-nvue
里只能用高德定位和Google地图(3.4+),不能用百度地图。另外选择地图、查看地图位置的API也仅支持高德地图和Google地图(3.4+)。所以App端如无特殊必要,建议使用高德地图。
H5 端
使用地图和定位相关,需要在 manifest.json 内配置腾讯或谷歌等三方地图服务商申请的秘钥(key)。微信内置浏览器
中可使用微信js sdk,详见(opens new window)- chooseLocation 属于封装型API,开发者若觉得不够灵活,可自行基于原始的 map 组件进行封装。插件市场已经有各种封装样例了。
- 若
Android App端
位置不准,见上文 uni.getLocation 的注意事项
三、uni.openLocation(OBJECT)
使用应用内置地图查看位置。
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | x | x | x |
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
latitude | Float | 是 | 纬度,范围为-90~90,负数表示南纬,使用 gcj02 国测局坐标系 | |
longitude | Float | 是 | 经度,范围为-180~180,负数表示西经,使用 gcj02 国测局坐标系 | |
scale | Int | 否 | 缩放比例,范围5~18,默认为18 | 微信小程序 |
name | String | 否 | 位置名 | 支付宝必填 |
address | String | 否 | 地址的详细说明 | 支付宝必填 |
success | Function | 否 | 接口调用成功的回调函数 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例
uni.getLocation({
type: 'gcj02', //返回可以用于uni.openLocation的经纬度
success: function (res) {
const latitude = res.latitude;
const longitude = res.longitude;
uni.openLocation({
latitude: latitude,
longitude: longitude,
success: function () {
console.log('success');
}
});
}
});
Tips
- 本API是一个非原子的封装界面,开发者如有定制需求,可自己做页面实现类似功能。
- 若定位不准,参考uni.getLocation文档的注意事项(opens new window)
<map>
组件默认为国测局坐标,调用uni.getLocation
返回结果传递给<map>
组件时,需指定 type 为 gcj02。- App 端使用地图组件需要向高德等三方服务商申请SDK资质,获取AppKey,打包时需要在manifest的SDK配置中填写Appkey。在manifest可视化界面有详细申请指南,详见:https://ask.dcloud.net.cn/article/29 (opens new window)。
- H5 端使用地图和定位相关,需要在 (manifest.json)[/collocation/manifest?id=h5sdkconfig] 内配置腾讯或谷歌等三方地图服务商申请的秘钥(key)。
- iOS端 如需使用第三方地图进行导航,需要在 manifest.json 文件内增加
urlschemewhitelist
节点,在线打包即可 - 不同平台打开的地图不一样,App端是高德地图(不支持百度地图)、H5端是腾讯地图或谷歌地图、微信小程序端是腾讯地图、百度小程序是百度地图、阿里小程序是高德地图、字节跳动小程序是高德地图。
{
"app-plus": {
"distribute": {
"ios": {
"urlschemewhitelist": [
"baidumap",
"iosamap",
"qqmap"
]
}
}
}
}
四、三方定位和地图服务收费说明
- 使用三方定位或者地图服务,需向服务提供商(如:高德地图、百度地图、腾讯地图、谷歌地图)申请授权或缴纳费用。
- 申请三方定位或地图服务秘钥时请详细阅读授权和收费说明,并关注服务条款后期的变更。
- 以下是关于部分地图服务商授权和收费的简介,具体以地图服务商官网公布的最新信息为准。
- 高德地图:商用授权收费,超出配额收费。
- 百度地图:商用授权收费,超出配额收费。
- 腾讯地图:商用授权收费,超出配额收费。
- 谷歌地图:按量收费,每月可获得一些赠送金额。
- 小程序平台内置地图:无需关心地图服务商,免费使用,无配额限制。
蓦然、回首,那人就在灯火阑珊处