瀏覽單一目的地路徑

請按照本指南的說明，使用 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"/>

或者，您也可以使用 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. 選用設定。在支援的國家/地區啟用道路限制功能。設定車牌號碼的最後一個號碼。這個呼叫只需進行一次：後續的路線要求會繼續使用這個呼叫。這項呼叫僅適用於支援的區域。請參閱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 會在地圖上顯示代表路線的折線，以及目的地標記。

    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。