瀏覽單一目的地路徑

本指南說明如何使用 Android 版 Navigation SDK，在應用程式中繪製路線。本指南假設您已將 Navigation SDK 整合到應用程式中，如「設定專案」一文所述。

摘要

  1. 在應用程式中新增 UI 元素做為導覽片段或做為導覽檢視畫面。這個 UI 元素會將互動式地圖和即時路線導覽 UI 新增至活動。
  2. 要求位置存取權。您的應用程式必須要求位置存取權，才能判斷裝置的所在位置。
  3. 使用 NavigationApi 類別初始化 SDK。

  4. 使用 Navigator 類別設定目的地及控制即時路線導航。其中包含三個步驟：

  5. 建構並執行應用程式。

查看程式碼

在應用程式中新增 UI 元素

本節說明您可以透過兩種方式新增互動式地圖和 UI，以顯示即時路線導航。

SupportNavigationFragment 是顯示導覽視覺化輸出內容的 UI 元件，包括互動式地圖和即時路線指示。您可以在 XML 版面配置檔案中宣告片段，如下所示：

<?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"/>

或者，您也可以使用 FragmentActivity.getSupportFragmentManager()，以程式輔助方式建構片段，如 Android 說明文件中所述。

除了片段之外，用來顯示地圖的 UI 元件也可以做為 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. 選用設定。在支援的國家/地區啟用道路限制，設定車牌的最後數字。此呼叫只需要進行一次：後續的路線要求會繼續使用該呼叫。這項呼叫僅適用於支援的地區。詳情請參閱 Countries and regions supported for two-wheeled vehicles。

    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 會顯示在地圖上代表路線的折線，並在目的地顯示標記。

    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 Manager) 設定虛擬裝置。選擇模擬器時，請務必挑選包含 Google API 的映像檔。
  2. 在 Android Studio 中，按一下「Run」(執行) 選單選項或播放按鈕圖示。 然後按照系統提示選擇裝置。

有助於改善使用者體驗的提示

  • 使用者必須先接受《Google 導航服務條款》，才能使用導航功能。你只需接受一次。根據預設，SDK 會在第一次叫用導覽器時提示接受。您也可以考慮在應用程式的使用者體驗流程初期 (例如註冊或登入期間) 使用 TermsAndConditionsCheckOption 觸發《導航服務條款》對話方塊。
  • 如要大幅改善導航品質和預計到達時間的準確度，請使用地點 ID 初始化路線控點，而非經緯度座標。
  • 本範例從雪梨歌劇院的特定地點 ID 取得目的地路線控點。您可以使用地點 ID 搜尋器取得其他特定位置的地點 ID。