瀏覽單一目的地路徑

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

或者，您也可以按照 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 會顯示地圖上代表路線的折線，以及目的地的標記。

    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。