导航单目的地路线

请按照本指南中的说明操作，使用 Navigation SDK for Android 在应用中绘制路线。本指南假设您已按照设置项目中的说明将 Navigation SDK 集成到应用中。

摘要

  1. 向应用添加界面元素，可以是导航 fragment，也可以是导航视图。此界面元素可将互动式地图和逐向导航界面添加到您的 activity 中。
  2. 请求位置信息权限。您的应用必须请求位置信息权限，才能确定设备的位置。
  3. 使用 NavigationApi 类初始化 SDK。

  4. 使用 Navigator 类设置目的地并控制精细路线导航。这涉及三个步骤：

  5. 构建并运行您的应用。

查看代码

向应用添加界面元素

本部分介绍了添加互动式地图和用于显示精细导航的界面的两种方法。在大多数情况下，我们建议使用 SupportNavigationFragment（它是 NavigationView 的封装容器），而不是直接与 NavigationView 互动。如需了解详情，请参阅导航地图互动最佳实践 。

SupportNavigationFragment 是显示导航可视化输出的界面组件，包括互动式地图和精细导航路线。您可以在 XML 布局文件中声明 fragment，如下所示：

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

或者，您也可以按照 Android 文档中的说明，使用 FragmentActivity.getSupportFragmentManager() 以程序化方式构建 fragment。

除了 fragment 之外，用于显示导航地图的界面组件也可以作为 NavigationView 提供。

请求位置权限

本部分将演示如何请求精确的位置信息权限。如需了解详情，请参阅有关 Android 权限的指南。

  1. 在 Android 清单中，添加此权限作为 <manifest> 元素的子元素：

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.navsdksingledestination">
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

  2. 在应用中请求运行时权限，让用户有机会授予或拒绝位置信息权限。以下代码会检查用户是否已授予精确的位置信息权限。如果未授予，它将请求此权限：

        if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
            android.Manifest.permission.ACCESS_FINE_LOCATION)
                == PackageManager.PERMISSION_GRANTED) {
        mLocationPermissionGranted = true;
    } else {
        ActivityCompat.requestPermissions(this,
                new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
                PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
    }

    if (!mLocationPermissionGranted) {
        displayMessage("Error loading Navigation SDK: "
                + "The user has not granted location permission.");
        return;
    }

  3. 替换 onRequestPermissionsResult() 回调以处理权限请求的结果：

        @Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                           @NonNull int[] grantResults) {
        mLocationPermissionGranted = false;
        switch (requestCode) {
            case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
                // If request is canceled, the result arrays are empty.
                if (grantResults.length > 0
                        && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                    mLocationPermissionGranted = true;
                }
            }
        }
    }

初始化 Navigation SDK

NavigationApi 类提供授权应用使用 Google 导航的初始化逻辑。本部分介绍了如何初始化导航器，以及您可以为应用启用的一些其他配置：

  1. 初始化 Navigation SDK 并替换 onNavigatorReady() 回调，以便在导航器准备就绪时开始导航。

  2. 可选。配置应用，以便在用户从设备中关闭应用时，指导通知和后台服务也会关闭。具体选择取决于您的业务模式。您可能希望使用默认的导航器行为，即使应用已关闭，导航器仍会继续显示转弯指引和位置更新。如果您希望在最终用户关闭应用时停止导航和位置信息更新，则应使用此配置。

  3. 可选。在支持的国家/地区启用道路限制。设置车牌的最后一位数字。只需调用一次此方法：后续的路线请求会继续使用此方法。此调用仅在支持的地区有效。请参阅 Navigation SDK 支持的国家/地区。

        NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
                /**
                 * Sets up the navigation UI when the navigator is ready for use.
                 */
                @Override
                public void onNavigatorReady(Navigator navigator) {
                    displayMessage("Navigator ready.");
                    mNavigator = navigator;
                    mNavFragment = (NavigationFragment) getFragmentManager()
                            .findFragmentById(R.id.navigation_fragment);

                    // Optional. Disable the guidance notifications and shut down the app
                    // and background service when the user closes the app.
                    // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)

                    // Optional. Set the last digit of the car's license plate to get
                    // route restrictions for supported countries.
                    // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");

                    // Set the camera to follow the device location with 'TILTED' driving view.
                    mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);

                    // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI).
                    mRoutingOptions = new RoutingOptions();
                    mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);

                    // Navigate to a place, specified by Place ID.
                    navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
                }

                /**
                 * Handles errors from the Navigation SDK.
                 * @param errorCode The error code returned by the navigator.
                 */
                @Override
                public void onError(@NavigationApi.ErrorCode int errorCode) {
                    switch (errorCode) {
                        case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                            displayMessage("Error loading Navigation SDK: Your API key is "
                                    + "invalid or not authorized to use the Navigation SDK.");
                            break;
                        case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                            displayMessage("Error loading Navigation SDK: User did not accept "
                                    + "the Navigation Terms of Use.");
                            break;
                        case NavigationApi.ErrorCode.NETWORK_ERROR:
                            displayMessage("Error loading Navigation SDK: Network error.");
                            break;
                        case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                            displayMessage("Error loading Navigation SDK: Location permission "
                                    + "is missing.");
                            break;
                        default:
                            displayMessage("Error loading Navigation SDK: " + errorCode);
                    }
                }
            });

设置目的地

Navigator 类可用于控制导航行程的配置、开始和停止。

使用上一部分中获得的 Navigator，为此行程设置目的地 Waypoint。计算路线后，SupportNavigationFragment 会在地图上显示表示路线的多段线，并在目的地显示标记。

```none
    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

        // Create a future to await the result of the asynchronous navigator task.
        ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
                mNavigator.setDestination(destination, travelMode);

        // Define the action to perform when the SDK has determined the route.
        pendingRoute.setOnResultListener(
                new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                    @Override
                    public void onResult(Navigator.RouteStatus code) {
                        switch (code) {
                            case OK:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // Enable voice audio guidance (through the device speaker).
                                mNavigator.setAudioGuidance(
                                        Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                                // Simulate vehicle progress along the route for demo/debug builds.
                                if (BuildConfig.DEBUG) {
                                    mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                            new SimulationOptions().speedMultiplier(5));
                                }

                                // Start turn-by-turn guidance along the current route.
                                mNavigator.startGuidance();
                                break;
                            // Handle error conditions returned by the navigator.
                            case NO_ROUTE_FOUND:
                                displayMessage("Error starting navigation: No route found.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }
```

构建并运行应用

  1. 将 Android 设备连接到您的计算机。按照 Android Studio 中关于如何在硬件设备上运行应用的说明进行操作。或者，您也可以使用 Android 虚拟设备 (AVD) 管理器配置虚拟设备。选择模拟器时，请务必选择一个包含 Google API 的映像。
  2. 在 Android Studio 中，点击 Run 菜单选项或 Play 按钮图标。 按提示选择设备。

有助于改善用户体验的提示

  • 用户必须接受 Google 导航服务条款，然后才能使用导航功能。此接受操作只需执行一次。默认情况下，SDK 会在首次调用导航器时提示用户接受。如果您愿意，可以使用 TermsAndConditionsCheckOption 在应用的用户体验流程的早期阶段（例如注册或登录期间）触发“导航服务条款”对话框。
  • 为了显著提高导航质量和预计到达时间 (ETA) 准确性，请使用地点 ID 初始化途经点，而不是使用纬度/经度坐标。
  • 此示例从悉尼歌剧院的特定地点 ID 派生出目的地途径点。您可以使用地点 ID 查找工具获取其他特定地点的地点 ID。