更新记录

1.1.0（2026-09-15）

  • 保留全部旧 API、参数及 locationHandler 回调结构，已有项目可直接升级
  • 三端定位结果新增水平精度、垂直精度及定位来源字段
  • 优化 Android 10/11+ 后台定位权限、Android 13 通知权限和前台服务启动流程
  • 优化 Android 保活服务
  • 优化 iOS 前后台授权策略，连续定位改为系统持续更新加最小回调间隔
  • 优化 HarmonyOS 后台权限检查，并改用高德 SDK 原生连续定位
  • 修复 Android 已授予部分定位权限时重复申请可能导致连续定位、保活定位无回调的问题
  • 补齐 Android 权限流程、SDK 初始化和前台服务启动异常的失败回调
  • 修复 iOS 已有“使用 App 期间”权限时，启动保活定位不会主动升级申请“始终允许”的问题

1.0.3（2026-03-31）

  • 优化iOS连续定位

1.0.2（2026-01-22）

  • 优化
查看更多

平台兼容性

uni-app(4.65)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ × × √ √ √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
× × × × × × × × × - × ×

uni-app x(4.65)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ √ √ ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

高德定位、连续定位、后台定位、保活定位

开发文档

UTS 语法 UTS API插件 UTS uni-app兼容模式组件 UTS 标准模式组件 Hello UTS

特别提醒

  • 购买本插件前，请先试用、并充分自测后再购买，购买后无法退款；
  • 如有使用上的疑问、bug，可以进交流群联系作者；
  • 结合文档和示例代码集成使用；
  • 试用必须先打基座、试用必须先打基座、试用必须先打基座重要事情说三遍；
  • 本插件支持uniapp/uniapp-x项目，支持vue2/vue3,支持iOS、Android、HarmonyOS
  • Android手机型号太多，各品牌对手机的限制不尽相同，需要保活而进行的设置也不一样。随着Android系统的更新迭代，保活的难度也在不断加大。最有效的保活方式还是联系厂家添加白名单以实现进程保活。
  • uniapp使用本插件保活、后台定位功能iOS需在manifest.json/其他设置中后台运行能力配置location
  • Android 无需为本插件单独手动设置 targetSdkVersion；插件会读取宿主应用的实际目标版本做兼容判断。发布应用时仍需按目标应用市场要求配置。
  • iOS/Android需更换appKey,更换位置见下面集成步骤

插件功能介绍

  1. 定位、连续定位、后台定位（Android需要使用保活定位）
  2. 保活定位

1.1.0 兼容性说明

  • 原有 onceLocation、updateLocation、keepLive、stopUpdateLocation、stopKeepLive、setLocationInterval 和 openAppSettings 均保留，参数与 locationHandler 的扁平回调结构不变。
  • 新增的 API 和字段都是可选能力；老用户升级插件后不需要修改业务代码。
  • 新增语义化别名：startUpdatingLocation、stopUpdatingLocation、keepLiveLocation、offKeepLiveLocation。
  • 定位失败（含缺少权限、HarmonyOS 未初始化 SDK）现在会通过回调返回，不再只写日志或静默结束。

可选基础配置（新增）

定位前可统一配置；不调用时继续使用旧版默认值。

GDLocation.configureBasicConfiguration({
    onceLocationTimeout: 5000,
    locationInterval: 10000,
    notificationTitle: "App后台定位",
    notificationContentText: "正在后台定位"
})

新版结构化回调也可按需使用，旧 locationHandler 仍然有效：

GDLocation.startUpdatingLocation({
    enableBackgroundLocation: false,
    locationResultBackcall: (res) => {
        if (res.code == 200) {
            console.log(res.location)
        } else {
            console.log(res.mes)
        }
    }
})

iOS 的 locationInterval 表示最小回调间隔。实际回调依赖系统产生新的有效位置，可能受设备静止、信号、息屏和系统节能策略影响而变长。

iOS 启动保活定位时会申请“始终允许”。系统可能采用两阶段授权，第二次升级提示的展示时机由 iOS 决定，不保证刚退到后台就立即弹出；若用户曾拒绝升级，需要到系统设置中手动修改。

Android 11 及以上的“始终允许”后台定位权限需用户在系统应用设置中开启。权限不足时回调会返回说明，可调用 openAppSettings() 跳转设置页。

仅需前台连续定位时请将 isAllow / enableBackgroundLocation 设为 false（或不传）；keepLive 属于后台保活定位，必须具备后台定位权限。

Android后台采集或保活设置

  1. 通知管理允许通知，允许自启动；

  2. 耗电保护允许后台运行；

  3. 电池设置中关闭智能耗电保护、省电模式、应用速冻等。

特别注意HarmonyOS后台定位需配置后台功能。配置步骤如下：

  1. 点击运行->运行到手机/模拟器->运行到鸿蒙
  2. 运行成功会在项目根目录下生成unpackage文件夹，找到unpackage/dist/dev/app-harmony/entry,将该文件夹复制到项目根目录下的harmony-configs文件夹下
  3. 在harmony-configs/entry/src/main/module.json5文件中增加设置如一下代码
在harmony-configs/entry/src/main/module.json5文件中增加设置
{
    "module": {
        "abilities": [
            {
                ...
                "backgroundModes": [
                    "location"
                ],
                "continuable": true
            }
        }
    }
}

集成插件步骤

  1. 点击试用/购买选择需要集成项目
  2. 调用插件在需要使用的地方导入 import * as GDLocation from '../../uni_modules/yt-amaplocation' 可参考下面的实例代码
  3. Android配置高德key，事先先申请的key，替换：uni_modules/yt-amaplocation/utssdk/app-android/AndroidManifest.xml文件下<meta-data android:name="com.amap.api.v2.apikey" android:value="自己的key" />。
  4. iOS配置高德key替换：uni_modules/yt-amaplocation/utssdk/app-ios/info.plist中GDAPIKey
  5. 配置完iOS/Android需打自定义基座测试

api说明

HarmonyOS需先初始化定位SDK：

//参数为高德开发平台申请的AppKey
GDLocation.initAmapLocal("e982b69*****1779ddd80ee52")

单次定位：GDLocation.onceLocation(options:LocationOptions,locationHandler(location=>{}))

GDLocation.onceLocation({
    locationMode: 'HundredMeters',
    reGeocode: true,
    locationHandler: (location) => {
        if (location.code == 200) {
            console.log(location)
        }
    }
} as GDLocation.LocationOptions)

连续定位：GDLocation.updateLocation(options:LocationOptions,locationHandler(location=>{}))

GDLocation.updateLocation({
        locationMode: 'HundredMeters',
        anLocationMode: "Hight_Accuracy",
        reGeocode: true,
        isAllow: true,
        locationInterval: 10000,
        locationHandler: (location) => {
            if (location.code == 200) {
                console.log(location)
            }
        }
    } as GDLocation.LocationOptions)
    ///停止连续定位
GDLocation.stopUpdateLocation()

保活定位：GDLocation.keepLive(options:LocationOptions,locationHandler(location=>{}))

GDLocation.keepLive({
                    locationMode: 'HundredMeters',
                    reGeocode: true,
                    isAllow: true,
                    locationInterval: 5000,
                    anLocationMode: "Battery_Saving",
                    locationHandler: (location) => {
                        if (location.code == 200) {
                            console.log(location)
                        }
                    }
} as GDLocation.LocationOptions)

///停止保活定位
GDLocation.stopKeepLive();

打开App对应设置页面 

GDLocation.openAppSettings()

参数说明：LocationOptions 定位参数

参数 类型 说明
locationMode String iOS端定位精度'BestForNavigation' 、 'AccuracyBest' 、 'NearestTenMeters' 、 'HundredMeters'、'Kilometer'
anLocationMode String android端定位精度 Hight_Accuracy 、 Battery_Saving 、Device_Sensors
reGeocode bool 是否需要地址默认true
locationInterval int 连续定位间隔，单位毫秒默认10*1000
maxAccuracy number HarmonyOS设置期望的最大定位精度（单位为米），数值越小表示要求的精度越高 -- 高德定位 SDK 是基于鸿蒙系统定位能力封装的，最终的定位精度还受设备硬件、环境（如 GPS 信号强度）等因素影响,默认5米
distanceFilter number 设定定位的最小更新距离。单位米，默认为 kCLDistanceFilterNone，表示只要检测到设备位置发生变化就会更新位置信息。---仅iOS有效，设置了该属性则locationInterval无效
isAllow bool 是否后台定位仅连续定位有效，保活定位默认开启后台定位
notificationTitle string 仅Android有效设置后台定位通知标题
notificationContentText string 仅Android有效设置后台定位通知内容
locationHandler function 定位回调
onceLocationTimeout number 单次定位超时时间，单位毫秒，默认5000（HarmonyOS旧版默认10000）
enableBackgroundLocation bool isAllow 的语义化别名；两者均未设置时默认false
locationResultBackcall function 新版结构化回调，返回 { code, mes, location }；可与旧回调并存

locationMode：补充说明，iOS端定位精度设置BestForNavigation：导航级精度，±1米内

参数 说明
BestForNavigation 导航级精度，±1米内
AccuracyBest 设备支持的最佳精度，±10米内
NearestTenMeters ±10米 默认
HundredMeters ±100米
Kilometer ±1公里

anLocationMode：Android端定位精度

参数 说明
Hight_Accuracy 高精度模式
Battery_Saving 低功耗模式
Device_Sensors 仅设备模式,不支持室内环境的定位

定位回调说明

定位回调返回的数据类型location:LocationInfo。

字段 类型 说明
code int 状态码 200成功
mes string 定位说明
latitude number 纬度
longitude number 经度
speed number 速度
altitude number 海拔
accuracy number 水平精度，单位米
verticalAccuracy number 垂直精度，平台支持时返回
locationType string 统一定位来源，如gps、network、offline、last_fix、unknown
provider string 平台原始定位提供者
sourceType number 平台原始定位类型值，平台支持时返回
address AddressInfo 地址信息，详情见下表

AddressInfo说明：

字段 类型 说明
formattedAddress string 格式化地址
country string 国家
province string 省/直辖市
city string 市
district string 区
citycode string 城市编码
adcode string 区域编码
street string 街道名称
number string 门牌号
poiName string 兴趣点名称
aoiName string 所属兴趣点名称

uniapp-x完整示例，uniapp项目的示例demo可点击右侧导入示例项目

<template>
    <view>
        <view class="text-area">
            <text class="title" @click="oneceLocationAction">单次定位</text>
            <text class="title" @click="updateLocation">连续定位</text>
            <text class="title" @click="keepLive">保活定位</text>
            <text class="title" @click="stopUpdateLocation">取消连续定位</text>
            <text class="title" @click="stopKeepLive">取消保活定位</text>
            <text class="title" @click="openAppSettings">打开设置页面</text>
        </view>
    </view>
</template>

<script>
    import * as GDLocation from '../../uni_modules/yt-amaplocation'
    export default {
        data() {
            return {
                title: 'Hello'
            }
        },
        onLoad() {
            // #ifdef APP-HARMONY
            //获取应用appid用于申请高德定位、地图的appkey
            let appId = GDLocation.getHarmonyOSAppID()
            console.log(`appId:${appId}`)
            GDLocation.initAmapLocal("高德开放平台申请的appkey")
            // #endif
        },
        methods: {
            oneceLocationAction() {
                GDLocation.onceLocation({
                    locationMode: 'HundredMeters',
                    reGeocode: true,
                    maxAccuracy: 5,
                    anLocationMode: "Hight_Accuracy",
                    locationHandler: (location) => {
                        if (location.code == 200) {
                            console.log(location)
                        }
                    }
                } as GDLocation.LocationOptions)
            },
            //连续定位
            updateLocation() {
                GDLocation.updateLocation({
                    locationMode: 'HundredMeters',
                    anLocationMode: "Hight_Accuracy",
                    maxAccuracy: 5,
                    reGeocode: true,
                    isAllow: true,
                    locationInterval: 10000,
                    locationHandler: (location) => {
                        if (location.code == 200) {
                            console.log(location)
                        }
                    }
                } as GDLocation.LocationOptions)
            },
            //后台保活定位
            keepLive() {
                GDLocation.keepLive({
                    locationMode: 'HundredMeters',
                    reGeocode: true,
                    isAllow: true,
                    locationInterval: 5000,
                    maxAccuracy: 5,
                    anLocationMode: "Battery_Saving",
                    locationHandler: (location) => {
                        if (location.code == 200) {
                            console.log(location)
                        }
                    }
                } as GDLocation.LocationOptions)
            },
            //取消连续定位
            stopUpdateLocation() {
                GDLocation.stopUpdateLocation()
            },
            //停止保活
            stopKeepLive() {
                GDLocation.stopKeepLive()
            },
            //跳设置页面
            openAppSettings() {
                GDLocation.openAppSettings()
            },
        }
    }
</script>

<style>
    .title {
        font-size: 18px;
        color: #8f8f94;
        text-align: center;
        margin-top: 45rpx;
    }

    .text-area {
        display: flex;
        flex-direction: column;
        align-items: center;
        width: 750rpx;
    }
</style>

隐私、权限声明

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

位置权限，后台定位权限

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

插件会采集用户位置信息，插件使用高德地图定位SDK，参考其官方网站https://lbs.amap.com 和个人信息保护声明 https://lbs.amap.com/api/compliance-center/ability/data-security

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

无

评论列表 撰写评论 向官方投诉
加载更多...