請按照本指南的說明,使用 Navigation SDK for Android 在應用程式中繪製路線。本指南假設您已按照「設定專案」一節的說明,將 Navigation SDK 整合至應用程式。
摘要
- 將 UI 元素新增至應用程式,做為導覽片段或導覽檢視畫面。這個 UI 元素會加入互動式地圖和即時路線指引 導覽 UI 加入活動。
- 要求位置存取權。應用程式必須要求位置存取權,才能判斷裝置的位置。
- 使用
NavigationApi
類別 設定目的地並使用
Navigator
類別這項程序分為三個步驟:- 使用以下方式設定目的地
setDestination()
。 - 使用
startGuidance()
開始導航。 - 使用
getSimulator()
以模擬車輛在沿途的進度 以測試、偵錯及展示應用程式
- 使用以下方式設定目的地
建構並執行應用程式。
查看程式碼
在應用程式中新增 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 權限指南。
將權限新增為 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>
在應用程式中要求執行階段權限,讓使用者可以授予或拒絕位置存取權。下列程式碼會檢查使用者是否已授予精確位置存取權;如果未授予,程式碼就會要求權限:
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; }
覆寫
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
導覽。本節說明如何初始化導覽器,以及一些
您可以為應用程式啟用的其他設定:
初始化 Navigation SDK 並覆寫
onNavigatorReady()
回呼在導航工具處於下列狀態時開始導航 準備好選用設定。設定應用程式,讓使用者從裝置上關閉應用程式時,導覽通知和背景服務會關閉。這個 取決於您的商業模式建議您使用預設值 導航工具行為,持續顯示轉彎指引和位置 也會更新。如果您想將 導航和位置會在使用者關閉應用程式時更新。 就會使用這項設定
選用設定。在支援的國家/地區啟用道路限制功能。設定車牌號碼的最後一個號碼。此呼叫只需進行一次:後續 路線要求則繼續使用。這項呼叫僅適用於支援的區域。詳情請見 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));
}
}
});
}
建構並執行應用程式
- 將 Android 裝置連接到電腦。追蹤 Android Studio 有關在硬體裝置上執行應用程式的操作說明 或者,您也可以使用 Android 虛擬裝置 (AVD Manager): 選擇模擬器時,請務必挑選包含 Google API
- 在 Android Studio 中,按一下「Run」選單選項或播放按鈕圖示。然後按照系統提示選擇裝置。
提升使用者體驗的提示
- 使用者必須接受《Google 導航服務條款》
可以使用導航功能。您只需接受一次。變更者:
根據預設,SDK 會在首次導航器發生時提示接受
呼叫。如有需要,也可以觸發「導航服務條款」對話方塊
在應用程式使用者體驗流程的初期階段 (例如註冊或登入時),使用
TermsAndConditionsCheckOption
。 - 如要大幅改善導航品質和預計到達時間,請使用 用來初始化路線點而非經緯度的地點 ID 座標。
- 這個範例會從雪梨歌劇院的特定地點 ID 擷取目的地路線點。您可以使用 地點 ID 搜尋器, 其他特定地點的地點 ID。