更新记录

1.1.9(2022-08-05)

新增: 定位配置参数,见底部文档说明,默认值均为官方默认值,代码中不设置不影响之前版本配置。

1.1.8(2022-04-22)

新增: 定位接口新增开关checkPermissions控制是否检查申请定位权限,适用于在onReady,内(调用会导致执行2次,检查申请权限会触发onhide,)调用的需求,请自行将权限检测申请放在其他地方。

查看更多

平台兼容性

Android iOS
适用版本区间:4.4 - 11.0 ×

原生插件通用使用流程:

  1. 购买插件,选择该插件绑定的项目。
  2. 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
  3. 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
  4. 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
  5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择


1.1.7版本增加参数控制是否检查权限,以避免在onReady,生命周期调用定位接口出现执行2次。

1.1.4版本使用最近几个版本没有问题(已测HBX3.3.3-HBX3.3.5,HBX3.2.16)【HBX3.3.3及以上需要检查隐私合规,参数默认均为true,详情见底部参数表格】

本插件与另一个基本一致,接口名称略有区别。https://ext.dcloud.net.cn/plugin?id=7013

福利插件【高德导航】

1分购导航插件

完整版 https://ext.dcloud.net.cn/plugin?id=7109

精简版 https://ext.dcloud.net.cn/plugin?id=7110

精简版体积小,方便打调试包。



高德持续定位使用,符合作者所做项目,使用时请确认是否满足项目需求【主要作用是后台持续定位(用户必须给相应权限,且不清理后台运行应用前提下),以及单次获取定位信息】。


默认开启定位缓存机制locationCacheEnable,可关闭、并打开屏幕唤醒以便更新位置。


若打包出现问题(无回调等)可重新打包或更新HBX后重新打包。

更新

v1.1.9版本:

新增: 定位配置参数,见底部文档说明,默认值均为官方默认值,代码中不设置不影响之前版本配置。

v1.1.8版本:

新增: 定位接口新增开关checkPermissions控制是否检查申请定位权限,适用于在onReady,内(调用会导致执行2次,检查申请权限会触发onhide,)调用的需求,请自行将权限检测申请放在其他地方。

v1.1.7版本:

新增: 打开系统设置

v1.1.6版本:

新增: 打开设置、电源管理(可能部分机型无法打开)

v1.1.5版本:

修复:优化权限获取,与 https://ext.dcloud.net.cn/plugin?id=7013保持同步。

修复: 获取是否有权限错误

新增: 打开gps设置

v1.1.4版本:

更新:将淘宝weex类全部更为Uniapp类。

修复:HBX3.2.16打包无回调,其余低版本未测试,建议使用最近几个版本打包。

增加:持续和单次定位接口增加apikey参数,用于不使用官方map包的应用(但其他插件需包含定位SDK)

增加:获取是否授权定位(忘了加文档说明了,20220304补充文档)

v1.1.3版本:

!!!重要更新:同步uni官方更新,修复新版HBX(3.3.3)版本打包插件无法正常使用问题。

定位接口新增3个隐私政策参数,详细信息见底部参数表格

修复:stop接口无回调[已加回调]

v1.1.2版本:

新增:引导用户设置白名单 【见接口7-10】,如果之前自己实现的可以不用此接口,新增的接口当前只测试了小米华为部分机子。

v1.1.1版本:

新增:屏幕唤醒【见接口4、5】 。

v1.1.0版本:

优化,并基于最新sdk重新打包【*】。

v1.0.9版本:

新增:设置是否开启定位缓存机制locationCacheEnable,默认true 。

v1.0.8版本:

新增:海拔altitude 街道street 街道门牌号streetNum 。

v1.0.7版本:

修复:调用stop接口时取消常驻通知图标。

v1.0.5版本:
  1. once接口参数:支持locationMode和gpsFirst参数见底部参数说明。
  2. start方法增加常驻通知文字描述配置。
v1.0.4版本:

start方法增加3个参数:见底部参数说明

1)定位场景 2)定位模式 3)GPS优先

v1.0.3版本:

修改电量获取,优化结果json结构,将非定位信息单独摘出

示例

{ "GPSSatellites": 0, "GPSStatus": 0, "accuracy": 30, "adCode": "000000", "address": "XX省XX市XX区南一路x号靠近XXXX园B座", "androidBuild": { //手机相关信息 "appVersionCode": 1, "appVersionName": "1.0.0", "brand": "Xiaomi", "cpu_abi": "armeabi-v7a", "cpu_abi2": "armeabi", "model": "MI 6", "product": "sagit", "release": "9", "sdk": "28", "sdk_int": 28 }, "battery": {//电池信息 "level": 100, "status": 2 }, "bearing": 0, "city": "XX市", "cityCode": "0123", "code": 0,//根据此值判断定位结果 "country": "中国", "description": "在XXXX园B座附近", "district": "XXX区", "isWifiAble": true, "latitude": 37, "locationType": 2,//定位类型,见下方定位类型对照表 "longitude": 118, "message": "OK", "now": 1604477982093, "poiName": "XXXX园B座", "provider": "lbs", "province": "XX省", "result": "OK", "satellites": 0, "speed": 0, "time": 1604477976956 }

v1.0.2版本:

修改dc.okhttp(新版dc.okhttp3)为官方okhttp3,防止DC更改包名出错。

如有问题,请及时反馈。。。

已知问题

1.申请忽略电池优化:在小米新机子上打开的不是优化申请窗或优化页,而是【应用智能省电】(点击是省电策略),旧机子(如MI6)没问题。但是去【设置】搜索【电池优化】当前前应用已加入。

解决:可以先调用省电策略,在判断是否忽略电池优化,没忽略再申请。

接口说明

引入插件: 在manifest中app原生插件配置中,添加云端插件

选择高德地图并填入正确key.

const fUN_AmapLocation = uni.requireNativePlugin('FUN-AmapLocation');

定位主功能

1.申请权限【也可用uni.getLocation来申请】

// 权限申请2次,第一次申请 使用中允许 第二次才会出现 始终允许
//可提前申请权限。也可用uni.getLocation来提前申请。防止第一次可能定位失败。[start接口也有权限判断申请]
fUN_AmapLocation.permission({}, result => {
    console.log('====fUN_AmapLocation定位====');
});
//以下也可以,
fUN_AmapLocation.requestLocationPermissions(function(result) {

});

2.获取是否授权定位

fUN_AmapLocation.hasLocationPermissions(function(result) {
    console.log(result)
});
//结果code=0时,flag:true代表有定位权限,flag_br:true代表允许后台定位(AndroidQ即sdk_int>=29)
//sdk_int>28 android Q 有后台定位始终允许(经测 小米6 安卓9 sdk28 也有但无法调请求窗,经测试不影响后台定位[息屏或置于后台])

3.开启持续定位【参数见下方参数说明】

// startLocation与start均可
fUN_AmapLocation.start(
                {
                    intervalTime: 5000,
                    reportInterval: 5,
                    isReport: true,
                    url: 'http://192.168.0.66/fun/open/test_json.do',
                    params: { a: 1, B: '测试', c: true },
                    headers: { a: '123', B: 'abcd' }
                },
                result => {
                    //见下方定位返回示例
                    console.log('====fUN_AmapLocation定位====', JSON.stringify(result));
                    _this.msg = JSON.stringify(result);
                }
            ); 

4.停止持续定位【参数传空对象{},保留,防后续加参数 】

// stopLocation 与 stop 均可
fUN_AmapLocation.stop({}, result => {
            console.log('====fUN_AmapLocation定位stop====', JSON.stringify(result));
        });

5.单次定位【参数见下方参数说明】

// onceLocation 与 once 均可
fUN_AmapLocation.once({}, result => {
                    console.log('====fUN_AmapLocation定位====', JSON.stringify(result));
                    _this.msg = JSON.stringify(result);
                }
            );

以下附加功能

6.打开屏幕唤醒【开启唤醒增加保活和位置更新】

//1台华为[鸿蒙],2台小米(米6[安卓9]、米11Ultra[安卓11])使用的10分测试的。
fUN_AmapLocation.openWakeLock({time:5},function(result) {
    console.log(result)
});
//参数    time:间隔时间,单位:分,建议5-10。具体看业务

7.关闭屏幕唤醒

fUN_AmapLocation.colseWakeLock(function(result) {
    console.log(result)
});

8.检测是否忽略电池优化(简单解释:开启电池优化,会干掉应用)

fUN_AmapLocation.isIgnoringBatteryOptimizations(function(result) {//SDK>=23,否则返回不支持
    console.log(result);
})
//以下为结果示例(期望结果是忽略优化即"flag": true)
{
    "sdk_int": 28,
    "flag": true,//电池是否忽略优化,true:忽略;false:优化
    "code": 0,
    "msg": "ok"
}

9. 申请忽略电池优化(如果已加入电池优化的白名单 则进入系统电池优化页面,若未加入则弹窗申请。)

//如果已加入电池优化的白名单 则进入系统电池优化页面,
//若未加入则弹窗申请,
//可使用isIgnoringBatteryOptimizations检测
fUN_AmapLocation.requestIgnoreBatteryOptimizations(function(result) {
    console.log(result)
});
//以下为结果示例(调用那一刻的情况,比如初次默认是优化,那返回结果就是"flag": false)
{
    "sdk_int": 28,
    "flag": true,//电池是否忽略优化,true:忽略;false:优化
    "code": 0,
    "msg": "ok"
}

10. 设置省电策略

fUN_AmapLocation.setPowerKeeper(function(result) {
    console.log(result)
});

11.设置自启动

fUN_AmapLocation.startToAutoStartSetting(function(result) {
    console.log(result)
});

12.打开GPS设置【位置信息设置】

fUN_AmapLocation.openGpsSetting( result => {
                    console.log('====fUN_AmapLocation定位====', JSON.stringify(result));

                }
            );

12.打开应用设置页[1.1.6新增]

fUN_AmapLocation.openSetting(function(result) {

});

13.打开耗电统计[1.1.6新增]

fUN_AmapLocation.openPowerUsageSummary(function(result) {

});

14.打开系统设置页[1.1.7新增]

fUN_AmapLocation.openSystemSetting(function(result) {

});

参数说明

https://lbs.amap.com/api/android-location-sdk/guide/android-location/getlocation 部分参数可参考官方

1.start接口参数:

参数 参数 参数说明
intervalTime 间隔时间 可选,设置定位间隔,单位毫秒,默认为2000ms,最低1000ms。参数类型:数字。默认值:2000
locationMode 定位模式 可选,设置定位模式,可选的模式有高精度、仅设备、仅网络(低功耗)。默认为高精度模式。参数类型:数字。1:高精度、2:仅网络(低功耗)、3:仅设备。默认值:1
gpsFirst GPS优先 可选,设置是否gps优先,只在高精度模式下有效。默认关闭。参数类型:布尔。true/false,默认值:false
isReport 是否上传 可选,是否使用内置客户端上传数据。参数类型:布尔。true/false,默认值:false
reportInterval 上传间隔 可选,单位:次数,时间间隔为 intervalTime*reportInterval。参数类型:数字。默认值:3
url URL 可选,上传地址。例如'http://192.168.0.66/fun/open/test_json.do'
params HTTP-body 可选,其他上传数据。例如{ a: 1, B: '测试', c: true }
headers HTTP消息头 可选,HTTP消息头自定义数据。例如{ a: 1, B: '测试', c: true }
purpose 定位场景 可选,选择了对应的定位场景,SDK会根据选择的场景自行定制定位参数的值,自行设置的参数覆盖此配置。目前支持3种定位场景的设置:签到、出行、运动。默认无场景。参数类型:数字。0:无、1:签到、2:出行、3:运动。默认值:0
notificationTitle 常驻通知标题 默认:APP名称【1.0.5新增】
notificationText 常驻通知内容 默认:正在后台运行【1.0.5新增】
locationCacheEnable 缓存机制 缓存机制默认启用缓存策略,SDK将在设备位置未改变时返回之前相同位置的缓存结果。当开启定位缓存功能,在高精度模式和低功耗模式下进行的网络定位结果均会生成本地缓存,不区分单次定位还是连续定位。GPS定位结果不会被缓存。参数类型:布尔,true/false,默认值:true。【1.0.9新增】
isContains 隐私 默认值:true。是隐私权政策是否包含高德开平隐私权政策 true是包含
isShow 隐私 默认值:true。隐私权政策是否弹窗展示告知用户 true是展示
isAgree 隐私 默认值:true。隐私权政策是否取得用户同意 true是用户同意
apikey KEY 高德key,manifest.json文件已配置高德地图key的忽略
checkPermissions 开关 默认值:true。控制是否检查申请定位权限,false即不检查【1.1.8新增】
isNeedAddress 地址描述 默认值:true。true表示定位返回经纬度同时返回地址描述(定位类型是网络定位的会返回);false表示不返回地址描述。【1.1.9新增】
isOnceLocationLatest --->> 默认值:false。true表示获取最近3s内精度最高的一次定位结果;false表示使用默认的连续定位策略。【1.1.9新增】
isWifiActiveScan --->> 默认值:false。true表示会主动刷新设备wifi模块,获取到最新鲜的wifi列表(wifi新鲜程度决定定位精度);false表示不主动刷新。【1.1.9新增】

2.once接口参数:

参数 参数说明
locationMode 定位模式 可选,设置定位模式,可选的模式有高精度、仅设备、仅网络(低功耗)。默认为高精度模式。参数类型:数字。1:高精度、2:仅网络(低功耗)、3:仅设备。默认值:1
gpsFirst GPS优先 可选,设置是否gps优先,只在高精度模式下有效。默认关闭。参数类型:布尔。true/false,默认值:false
locationCacheEnable 缓存机制 缓存机制默认启用缓存策略,SDK将在设备位置未改变时返回之前相同位置的缓存结果。当开启定位缓存功能,在高精度模式和低功耗模式下进行的网络定位结果均会生成本地缓存,不区分单次定位还是连续定位。GPS定位结果不会被缓存。参数类型:布尔,true/false,默认值:true。【1.0.9新增】
isContains 隐私 默认值:true。是隐私权政策是否包含高德开平隐私权政策 true是包含
isShow 隐私 默认值:true。隐私权政策是否弹窗展示告知用户 true是展示
isAgree 隐私 默认值:true。隐私权政策是否取得用户同意 true是用户同意
apikey KEY 高德key,manifest.json文件已配置高德地图key的忽略
checkPermissions 开关 默认值:true。控制是否检查申请定位权限,false即不检查【1.1.8新增】
isNeedAddress 地址描述 默认值:true。true表示定位返回经纬度同时返回地址描述(定位类型是网络定位的会返回);false表示不返回地址描述。【1.1.9新增】
isOnceLocationLatest --->> 默认值:false。true表示获取最近3s内精度最高的一次定位结果;false表示使用默认的连续定位策略。【1.1.9新增】
isWifiActiveScan --->> 默认值:false。true表示会主动刷新设备wifi模块,获取到最新鲜的wifi列表(wifi新鲜程度决定定位精度);false表示不主动刷新。【1.1.9新增】

返回结果

1.关键字段code : 其值就是errorCode,2字段一样(1.1.1版本正常情况不显示,下版本增加)。0 为定位成功。错误码对照表

2.主要字段如下:

字段 返回值 返回值说明 备注(此处版本号为高德SDK版本号,具体使用版本取决uniapp官方集成)
latitude double 纬度 V2.0.0版本起
longitude double 经度 V2.0.0版本起
accuracy float 精度 V2.0.0版本起
altitude double 海拔 V2.0.0版本起
speed float 速度 V2.0.0版本起
bearing float 方向角 V2.0.0版本起
buildingId String 室内定位建筑物Id V3.2.0版本起
floor String 室内定位楼层 V3.2.0版本起
address String 地址描述 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
country String 国家 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
province String V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
sity String 城市 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
district String 城区 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
street String 街道 V2.3.0版本起模式为仅设备模式(Device_Sensors)时无此信息
streetNum String 街道门牌号 V2.3.0版本起模式为仅设备模式(Device_Sensors)时无此信息
cityCode String 城市编码 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
adCode String 区域编码 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
poiName String 当前位置POI名称 V2.0.0版本起模式为仅设备模式(Device_Sensors)时无此信息
aoiName String 当前位置所处AOI名称 V2.4.0版本起模式为仅设备模式(Device_Sensors)时无此信息
accuracyStatus int 设备当前 GPS 状态 V3.1.0版本起模式为仅设备模式(Device_Sensors)时提供此信息
locationType int 定位来源 V2.0.0版本起可参考定位类型编码表
locationDetail String 定位信息描述 V2.0.0版本起用于问题排查
errorInfo String 定位错误信息描述 V2.0.0版本起可参考定位错误码表
errorCode String 定位错误码 V2.0.0版本起可参考定位错误码表

定位类型【locationType】对照表

响应码 说明 介绍
0 定位失败 请通过错误码参考错误码对照表进行问题排查。
1 GPS定位结果 通过设备GPS定位模块返回的定位结果,精度较高,在10米-100米左右
2 前次定位结果 网络定位请求低于1秒、或两次定位之间设备位置变化非常小时返回,设备位移通过传感器感知。
4 缓存定位结果 返回一段时间前设备在同样的位置缓存下来的网络定位结果
5 Wifi定位结果 属于网络定位,定位精度相对基站定位会更好,定位精度较高,在5米-200米之间。
6 基站定位结果 纯粹依赖移动、联通、电信等移动网络定位,定位精度在500米-5000米之间。
8 离线定位结果 -
9 最后位置缓存 -

示例:

//可提前申请权限。也可用uni.getLocation来提前申请。防止第一次可能定位失败。[start接口也有权限判断申请]
fUN_AmapLocation.permission({}, result => {
            console.log('====fUN_AmapLocation定位====');
        });
//开启定位
fUN_AmapLocation.start(
                {
                    intervalTime: 5000,
                    reportInterval: 5,
                    isReport: true,
                    url: 'http://192.168.0.66/fun/open/test_json.do',
                    params: { a: 1, B: '测试', c: true },
                    headers: { a: '123', B: 'abcd' }
                },
                result => {
                    //见下方定位返回示例
                    console.log('====fUN_AmapLocation定位====', JSON.stringify(result));
                    _this.msg = JSON.stringify(result);
                }
            );  
//定位返回示例
{"B":"测试","GPSSatellites":0,"GPSStatus":0,"a":1,"accuracy":54,"adCode":"370000","address":"山东省XX市XX区南一路122号靠近XX软件园C座","appVersionCode":1,"appVersionName":"1.0.0","bearing":0,"c":true,"city":"XX市","cityCode":"0123","code":0,"country":"中国","description":"在XX软件园C座附近","district":"XX区","isWifiAble":true,"latitude":33.00000,"locationType":2,"longitude":188.00000,"message":"OK","model":"MI 6","now":1591861526567,"poiName":"XX软件园C座","provider":"lbs","province":"山东省","release":"9","result":"OK","satellites":0,"sdk":"28","speed":0,"time":1591861472743}

//停止

//单次定位接口
fUN_AmapLocation.once(
                {},
                result => {
                    console.log('====fUN_AmapLocation定位====', JSON.stringify(result));
                    _this.msg = JSON.stringify(result);
                }
            );

//间隔一定时间做相关操作可如下处理,具体以个人实际业务为准
var time_start = 0;
            fUN_AmapLocation.start(
                {
                    intervalTime: 3000,
                    isReport: false
                },
                result => {
                    var time_end = Date.parse(new Date());
                    if (time_end - time_start > 298000) {//
                        if (result.code == 0) {
                            time_start = time_end;
                            //业务逻辑
                        }
                    }
                }
            );

隐私、权限声明

1. 本插件需要申请的系统权限列表:

定位权限,网络访问权限,读写权限、更改设置、后台定位、屏幕唤醒

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无,高德是否采集参考其官方说明https://lbs.amap.com/api/android-location-sdk/locationsummary/

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问