瀏覽單一目的地路徑

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

摘要

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

  4. 設定目的地並使用 Navigator 類別這項程序分為三個步驟：

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

查看程式碼

在應用程式中新增 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:

    <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。