快速开始

本文档帮助您在完成工程配置后，用最少的代码快速跑通定位功能。

如果尚未完成 Key 申请、Gradle 依赖、权限配置等工程准备工作，请先参考 创建工程。

隐私合规（必须）

在调用 SDK 任何接口前，必须先完成隐私合规设置，否则 SDK 将无法正常工作：

TencentLocationManager.setUserAgreePrivacy(true);

详见 隐私合规接口。

连续定位

// 1. 获取定位管理器实例（建议全局复用，避免反复创建）
TencentLocationManager manager = TencentLocationManager.getInstance(context);

// 2. 配置定位请求
TencentLocationRequest request = TencentLocationRequest.create();
request.setInterval(5000);        // 定位间隔 5 秒
request.setAllowGPS(true);        // 允许使用 GPS
request.setRequestLevel(TencentLocationRequest.REQUEST_LEVEL_NAME); // 获取经纬度+名称+地址

// 3. 创建定位监听器
TencentLocationListener listener = new TencentLocationListener() {
    @Override
    public void onLocationChanged(TencentLocation location, int error, String reason) {
        if (error == TencentLocation.ERROR_OK) {
            double latitude = location.getLatitude();   // 纬度
            double longitude = location.getLongitude();  // 经度
            float accuracy = location.getAccuracy();     // 精度（米）
            String name = location.getName();            // 位置名称
            String address = location.getAddress();      // 地址信息
        } else {
            // 定位失败，根据 error 错误码排查原因
        }
    }

    @Override
    public void onStatusUpdate(String name, int status, String desc) {
        // GPS、Wi-Fi、Cell 等定位源状态变化回调
    }
};

// 4. 启动定位（在后台线程处理回调）
HandlerThread handlerThread = new HandlerThread("LocationThread");
handlerThread.start();
int result = manager.requestLocationUpdates(request, listener, handlerThread.getLooper());

// 5. 停止定位（不再需要时务必调用，避免不必要的电量消耗）
manager.removeUpdates(listener);

单次定位

TencentLocationManager manager = TencentLocationManager.getInstance(context);

HandlerThread handlerThread = new HandlerThread("LocationThread");
handlerThread.start();

manager.requestSingleFreshLocation(new TencentLocationListener() {
    @Override
    public void onLocationChanged(TencentLocation location, int error, String reason) {
        if (error == TencentLocation.ERROR_OK) {
            double latitude = location.getLatitude();
            double longitude = location.getLongitude();
            String address = location.getAddress();
        }
    }

    @Override
    public void onStatusUpdate(String name, int status, String desc) {}
}, handlerThread.getLooper());

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

请求级别说明

定位请求可通过 setRequestLevel 设置不同的信息详细程度：

级别越高，返回的信息越详细。

回调错误码

下一步

• 连续定位 — 详细的连续定位参数配置
• 单次定位 — 单次定位使用说明
• 场景定位 — 针对不同场景的定位策略
• API 参考手册 — 完整接口文档
• 常见问题 — FAQ