核心内容摘要
2026年企业级顶级开源授权工具
sculpture
获取当前的地理位置、速度。 注意：百度地图SDK已恢复云端打包和离线打包配置。 Web平台本API之前调用了腾讯地图的gcj02坐标免费转换接口，该接口从2024年7月18日起被腾讯逐步下线，导致老版本中本API无法使用。请立即升级到 。 升级后注意： cli项目需升级cli App平台 manifest中配置好自己的地图厂商key，在地图厂商的后台，填写正确包名和证书摘要。地图厂商的sdk会在运行时校验key、包名、证书的一致性 Web平台 manifest中配置好自己的地图厂商key，使用web接口如涉及白名单，需确保自己的域名在地图厂商那里正确配置了域名白名单 确保在地图厂商那里配额足够 确保在地图厂商那里有周边服务的权限。否则无法获取周围地址 如果运行在微信浏览器中，可以使用微信的jssdk的定位能力。这个是微信向腾讯地图申请的key，开发者无需配置自己的key。 地图厂商的商业授权较贵，如需购买，请点击获取优惠。 HarmonyOS HBuilderX 4.25 地图服务商说明 点击查看地图服务商兼容性 OBJECT 参数说明 参数名 类型 必填 说明 平台差异说明 type String 否 默认为 wgs84 返回 gps 坐标，gcj02 返回国测局坐标，可用于 和 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+)、抖音小程序（2.26.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 示例 示例源码如下，请查看 pre > code 标签中的内容 注意事项 在较新的浏览器上，H5 端获取定位信息，要求部署在 https 服务上，本地预览（localhost）仍然可以使用 http 协议。 国产安卓手机上，H5若无法定位，检查手机是否开通位置服务、GPS，ROM是否给该浏览器位置权限、浏览器是否对网页弹出请求给予定位的询问框。 在原生App内嵌H5时，无法定位需要原生App处理Webview。 普遍仅支持GPS定位，在GPS信号弱的地方可能定位失败。 使用 Chrome 浏览器的时候，位置信息是连接谷歌服务器获取的，国内用户可能获取位置信息失败，推荐使用Edge进行获取位置信息 微信公众号可使用微信js sdk，详见 ，优化 uni.getLocation 支持通过 IP 定位。默认通过 GPS 获取，如果获取失败，备选方案是通过 IP 定位获取，需填写三方地图服务平台的秘钥（key）。key配置：manifest.json ---> H5配置 ---> 定位和地图 ---> key。 Android由于谷歌服务被墙，或者手机上没有GMS，想正常定位就需要向高德等三方服务商申请SDK资质，获取AppKey。否则打包后定位就会不准。云打包时需要在manifest的SDK配置中填写 Appkey。在 manifest 可视化界面有详细申请指南，详见：https://ask.dcloud.net.cn/article/29。离线打包自行在原生工程中配置。注意包名、appkey、证书信息必须匹配。真机运行可以正常定位，是因为真机运行基座使用了DCloud向高德申请的sdk配置，打包后必须由开发者自己申请。如果手机自带GMS且网络环境可以正常访问google定位服务器，此时无需在 manifest 填写高德定位的 sdk 配置。 注意手机自身要开启定位、同时要给App赋予定位权限。权限判断可参考：https://uniapp.dcloud.net.cn/api/system/getappauthorizesetting.html 组件默认为国测局坐标 gcj02，调用 返回结果传递给 组件时，需指定 type 为 gcj02。 定位 和 map 是两个东西。通过 得到位置坐标后，可以在任意map地图上展示，比如定位使用高德，地图使用 google 的 webview 版地图。如果坐标系不同时，注意转换坐标系。 如果使用 加载地图，无需在manifest里配地图的sdk配置。 持续定位方案：iOS端可以申请持续定位权限，参考。Android如果进程被杀，代码无法执行，可以在插件市场搜索保活相关原生语言插件避免App被系统杀死。即使使用了原生语言插件保活，也很容易被杀，此时可以使用unipush ，通过推送消息提示用户激活App 优化系统定位模块，可不使用三方定位SDK的进行高精度定位，具体参考：系统定位。 鸿蒙系统 4（不是鸿蒙 5、纯血鸿蒙）不支持系统定位，需要配置三方sdk，比如高德，同时设置坐标系参数为 Android/iOS平台使用腾讯定位SDK需到 腾讯位置服务 官网申请应用Key并配置： HBuilderX内置支持腾讯定位，在manifest.json勾选配置，详情参考Geolocation定位 可下载腾讯定位插件，在插件中配置key打包后生效，腾讯定位是ext api插件引用到工程后，会覆盖uni.getLocation的实现，替换掉系统定位。 api默认不返回详细地址中文描述。需要中文地址有2种方式：1、使用高德地图小程序sdk，在app和微信上都可以获得中文地址，参考。2、只考虑app，使用也可以获取中文地址。manifest里的App SDK配置仅用于app，小程序无需在这里配置。 可以通过用户授权API来判断用户是否给应用授予定位权限，详见 在 中，当用户离开应用后，此接口无法调用，需要申请 后台持续定位权限 ，另外新版本中需要使用 wx.onLocationChange 监听位置信息变化；当用户点击“显示在聊天顶部”时，此接口可继续调用。 如果在app模块中勾选了系统定位和其他定位，比如腾讯定位，由配置的type值决定调用规则，type值为wgs84使用系统定位，type值为gcj02则使用腾讯定位。 HarmonyOS 5平台 注意事项： 鸿蒙 4.x 版本参考上方 App 要求限制，这里指代鸿蒙 5版本。 使用位置权限使用鸿蒙系统定位，不依赖三方服务。调用此 API 需要申请定位权限、，具体操作步骤见下方描述。 这里介绍鸿蒙位置权限如何配置。将鸿蒙应用正常运行启动。在 HBuilderX 工程中找到 把 文件复制放到 把 将其复制到 编辑 ，在 中添加下面代码 示例源码如下，请查看 pre > code 标签中的内容 这里的定位和模糊定位务必同时存在，否则会被上架驳回。在 api 可在 isHighAccuracy 属性中切换。 这里的 reason 值为 开头，不可直接中文字符，需要使用资源引用。编辑刚才复制的 harmony-config 目录中的 ，添加下面代码并改写 value。 示例源码如下，请查看 pre > code 标签中的内容 这里使用也可以放入 zh_CN 目录中，zh_CN > base 目录，细节可参考《鸿蒙 资源分类与访问》 打开地图选择位置。chooseLocation会使用项目配置的地图服务商来展示地图，地图服务商支持情况参考：map组件。 Web平台和App平台，本API之前调用了腾讯地图的gcj02坐标免费，该接口从2024年7月18日起被腾讯逐步下线，导致老版本中本API无法使用。请立即升级到 。 升级后注意： 如果是cli或离线打包，需要配套升级cli和离线sdk manifest中配置好自己的地图厂商key。web和app都需要。一般标准基座正常，自定义基座和打包后异常，都是这个原因 确保在地图厂商那里配额足够 确保在地图厂商那里有周边服务的权限。否则无法获取周围地址 web平台确保自己的域名在地图厂商那里正确配置了域名白名单 地图厂商的商业授权较贵，如需购买，请点击获取优惠。 平台差异说明 App H5 微信小程序 支付宝小程序 百度小程序 抖音小程序、飞书小程序 QQ小程序 快手小程序 京东小程序 元服务 √ √ √ √ √ √ √ √ √ √ HarmonyOS HBuilderX 4.23 地图服务商说明 点击查看地图服务商兼容性 OBJECT 参数说明 参数名 类型 必填 说明 平台差异说明 latitude Number 否 目标地纬度 微信小程序（2.9.0+）、H5-Vue3（3.2.10+） longitude Number 否 目标地经度 微信小程序（2.9.0+）、H5-Vue3（3.2.10+） keyword String 否 搜索关键字，仅App平台支持 useSecureNetwork Boolea 否 是否通过安全网络调用地点搜索、逆地址解析，默认false success Function 是 接口调用成功的回调函数，返回内容详见返回参数说明。 fail Function 否 接口调用失败的回调函数（获取定位失败、用户取消等情况下触发） complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行） 腾讯地图服务商说明 出于安全考虑，安卓、iOS端manifest.json内配置的 腾讯位置服务 Key 仅用来展示地图，uni.chooseLocation所依赖的地点搜索、逆地址解析功能需要通过uniCloud云对象uni-map-co来调用，开发者可以通过安全网络来保障服务端api不被他人盗用。 鸿蒙平台由于暂不支持安全网络，所以chooseLocation依然使用manifest.json内配置的key来调用地点搜索、逆地址解析。 默认情况下，uni.chooseLocation不会使用安全网络请求uni-map-co。如果需要使用安全网络请求uni-map-co，需按如下步骤操作： 项目关联uniCloud服务空间 参考uni-map-co文档导入uni-map-common插件，并配置好地图的key。 参考安全网络文档，将应用关联到服务空间。 在项目manifest.json中中勾选安全网络模块。 修改uni-map-co入口文件内添加如下代码，拦截非法请求： 示例源码如下，请查看 pre > code 标签中的内容 上传uni-map-co云对象、uni-config-center公共模块、uni-map-common公共模块。 调用uni.chooseLocation时，将useSecureNetwork设置为true。 注意 因平台差异，如果SDK配置百度地图，需要设置 keyword，才能显示相关地点 非 weex 编译模式不支持百度地图 success 返回参数说明 参数 说明 name 位置名称 address 详细地址 latitude 纬度，浮点数，范围为-90~90，负数表示南纬，使用 gcj02 国测局坐标系。 longitude 经度，浮点数，范围为-180~180，负数表示西经，使用 gcj02 国测局坐标系。 示例 示例源码如下，请查看 pre > code 标签中的内容 注意 不同端，使用地图选择时基于的底层地图引擎不一样，详见地图map组件的地图服务商支持。 中也可以使用百度定位，在 manifest 中配置，打包后生效。 里只能用高德定位和Google地图(3.4+)，不能用百度地图。另外选择地图、查看地图位置的API也仅支持高德地图和Google地图(3.4+)。所以App端如无特殊必要，建议使用高德地图。 使用地图和定位相关，需要在 manifest.json 内配置腾讯或谷歌等三方地图服务商申请的秘钥（key）。 中可使用微信js sdk，详见 chooseLocation 属于封装型API，开发者若觉得不够灵活，可自行基于原始的 map 组件进行封装。插件市场已经有各种封装样例了。 若 位置不准，见上文 uni.getLocation 的注意事项 微信小程序在2023年10月17日之后，使用API需要配置隐私协议 使用三方定位或者地图服务，需向服务提供商（如：高德地图、百度地图、腾讯地图、谷歌地图）申请商业授权和缴纳费用（5万/年）。 详见：https://uniapp.dcloud.net.cn/tutorial/app-geolocation.html#lic 若想要实现城市选择功能，可以使用 城市选择组件。 运行效果图 下载地址：https://ext.dcloud.net.cn/plugin?name=unicloud-city-select 文档地址：https://doc.dcloud.net.cn/uniCloud/unicloud-city-select.html
