更新记录

1.0.8(2024-10-13)

  • 【更新】兼容iOS

1.0.7(2024-08-27)

  • 【修复】修复AndroidManifest.xml的bug

1.0.6(2024-08-26)

  • 【新增】设置自启动(支持小米,华为,红米,oppo,vivo厂商)
  • 【新增】申请白名单权限和检查白名单权限
  • 【新增】开启北斗定位和关闭北斗定位
  • 【新增】开启步骑行惯导和关闭步骑行惯导
  • 【新增】判断设备是否支持GPS定位
  • 【新增】两个点以经纬度的形式计算距离
查看更多

平台兼容性

Vue2 Vue3
App 快应用 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
HBuilderX 4.28,Android:4.4,iOS:不确定,HarmonyOS:不确定 × × × × × ×
钉钉小程序 快手小程序 飞书小程序 京东小程序
× × × ×
H5-Safari Android Browser 微信浏览器(Android) QQ浏览器(Android) Chrome IE Edge Firefox PC-Safari
× × × × × × × × ×

x-tencent-s【腾讯定位】保姆和小白式的完美解决方案

常见问题

  • 注意:本插件已实现https://lbs.qq.com/mobile/androidLocationSDK/androidGeoGuide/androidGeoBack该文档后台定位
  • 运行之前需要打包自定义基座,并且需要提前引入在页面使用之后再打包,防止官方摇树
  • 如有问题请及时在uni-im的x-tencent-s群反馈
  • 本文档只支持Hbuilder X4.23,Hbuilder X4.24,Hbuilder X4.26版本
  • 普通授权用户/试用用户/源码授权用户使用教程请看文档最下面(强烈建议)

示例代码

  • 引入
import { 
    xSetKey,
    xSetUserAgreePrivacy,
    xGetLocation,
    xGetOnceLocation,
    xStopLocation,
    xGetSceneLocation,
    xStopSceneLocation,
    xGetBackstageLocation,
    xStopBackstageLocation,
    xApplyPermissions,
    xStartDrEngine,
    xStopDrEngine,
    xIsIgnoringBatteryOptimizations,
    xRequestIgnoreBatteryOptimizations,
    xSetSelfStart,
    X_RESULT_TYPE,
    X_LOCATION_TYPE
} from "@/uni_modules/x-tencent-s"
  • template示例
<template>
    <scroll-view style="flex: 1;">
        <view class="cell">
            <text>经度:{{longitude}}</text>
            <text>纬度:{{latitude}}</text>
            <text>地址:{{address}}</text>
        </view>
        <view class="cell">
            <button class="cell-btn" @click="setSelfStart">设置自启动</button>
            <button class="cell-btn" @click="requestIgnoreBatteryOptimizations">申请白名单权限</button>
            <button class="cell-btn" @click="isIgnoringBatteryOptimizations">检查白名单权限</button>
            <button class="cell-btn" @click="applyPermissions">申请定位权限</button>
            <button class="cell-btn" @click="getLocation">开启前台持续定位</button>
            <button class="cell-btn" @click="stopLocation">关闭前台持续定位</button>
            <button class="cell-btn" @click="getOnceLocation">开启单次定位</button>
            <button class="cell-btn" @click="getSceneLocation">开启场景定位</button>
            <button class="cell-btn" @click="stopSceneLocation">关闭场景定位</button>
            <button class="cell-btn" @click="getBackstageLocation">开启后台持续定位</button>
            <button class="cell-btn" @click="stopBackstageLocation">关闭后台持续定位</button>
            <button class="cell-btn" @click="getBDSLocation">开启北斗定位</button>
            <button class="cell-btn" @click="stopBDSLocation">关闭北斗定位</button>
            <button class="cell-btn" @click="startDrEngine">开启步骑行惯导</button>
            <button class="cell-btn" @click="stopDrEngine">关闭步骑行惯导</button>
        </view>
    </scroll-view>
</template>
  • Vue2使用示例

<script>
    export default {
        onReady() {
            xSetUserAgreePrivacy()
            xSetKey("你的KEY")
        },
        methods: {
            // 申请定位权限
            applyPermissions() {
                xApplyPermissions((data: X_RESULT_TYPE)=>{
                    console.log(data)
                })
            },
            // 开启持续定位
            getLocation() {
                xGetLocation({interval: 3000} as X_LOCATION_TYPE,(data:X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 开启单次定位
            getOnceLocation() {
                xGetOnceLocation((data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 停止持续定位
            stopLocation() {
                xStopLocation((data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 开启场景定位
            getSceneLocation() {
                xGetSceneLocation("SIGN_IN_SCENE",(data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 停止场景定位
            stopSceneLocation() {
                xStopSceneLocation("SIGN_IN_SCENE",(data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 开启后台定位
            getBackstageLocation(){
                xGetBackstageLocation({interval: 3000} as X_LOCATION_TYPE,(data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 停止后台定位
            stopBackstageLocation(){
                xStopBackstageLocation((data: X_RESULT_TYPE) => {
                    console.log(data)
                })
            },
            // 开启北斗定位
            getBDSLocation(){},
            // 关闭北斗定位
            stopBDSLocation(){},
            // 开启步骑行惯导
            startDrEngine() {
                xStartDrEngine("",(result: X_RESULT_TYPE) => {
                    console.log(result)
                })
            },
            // 停止步骑行惯导
            stopDrEngine() {
                xStopDrEngine((result: X_RESULT_TYPE) => {
                    console.log(result)
                })
            },
            // 申请白名单权限
            requestIgnoreBatteryOptimizations() {
                xRequestIgnoreBatteryOptimizations((result: X_RESULT_TYPE) => {
                    console.log(result)
                })
            },
            // 判断是否在白名单
            isIgnoringBatteryOptimizations() {
                let isIgnore = xIsIgnoringBatteryOptimizations()
                if(isIgnore){
                    uni.showToast({title: "已申请白名单权限", icon: "none"})
                    return
                }
                uni.showToast({title: "未申请白名单权限", icon: "none"})
            },
            // 设置自启动
            setSelfStart() {
                xSetSelfStart((result: X_RESULT_TYPE) => {
                    console.log(result)
                })
            }
        }
    }
</script>
  • Vue3使用示例
<script lang="uts" setup> 
// 申请定位权限
const applyPermissions = () => {
    xApplyPermissions((data: X_RESULT_TYPE)=>{
        console.log(data)
    })
}
// 开启持续定位
const getLocation = () => {
    xGetLocation({interval: 3000} as X_LOCATION_TYPE,(data:X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 开启单次定位
const getOnceLocation = () => {
    xGetOnceLocation((data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 停止持续定位
const stopLocation = () => {
    xStopLocation((data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 开启场景定位
const getSceneLocation = () => {
    xGetSceneLocation("SIGN_IN_SCENE",(data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 停止场景定位
const stopSceneLocation = () => {
    xStopSceneLocation("SIGN_IN_SCENE",(data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 开启后台定位
const getBackstageLocation = () => {
    xGetBackstageLocation({interval: 3000} as X_LOCATION_TYPE,(data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 停止后台定位
const stopBackstageLocation = () => {
    xStopBackstageLocation((data: X_RESULT_TYPE) => {
        console.log(data)
    })
}
// 开启北斗定位
const getBDSLocation = () => {}
// 关闭北斗定位
const stopBDSLocation = () => {}
// 开启步骑行惯导
const startDrEngine = () => {
    xStartDrEngine("",(result: X_RESULT_TYPE) => {
        console.log(result)
    })
}
// 停止步骑行惯导
const stopDrEngine = () => {
    xStopDrEngine((result: X_RESULT_TYPE) => {
        console.log(result)
    })
}
// 申请白名单权限
const requestIgnoreBatteryOptimizations = () => {
    xRequestIgnoreBatteryOptimizations((result: X_RESULT_TYPE) => {
        console.log(result)
    })
}
// 判断是否在白名单
const isIgnoringBatteryOptimizations = () => {
    let isIgnore = xIsIgnoringBatteryOptimizations()
    if(isIgnore){
        uni.showToast({title: "已申请白名单权限", icon: "none"})
        return
    }
    uni.showToast({title: "未申请白名单权限", icon: "none"})
}
// 设置自启动
const setSelfStart = () => {
    xSetSelfStart((result: X_RESULT_TYPE) => {
        console.log(result)
    })
}

onReady(() => {
    xSetUserAgreePrivacy()
    xSetKey("你的KEY")
})
</script>
  • 如果定位权限存在并且xSetKey方法失效,出现KEY配置错误(解决方案)
    • 在你的根目录下创建AndroidManifest.xml文件
    • 将以下代码放在该文件,修改你的包名和你的KEY
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"
    package="你的包名">
    <application>
        <meta-data android:name="TencentMapSDK" android:value="你的KEY" />
        <service android:name="com.tencent.map.geolocation.s" android:foregroundServiceType="location" />
    </application>
</manifest>

方法

名称 参数 描述 平台兼容性
xApplyPermissions - 申请定位权限 Android/iOS
xSetKey (key: string) 设置腾讯地图KEY Android
xSetUserAgreePrivacy (callback:(data:X_RESULT_TYPE)=>void) 设置腾讯地图隐私合规 Android/iOS
xGetLocation (params:X_LOCATION_TYPE,callback:(data:X_RESULT_TYPE)=>void) 开启持续定位 Android/iOS
xStopLocation (callback:(data:X_RESULT_TYPE)=>void) 关闭持续定位 Android/iOS
xGetOnceLocation (callback:(data:X_RESULT_TYPE)=>void) 开启单次定位 Android/iOS
xGetSceneLocation (param: string,callback:(data: X_RESULT_TYPE) => void) 开启场景定位 Android
xStopSceneLocation (param: string,callback:(data: X_RESULT_TYPE) => void) 关闭场景定位 Android
xGetBackstageLocation (params:X_LOCATION_TYPE,callback:(data: X_RESULT_TYPE) => void) 开启后台定位 Android
xStopBackstageLocation (callback:(data:X_RESULT_TYPE)=>void) 关闭后台定位 Android
xStartDrEngine (params: string, callback: (result: X_RESULT_TYPE) => void) 开启步骑行惯导 Android
xStopDrEngine (callback: (result: X_RESULT_TYPE) => void) 关闭步骑行惯导 Android
xGetBDSLocation (params: X_LOCATION_TYPE, callback: (result: X_RESULT_TYPE) => void) 开启北斗定位(测试中) Android
xSetExtraKey (key: string) 设置北斗定位专属KEY Android
xDistanceBetween (aLatitude: number,aLongitude: number, bLatitude: number, bLongitude: number): number 两个点以经纬度的形式计算距离 Android
xIsSupportGps ():boolean 判断设备是否支持GPS定位 Android
xIsIgnoringBatteryOptimizations (): boolean 判断应用是否已经在白名单中 Android
xRequestIgnoreBatteryOptimizations (callback: (result: X_RESULT_TYPE) => void) 申请白名单权限 Android
xSetSelfStart (callback: (result: X_RESULT_TYPE) => void) 设置自启动权限 Android

X_LOCATION_TYPE 传入参数

名称 类型 必填 默认值 可选值 描述 平台兼容性
appName String xTencentS - 通知栏标题 Android
interval Number 1000 >1000 自定义定位间隔,时间单位为毫秒,不得小于1000毫秒 Android
allowGPS Boolean true false 是否允许使用GPS Android
allowDirection Boolean false true 是否需要获取传感器方向 Android
indoorLocationMode Boolean true false 是否需要开启室内定位 Android
locMode String HIGH_ACCURACY HIGH_ACCURACY 或 ONLY_NETWORK 或 ONLY_GPS 定位模式 Android
gpsFirst Boolean false true 设置是否GPS优先 Android
gpsTimeout Number 5000 >=1000 GPS超时时间,超过该时间仍然没有卫星定位结果将返回网络定位结果 Android
requestLevel String REQUEST_LEVEL_ADMIN_AREA REQUEST_LEVEL_GEO 或 REQUEST_LEVEL_NAME 或 REQUEST_LEVEL_ADMIN_AREA 或 REQUEST_LEVEL_POI 设置请求级别 Android
gnssSource String GNSS_SOURCE_GPS_FIRST GNSS_SOURCE_BEIDOU_FIRST 卫星定位来源(仅支持北斗定位) Android
geocode Boolean false true 是否需要返回逆地理编码 iOS

X_RESULT_TYPE 返回参数

名称 类型 描述
code Int 状态码
msg string 状态消息
data UTSJSONObject 定位数据

X_RESULT_TYPE 的 code和msg

code msg
-1 相关错误信息请查看控制台
0 注册位置监听器成功(代表正常)
1 设备缺少使用腾讯定位SDK需要的基本条件
2 配置的 Key 不正确或缺少定位权限
3 自动加载libtencentloc.so失败
4 未设置或未同意用户隐私

普通授权用户/试用用户 使用教程

  • 1.将以下代码,引入到你要使用的文件里面,确保该函数被页面调用或自调用。
import { 
    X_RESULT_TYPE,
    X_LOCATION_TYPE
} from "@/uni_modules/x-tencent-s"
  • 2.进行自定义基座打包,打包成功之后,可以直接引用以下代码进行使用
    • 打包自定义基座需要修改版本号和版本名称,防止打包不进去
  • 3.由于代码进行了加密,所以普通授权用户引入的函数可能会爆红,但不影响正常使用
import { 
    xSetKey,
    xSetUserAgreePrivacy,
    xGetLocation,
    xGetOnceLocation,
    xStopLocation,
    xGetSceneLocation,
    xStopSceneLocation,
    xGetBackstageLocation,
    xStopBackstageLocation,
    xApplyPermissions,
    xStartDrEngine,
    xStopDrEngine,
    xIsIgnoringBatteryOptimizations,
    xRequestIgnoreBatteryOptimizations,
    xSetSelfStart,
    X_RESULT_TYPE,
    X_LOCATION_TYPE
} from "@/uni_modules/x-tencent-s"

源码授权用户 使用教程

  • 1.将以下代码,引入到你要使用的文件里面,确保该函数被页面调用或自调用。
  • 2.进行自定义基座打包,打包成功之后,可以直接引用以下代码进行使用
    • 打包自定义基座需要修改版本号和版本名称,防止打包不进去
import { 
    xSetKey,
    xSetUserAgreePrivacy,
    xGetLocation,
    xGetOnceLocation,
    xStopLocation,
    xGetSceneLocation,
    xStopSceneLocation,
    xGetBackstageLocation,
    xStopBackstageLocation,
    xApplyPermissions,
    xStartDrEngine,
    xStopDrEngine,
    xIsIgnoringBatteryOptimizations,
    xRequestIgnoreBatteryOptimizations,
    xSetSelfStart,
    X_RESULT_TYPE,
    X_LOCATION_TYPE
} from "@/uni_modules/x-tencent-s"

iOS修改腾讯定位密钥Key指南

  • 找到 uni_modules/x-tencent-s/utssdk/app-ios/info.plist 文件
  • 你的KEY修改为你的KEY
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>TencentLBSAPIKey</key>
        <string>你的KEY</string>
        <key>UIBackgroundModes</key>
        <array>
            <string>location</string>
        </array>
        <key>NSLocationAlwaysUsageDescription</key>
        <string>用于提供精确的定位</string>
        <key>NSLocationWhenInUseUsageDescription</key>
        <string>用于提供精确的定位</string>
    </dict>
</plist>

X插件系列

x-base-s【基础插件】安卓好用的基础工具

x-sms【短信插件】为X系列插件打造完美轮子

x-tencent-u【腾讯地图】

x-tencent-s【腾讯定位】保活和持久,保姆和小白式的完美解决方案

x-gaode-s【高德定位】保姆和小白式完美解决方案

x-icon-u【图标组件】

x-short-video-u是一个高性能,高度配置的短视频组件

x-im-sdk 为即时通讯量身打造, 适配Android,iOS,Web

隐私、权限声明

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

权限列表详细可参考:https://lbs.qq.com/mobile/androidLocationSDK/androidGeoGuide/androidGeoCreat

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

插件使用的 腾讯定位 SDK会采集数据,详细可参考:https://privacy.qq.com/document/preview/dbd484ce652c486cb6d7e43ef12cefb0

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

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