瀏覽單一目的地路徑

請按照本指南的說明，使用 Navigation SDK for Android 在應用程式中規劃路線。本指南假設您已按照「設定專案」一文的說明，將 Navigation SDK 整合至應用程式。

摘要

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

  4. 使用 Navigator 類別設定目的地，並控制即時導航。這項程序包含三個步驟：

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

查看程式碼

在應用程式中新增 UI 元素

本節將介紹兩種方法，可加入互動式地圖和 UI，顯示即時路線指示。在大多數情況下，建議使用 SupportNavigationFragment (NavigationView 的包裝函式)，而非直接與 NavigationView 互動。詳情請參閱「導覽地圖互動最佳做法 」。

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

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

除了片段，您也可以使用 NavigationView 做為 UI 元件，顯示導覽地圖。

要求位置存取權

本節說明如何要求精確位置存取權。詳情請參閱 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 Manager) 設定虛擬裝置。選擇模擬器時，請務必挑選包含 Google API 的映像檔。
  2. 在 Android Studio 中，按一下「Run」(執行) 選單選項或播放按鈕圖示。然後按照系統提示選擇裝置。

提升使用者體驗的提示

  • 使用者必須接受《Google 導航服務條款》，才能使用導航功能。這項接受程序只需要執行一次。根據預設，SDK 會在首次叫用導覽器時提示接受。如要提早觸發「導航服務條款」對話方塊，例如在註冊或登入期間，可以使用 TermsAndConditionsCheckOption。
  • 如要大幅提升導航品質和預計抵達時間準確度，請使用地點 ID 初始化中途點，而非經緯度座標。
  • 這個範例會從雪梨歌劇院的特定地點 ID 衍生目的地中途點。您可以使用地點 ID 搜尋器，取得其他特定地點的 ID。