常见A3L Location API

本页介绍您可以在应用程序中使用的常见A3L Location API，以支持集成A3L Location SDK中描述的A3L Location的主要函数。

检查设置
获取位置可用性
请求持续位置更新
停止位置更新
相关资源

检查设置

要获取位置设置的当前状态，可调用A3LLocationSettingsResponse.getLocationSettingsStates()方法。

若要确保用户设备的系统设置处于允许位置服务成功执行位置请求的状态，请使用checkLocationSettings() API。如果API确定设备上未启用所需的设置，则可以选择向用户显示一个对话框，指导用户启用设置。

在检查系统设置之前，必须创建一个A3LLocationSettingsRequest.Builder对象，该对象包括应用程序使用的A3LLocationRequest对象。下面的代码演示了创建具有两个位置请求的A3LLocationSettingsRequest.Builder对象的示例。

A3LLocationSettingsRequest.Builder builder = new A3LLocationSettingsRequest.Builder()
        .addLocationRequest(mLocationRequestHighAccuracy)
        .addLocationRequest(mLocationRequestBalancedPowerAccuracy);

如果您的应用使用低功耗蓝牙(BLE)进行定位，如以下代码所示使用setNeedBle()方法构建A3LLocationSettingsRequest.Builder对象。

builder.setNeedBle(true);

要在应用中检查系统设置，可如以下示例所示构建A3LLocationSettingsRequest对象，并将其传递给A3LSettingsClient类的checkLocationSettings()方法。

Task<A3LLocationSettingsResponse> result =
        A3LLocationServices.getSettingsClient(this).checkLocationSettings(builder.build());

向Task添加一个完成时侦听器来处理结果。如果结果引发异常，您的应用可以有条件地检查状态代码，以确定是否可以解决问题。如果状态代码为RESOLUTION_REQUIRED，您可以向用户显示对话框以请求他们运行所需设置。为此，调用ResolvableApiException.startResolutionForResult()，如以下示例中所示。

result.addOnCompleteListener(new OnCompleteListener<A3LLocationSettingsResponse>() {
    @Override
    public void onComplete(Task<A3LLocationSettingsResponse> task) {
        try {
            A3LLocationSettingsResponse response = task.getResult(ApiException.class);
            //系统设置可允许位置服务。
            ...
        } catch (ApiException exception) {
            switch (exception.getStatusCode()) {
                case A3LLocationSettingsStatusCodes.RESOLUTION_REQUIRED:
                    //系统设置未处于允许位置服务的状态，但是
                    //可以解决该问题。
                    try {
                        //转换为可解决的异常。
                        ResolvableApiException resolvable = (ResolvableApiException) exception;
                        //向用户显示对话框以进行解决 - 在onActivityResult()中验证结果。
                        resolvable.startResolutionForResult(
                                OuterClass.this,
                                REQUEST_CHECK_SETTINGS);
                    } catch (SendIntentException e) {
                        //忽略
                    } catch (ClassCastException e) {
                        //忽略
                    }
                    break;
                case A3LLocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
                    //系统设置未处于允许位置服务的状态，并且
                    //无法解决该问题。
                    ...
                    break;
            }
        }
    }
});

有关状态代码的更多信息，请参阅A3LLocationSettingsStatusCodes的API文档。

以下示例说明如何在onActivityResult()方法中验证startResolutionForResult()的结果。

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode) {
        case REQUEST_CHECK_SETTINGS:
            switch (resultCode) {
                case Activity.RESULT_OK:
                    //用户更改了所需设置
                   ...
                    break;
                case Activity.RESULT_CANCELED:
                    //用户未更改所需设置
                    ...
                    break;
                default:
                    break;
            }
            break;
    }
}

获取位置可用性

要确定位置数据是否可用，可使用getLocationAvailability()方法。成功的Task结果返回A3LLocationAvailability对象。要获取指示可以检索位置数据的可能性的布尔值，可使用isLocationAvailable()方法。响应为true时不能保证位置可用，而是表示位置数据可能可用。与之相似，响应为false时不能确定证位置不可用，而是表示位置数据可能不可用。以下代码演示了如何获取位置可用性的示例。

// getLocationAvailability
Task<A3LLocationAvailability> a3LLocationAvailability = a3LLocationProviderClient.getLocationAvailability();
a3LLocationAvailability.addOnCompleteListener(new OnCompleteListener<A3LLocationAvailability>() {
    @Override
    public void onComplete(@NonNull Task<A3LLocationAvailability> task) {
        //完成时要执行的代码
        // ...
        if(task.isSuccessful()) {
            //使用isLocationAvailable()检查位置API是否可以检索位置。
            //结果并不能保证API可以获取一个位置，而是可能会获取一个位置。
            Boolean locationAvailable = task.getResult().isLocationAvailable();
        }
    }
});

对于没有Google Play服务的Android设备，getLocationAvailability()方法仅验证位置是已启用还是已禁用。

请求持续位置更新

requestLocationUpdates()方法允许您的应用反复获取位置更新。如果您的应用随时间推移跟踪用户位置，则该API可处理该用例。requestLocationUpdates()方法使用A3LLocationRequest、A3LLocationListener以及循环器。API在提供的循环器上将结果传递给侦听器。如果您的应用发出位置更新请求，并且您的应用先前使用同一侦听器发出位置更新请求，则新的请求会取代之前的请求。以下代码演示了如何请求位置更新的示例。

//请求位置更新
A3LLocationListener a3lLocationListener = new A3LLocationListener() {
    @Override
    public void onLocationChanged(@NonNull Location location) {
        //一旦收到位置时要执行的自定义代码。

    }
};
//值1000L为示例。可对A3LLocationRequest intervalMillis使用任何值，或使用
//其他生成器构造函数。有关其他选项，请参阅Javadoc API参考。
A3LLocationRequest a3lLocationRequest = new A3LLocationRequest.Builder(1000L).build();
//可提供不同的循环器。如果循环器为空，则使用与调用线程相关的循环器。
Task<Void> locationUpdates = a3LLocationProviderClient.requestLocationUpdates(a3lLocationRequest, a3lLocationListener, null);

停止位置更新

要在侦听器上停止位置更新，可如以下代码所示使用removeLocationUpdates()方法。removeLocationUpdates()使用A3lLocationListener对象。

//删除位置更新
Task<Void> removeLocationUpdatesTask = a3LLocationProviderClient.removeLocationUpdates(a3lLocationListener);

Last updated: 2023年9月13日

常见A3L Location API

检查设置

获取位置可用性

请求持续位置更新

停止位置更新

相关资源