更新记录

1.0.0（2026-07-11）

• 首发：Android、iOS、HarmonyOS、Web、微信小程序五端统一系统定位 API。
• 公开 API 采用 get / request / watch / initLocation 命名（如 getLastLocation、requestPermission、watchLocation、initLocation）。
• 支持权限申请、后台定位、缓存读取、对象/元组监听与停止监听。
• HarmonyOS 原生能力独立到 app-harmony/Bridge.ets，index.uts 仅保留统一 API 包装。
• 提供 uni-app / uni-app x 示例页面。

平台兼容性

uni-app(5.06)

uni-app x(5.06)

其他

xview-location

面向 uni-app / uni-app x 的系统定位 UTS 插件。Android、iOS、HarmonyOS、Web、微信小程序五端 API 与返回结构一致，不依赖第三方定位 SDK。

能力概览

• 权限申请、后台定位、系统设置跳转
• 缓存读取、单次定位、持续监听（对象 / 元组双回调）
• WGS84 / GCJ-02 / BD-09 坐标转换
• 可选高德 Web Service 逆地理编码
• Android 息屏持续定位（前台服务 + 原生队列回灌）

典型流程

initLocation() → 检查/申请权限 → watchLocation() 或 getLastLocation() → stopLocationWatch()

快速开始

import {
    requestPermission,
    checkPermission,
    initLocation,
    watchLocation,
    stopLocationWatch,
    type XviewLocationReading,
    type XviewLocationOptions
} from '@/uni_modules/xview-location'

let permissionName = 'location'
// #ifdef APP-ANDROID
permissionName = 'android.permission.ACCESS_FINE_LOCATION'
// #endif
// #ifdef APP-IOS
permissionName = 'ios.location.whenInUse'
// #endif
// #ifdef APP-HARMONY
permissionName = 'ohos.permission.LOCATION'
// #endif
// #ifdef MP-WEIXIN
permissionName = 'scope.userLocation'
// #endif

initLocation()

if (checkPermission(permissionName) == false) {
    requestPermission(permissionName, (granted : boolean) => {
        if (granted == false) {
            return
        }
        startLocationWatch()
    })
} else {
    startLocationWatch()
}

function startLocationWatch() {
    const options : XviewLocationOptions = {
        intervalMs : 1000,
        distanceMeters : 0,
        backgroundMode : false,
        emitCachedFirst : true,
        notificationTitle : '定位服务运行中',
        notificationText : '应用正在持续获取位置信息',
        notificationIconName : null
    }
    watchLocation(options, (reading : XviewLocationReading) => {
        if (reading.stage === 'error') {
            console.log(reading.message)
            return
        }
        console.log(reading.stage, reading.latitude, reading.longitude)
    })
}

// 页面卸载时停止监听
stopLocationWatch(true)

对象回调适合页面展示；需要更轻量的签名时，使用 watchLocationTuple / getLastLocationTuple，回调参数为 (stage, latitude, longitude, speed, altitude, heading)，其中 stage：0 缓存、1 实时、2 错误。

典型场景

缓存读取

不启动监听，直接读取最近一次定位结果：

getLastLocation((reading : XviewLocationReading) => {
    console.log(reading.stage, reading.latitude, reading.longitude)
})

单次定位

intervalMs 传 0 表示单次定位；建议 emitCachedFirst: false，每次点击重新调用 watchLocation / watchLocationTuple：

const options : XviewLocationOptions = {
    intervalMs : 0,
    distanceMeters : 0,
    backgroundMode : false,
    emitCachedFirst : false,
    notificationTitle : null,
    notificationText : null,
    notificationIconName : null
}

watchLocation(options, (reading : XviewLocationReading) => {
    if (reading.stage === 'live') {
        console.log(reading.latitude, reading.longitude)
    }
})

再次调用 watchLocation / watchLocationTuple 会先停止上一次监听。

持续监听

按间隔持续回调，emitCachedFirst: true 时启动后会先返回缓存定位：

watchLocation({
    intervalMs : 5000,
    distanceMeters : 0,
    backgroundMode : false,
    emitCachedFirst : true
}, (reading : XviewLocationReading) => {
    // cached / live / error
})

intervalMs 是系统定位请求的最小间隔，不是固定周期定时器；卫星信号、静止状态、省电策略可能导致实际间隔变长。

息屏持续定位

息屏定位仍使用 watchLocation()，关键参数为 backgroundMode: true。需先申请后台定位；Android 还需通知权限（API 33+）以展示前台服务通知。

import { readPendingLocations, requestBackgroundMode } from '@/uni_modules/xview-location'

const options : XviewLocationOptions = {
    intervalMs : 5000,
    distanceMeters : 0,
    backgroundMode : true,
    emitCachedFirst : false,
    notificationTitle : 'Xview Location 息屏定位',
    notificationText : '正在持续获取位置信息',
    notificationIconName : null
}

requestBackgroundMode((granted : boolean) => {
    if (granted == false) {
        return
    }
    watchLocation(options, (reading : XviewLocationReading) => {
        console.log(reading.stage, reading.latitude, reading.longitude)
    })
})

坐标转换

定位结果默认 WGS84。高德、腾讯等国内地图通常用 GCJ-02，百度地图用 BD-09：

const gcj02 = convertCoordinate(39.908823, 116.397470, 'wgs84', 'gcj02')
console.log(gcj02.latitude, gcj02.longitude)

convertCoordinates 支持批量转换；isGcj02OffsetRegion 判断是否在常用 GCJ-02 偏移算法范围内。算法存在米级误差，不适用于测绘；范围外 WGS84 与 GCJ-02 转换会原样返回。

逆地理编码

reverseGeocode 使用高德 Web Service，传入 WGS84 或 BD-09 时会先转为 GCJ-02：

reverseGeocode({
    latitude : 39.908823,
    longitude : 116.397470,
    coordinateType : 'wgs84',
    apiKey : '你的高德 Web Service Key',
    radiusMeters : 1000
}, (result : XviewLocationReverseGeocodeResult) => {
    if (result.success && result.address != null) {
        console.log(result.address!.formatted)
    }
})

• Key 由业务方申请和保管，插件只用于本次请求，不会持久化。
• 请求发送至 https://restapi.amap.com；Web 需处理跨域与 Key 安全配置；微信小程序需将该域名加入合法 request 域名。
• 不建议在每次 watchLocation 回调中直接请求，应在业务层按距离或时间节流。

公开 API

初始化与运行时

XviewLocationRuntimeProfile 主要字段：

权限与系统设置

各平台 permissionName：

读取与监听

坐标转换

逆地理编码

类型说明

XviewLocationOptions

XviewLocationReading

XviewLocationAndroidDiagnostics

错误码

stage === 'error' 或元组 stage === 2 时，message 含对应说明：

注意事项

1. 页面卸载时调用 stopLocationWatch(true)，避免后台监听泄漏。
2. Android 后台定位依赖前台服务；不会申请 REQUEST_IGNORE_BATTERY_OPTIMIZATIONS，若被系统终止请检查厂商白名单。
3. 定位数据默认仅在设备本地处理；主动调用 reverseGeocode 时会将 GCJ-02 坐标发送至高德 Web Service。
4. 插件所需 Android 权限见 package.json 中 dcloudext.declaration.permissions。