Navigation SDK 目前僅供特定客戶使用。如要瞭解詳情，請聯絡銷售人員。

Google 地圖平台即將推出全新地圖樣式設定。本次地圖樣式更新包含新的預設調色盤，並改善地圖體驗和可用性。所有地圖樣式都將在 2025 年 3 月自動更新。如要進一步瞭解可用性及如何選擇加入計畫，請參閱「Google 地圖平台的全新地圖樣式」一文。

本頁面由 Cloud Translation API 翻譯而成。

啟用即時路線導航資料動態饋給

即時路線資料動態饋給為未針對地圖式導航指引的裝置提供導航資訊。這個外掛程式能為您提供立即可用的元素：

圖示 (左、右、迴轉)
CANNOT TRANSLATE
路名
到達下個導航步驟或最終目的地的預估距離和所需時間

您可以使用即時路線動態饋給，打造不適合完整 Navigation SDK UI 的體驗，例如 Android Auto 或無法使用完整 Android 堆疊的小螢幕顯示畫面。舉例來說，您可以將這項功能用於雙輪車駕駛，藉此投影純導航的指引，在盡量減少干擾的情況下，幫助他們更快、更放心地抵達目的地。

如要使用這個 SDK，您要建立服務並向 Android 適用的 Navigation SDK 註冊，以便即時接收新的導覽資訊 (大約在導航期間接收一次新的導覽資訊)。

本文說明如何建立及註冊用於接收來自 SDK 的導覽資訊的導航服務，並為接收裝置提供導覽狀態。

總覽

本節說明如何在專案中新增 TurnByTurn 程式庫，並概略說明建構即時路線功能的概略流程。

使用 Maven 將 TurnByTurn 程式庫新增至專案 (建議做法)

如要使用獨立版本的 TurnByTurn 程式庫，請按照下列步驟操作：

設定環境以存取主機 Maven 存放區：

Maven

請將以下內容新增到 pom.xml 檔案中：

    <project>
      ...
      <repositories>
        <repository>
          <id>google-maven-repository</id>
          <url>https://maven.google.com</url>
        </repository>
      </repositories>
      ...
    </project>

Gradle

請將以下內容新增到 build.gradle 檔案中：

repositories {
    ...
    google()
}

Maven

<dependencies>
...
<dependency>
      <groupId>com.google.android.maps</groupId>
      <artifactId>google_turnbyturn</artifactId>
      <version>1.0.0</version>
</dependency>
</dependencies>

Gradle

dependencies {
  ...
  implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
}

使用下載的 JAR 檔案 (替代方法) 將 TurnByTurn 程式庫新增至專案中

TurnByTurn 程式庫會以 JAR 檔案的形式儲存在這個 SDK 資料夾中。若您沒有存取權限，請與代表聯絡。

下載 google_turnbyturn_*.jar 並解壓縮。
將下載的 JAR 檔案複製到專案的 app/libs 目錄。

將以下內容新增到 build.gradle，以在建構中加入 JAR。

dependencies {
   ...
   api fileTree(include: ['*.jar'], dir: 'libs')
}

使用 TurnByTurn 程式庫

以下是啟用即時路線導航功能的高階啟用步驟。後續章節會提供每個步驟的詳細資料。

建立服務以接收導航更新內容。
註冊服務。
瞭解導覽狀態。
查看顯示重要元素的導覽顯示範例。

建立服務來接收導航更新資訊

Navigation SDK 會繫結至 TurnByTurn 服務，並透過 Android Messenger 傳送導覽更新。您可以為這些更新內容建立新的導航服務，或使用現有服務。

使用服務接收導航更新的好處是，服務可在獨立的背景程序中運作。

以下範例中的服務會接收導航資訊，並使用 TurnByTurnManager 將資料轉換為包含導覽詳細資料的 NavInfo 物件。

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

訊息代碼

NavInfo 訊息可透過 Message 類別的 Message.what 欄位識別，這個欄位會設為 TurnByTurnManager.MSG_NAV_INFO 的值。

註冊服務以更新導航

下列程式碼片段可註冊導航服務。

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

啟動及停止服務

只要 Navigation SDK 繫結至導航服務，導航服務就會啟用。您可以手動呼叫 startService() 和 stopService() 來控制導航服務的生命週期，但使用 Navigation SDK 註冊服務時，服務會自動啟動，並且只會在取消註冊時停止服務。視應用程式的設定方式而定，建議您啟用前景服務，詳情請參閱 Android 說明文件「服務總覽」。

取消註冊服務

如要停止接收導航更新，請從 Navigation SDK 取消註冊服務。

navigator.unregisterServiceForNavUpdates();

瞭解導覽狀態

請使用 NavInfo.getNavState() 取得導覽目前的狀態，也就是下列其中一種：

Enroute：ENROUTE 狀態表示引導式導航目前已啟用，且使用者正在提供的路線。可提供目前後續行動步驟的相關資訊。
Rerouting - REROUTING 表示導航正在進行中，但導航工具正在尋找新路徑。目前沒有任何新路線，因此無法進行接下來的操縱步驟。在範例應用程式中，導覽資訊畫面會顯示「Rerouting...」訊息。找到路徑後，會傳送 ENROUTE 狀態的 NavInfo 訊息。
已停止 - STOPPED 表示導航已結束。舉例來說，當使用者在應用程式中結束導航時，導航就會停止。在範例應用程式中，STOPPED 狀態會清除導覽資訊顯示畫面，以免顯示操作步驟操作說明。

在動態消息顯示畫面中填入資料

您現在已經設定即時路線服務，本節介紹了可使用的視覺和文字元素，以便為即時路線動態饋給填入指引資訊卡。

導覽資訊卡資訊欄位

手機螢幕顯示即將在 100 英尺處向前彎曲 100 英尺，會轉到 W Ahwanee Ave。在螢幕下方，距離目的地還有 46 分鐘，剩餘距離為 39 英里。

使用者進入導覽導覽時，頂端會顯示導覽資訊卡，當中包含由 Navigation SDK 填入的導覽資料。相關圖片顯示了這些重要導覽元素的範例。

下表列出導覽資訊的欄位和欄位位置。

每個導覽步驟的欄位	整趟行程的欄位
在「`StepInfo`」中發現	在「`NavInfo`」中發現
完整道路名稱	剩餘時間
動畫圖示	與目的地的距離
到下一個步驟的距離
車道指引欄位

車道指引

Navigation SDK 會將導航路線資訊卡中的車道顯示為 Lane 和 LaneDirection 資料物件。Lane 物件代表導航期間的特定車道，並包含 LaneDirection 物件清單，這些物件說明從這條車道可以到達的所有轉彎處。

車道指引設定範例。

建議使用者走車道的建議方向會標示「isRecommended」欄位。

車道指引範例

下列程式碼片段說明上方顯示車道的資料表示法。

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

建立操作圖示

Maneuver 列舉會定義導覽時可能發生的所有可能方式，您可以透過 StepInfo.getManeuver() 方法取得特定步驟的配置。

您必須建立手勢圖示，並將其與相關操作配對。以某些方式來說，您可以設定與圖示之間的一對一對應，例如 DESTINATION_LEFT 和 DESTINATION_RIGHT。不過，由於部分做法相似，因此您可能會想將多個操控方式對應至單一圖示。舉例來說，TURN_LEFT 和 ON_RAMP_LEFT 都能對應到左轉圖示。

部分方式包含額外的 clockwise 或 counterclockwise 標籤，而 SDK 會根據國家/地區的推動因素決定標籤內容。舉例來說，如果行駛於道路左側行駛的國家/地區，駕駛會順時針方向進行圓環或迴轉，但道路右側的國家/地區則順時針方向。Navigation SDK 會偵測控制項是否出現在左側或右側流量中，然後輸出適當的處理程序。因此，順時針與逆時針圖示可能有所不同。

展開即可查看不同方式的圖示範例

「範例」圖示	轉彎手術
	`DEPART` `UNKNOWN`
	`STRAIGHT` `ON_RAMP_UNSPECIFIED` `OFF_RAMP_UNSPECIFIED` `NAME_CHANGE`
	`TURN_RIGHT` `ON_RAMP_RIGHT`
	`TURN_LEFT` `ON_RAMP_LEFT`
	`TURN_SLIGHT_RIGHT` `ON_RAMP_SLIGHT_RIGHT` `OFF_RAMP_SLIGHT_RIGHT`
	`TURN_SLIGHT_LEFT` `ON_RAMP_SLIGHT_LEFT` `OFF_RAMP_SLIGHT_LEFT`
	`TURN_SHARP_RIGHT` `ON_RAMP_SHARP_RIGHT` `OFF_RAMP_SHARP_RIGHT`
	`TURN_SHARP_LEFT` `ON_RAMP_SHARP_LEFT` `OFF_RAMP_SHARP_LEFT`
	`TURN_U_TURN_COUNTERCLOCKWISE` `ON_RAMP_U_TURN_COUNTERCLOCKWISE` `OFF_RAMP_U_TURN_COUNTERCLOCKWISE`
	`TURN_U_TURN_CLOCKWISE` `ON_RAMP_U_TURN_CLOCKWISE` `OFF_RAMP_U_TURN_CLOCKWISE`
	`ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE`
	`ROUNDABOUT_SHARP_RIGHT_CLOCKWISE`
	`ROUNDABOUT_RIGHT_COUNTERCLOCKWISE`
	`ROUNDABOUT_RIGHT_CLOCKWISE`
	`ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE`
	`ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE`
	`ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE`
	`ROUNDABOUT_STRAIGHT_CLOCKWISE`
	`ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE`
	`ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE`
	`ROUNDABOUT_LEFT_COUNTERCLOCKWISE`
	`ROUNDABOUT_LEFT_CLOCKWISE`
	`ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE`
	`ROUNDABOUT_SHARP_LEFT_CLOCKWISE`
	`ROUNDABOUT_U_TURN_COUNTERCLOCKWISE`
	`ROUNDABOUT_U_TURN_CLOCKWISE`
	`ROUNDABOUT_COUNTERCLOCKWISE`
	`ROUNDABOUT_CLOCKWISE`
	`ROUNDABOUT_EXIT_COUNTERCLOCKWISE`
	`ROUNDABOUT_EXIT_CLOCKWISE`
	`MERGE_RIGHT` `OFF_RAMP_RIGHT`
	`MERGE_LEFT` `OFF_RAMP_LEFT`
	`FORK_RIGHT` `TURN_KEEP_RIGHT` `ON_RAMP_KEEP_RIGHT` `OFF_RAMP_KEEP_RIGHT`
	`FORK_LEFT` `TURN_KEEP_LEFT` `ON_RAMP_KEEP_LEFT` `OFF_RAMP_KEEP_LEFT`
	`MERGE_UNSPECIFIED`
	`DESTINATION`
	`DESTINATION_RIGHT`
	`DESTINATION_LEFT`
	`FERRY_BOAT`
	`FERRY_TRAIN`

使用產生的圖示

Navigation SDK 提供的生成圖示小清單。

為協助 Android Auto 的用途，Navigation SDK 支援產生路線指引和車道指引圖示。這些圖示符合 Android Auto Car App 程式庫的圖片大小調整指南，建議指定 500 x 74 dp 的定界框。詳情請參閱 Android 參考說明文件中的 setsLaneImage 和 CarIcon。

圖示產生範例

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

啟用圖示產生功能後，TurnbyTurn StepInfo 物件就會以圖示填入 maneuverBitmap 和 lanesBitmap 欄位。

後續步驟

Android Auto 應用程式：
- 繪製地圖並啟用導航功能。