连续定位

连续定位是指发起一次定位请求后，SDK 按照指定的周期，持续返回定位结果的定位方式，是最常用的定位方式。

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

---

开发步骤

1. 获取 TencentLocationManager 实例

首次获取实例会进行初始化操作，可能存在耗时，建议尽早初始化。TencentLocationManager 为单例模式，推荐使用 ApplicationContext 以避免内存泄漏。

mLocationManager = TencentLocationManager.getInstance(this);

2. 创建位置监听器

实现 TencentLocationListener 接口，通过回调接收定位结果和设备状态变化。

public class MyActivity extends Activity implements 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 区分
    }
}

TencentLocation 中所有的属性和方法详见 API 参考。

状态码含义详见 状态码对照表。

3. 构造 TencentLocationRequest

TencentLocationRequest request = TencentLocationRequest.create();

默认配置如下：

参数	默认值
定位周期	5 秒
Request Level	REQUEST_LEVEL_ADMIN_AREA
允许 GPS	true
获取传感器方向	false
室内定位	false
定位模式	高精度模式（HIGH_ACCURACY_MODE）
GPS 优先	false
GPS 优先等待时间	5 秒
首次定位超时	15 秒
首个定位点等待地址信息	false

常用配置

(1) 设置定位间隔

单位为毫秒，不得小于 1000 毫秒。

request.setInterval(10000);

(2) 设置请求级别

根据需要获取的位置信息详细程度选择，详见 RequestLevel 说明。

request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_ADMIN_AREA);

(3) 设置是否允许使用 GPS

建议开启，在室外场景可显著提升定位精度。

request.setAllowGPS(true);

(4) 设置是否获取传感器方向

设置为 true 后，可通过 TencentLocation.getDirection() 获取当前设备方向。

getBearing() 返回的是 GPS 方向信息，无信号时无法获取。方向功能可能增加耗电量。

request.setAllowDirection(true);

(5) 设置是否开启室内定位

设置为 true 后，SDK 将启用室内定位策略。如果应用定位场景多在室内，建议开启以提升准确率。

request.setIndoorLocationMode(true);

(6) 设置定位模式

模式	常量	说明
高精度模式	HIGH_ACCURACY_MODE	同时使用网络定位和卫星定位，优先返回精度高的结果（默认）
仅网络模式	ONLY_NETWORK_MODE	不启动 GPS，仅使用网络定位，降低功耗但精度下降
仅 GPS 模式	ONLY_GPS_MODE	仅返回 GPS 结果，室外精度约 3~10 米，首次定位较慢且耗电。 若 8 秒超时内无 GPS 结果，返回网络定位结果

int locMode = TencentLocationRequest.HIGH_ACCURACY_MODE;
request.setLocMode(locMode);

(7) 设置 GPS 优先

设置后首次定位将等待卫星定位结果，仅在高精度模式下有效。

request.setGpsFirst(true);
request.setGpsTimeOut(5 * 1000); // GPS 超时时间，单位毫秒

(8) 设置首个定位点等待地址信息

request.setFirstLocationNeedAddress(true);
request.setLocFirstTimeOut(10); // 超时时间，单位秒，默认 15 秒

4. 发起连续定位请求

mLocationManager.requestLocationUpdates(request, this);

也可指定回调线程：

mLocationManager.requestLocationUpdates(request, this, Looper.getMainLooper());

错误码含义详见 错误码对照表。

5. 停止定位

mLocationManager.removeUpdates(this);

注意事项

• 定位不区分线程，建议在子线程调用，以减少 ANR 风险。
• 不再需要定位时务必调用 removeUpdates 停止定位，避免不必要的电量消耗。
• TencentLocationManager 为单例，推荐使用 ApplicationContext 初始化。