单次定位

单次定位是指发起一次定位请求后，仅返回一次定位结果，无需手动停止定位。

单次定位一般只会返回网络定位结果，因为手机 GPS 模块获取定位信息通常晚于网络定位。

自定位 SDK v7.2.8 起，需通过 TencentLocationManager.setDeviceID 上传设备唯一标识，用于定位问题排查。Device ID 只能包含数字、字母、下划线。

版本差异

开发步骤

1. 获取 TencentLocationManager 实例

mLocationManager = TencentLocationManager.getInstance(this);

2. 创建位置监听器

TencentLocationListener singleListener = new TencentLocationListener() {

    @Override
    public void onLocationChanged(TencentLocation location, int error, String reason) {
        // location - 新的位置，可能来自缓存；定位失败时 location 无效或为 null
        // error    - 错误码，仅当 TencentLocation.ERROR_OK 时表示定位成功
        // reason   - 错误描述
    }

    @Override
    public void onStatusUpdate(String name, int status, String desc) {
        // name   - 设备名：GPS、WIFI、CELL
        // status - 状态码：STATUS_ENABLED、STATUS_DISABLED、STATUS_UNKNOWN 等
        // desc   - 状态描述
        // 注意：使用 status 前，请先按 name 区分
    }
};

建议连续定位和单次定位使用不同的 Listener，避免回调混淆。

3. 发起单次定位

TencentLocationRequest request = TencentLocationRequest.create();
request.setGpsFirst(true); // 可选：优先等待 GPS 结果

mLocationManager.requestSingleFreshLocation(request, singleListener, Looper.getMainLooper());

单次定位完成后自动停止，无需手动调用 removeUpdates。

默认配置

注意事项

• 单次定位无需手动停止，SDK 返回结果后会自动结束。
• 建议连续定位和单次定位使用不同的 TencentLocationListener 实例。

相关链接

• RequestLevel 说明
• 错误码对照表
• 状态码对照表
• API 参考手册