適用於 Android Automotive 意圖的 Google 地圖

免責事項

這項產品/功能將有所變更，且不受任何服務水準協議 (SLA) 或淘汰政策的規範。實作方式可能會在日後的版本中有所變動。

關於本文件隨附的範例軟體、資料檔案和/或原始碼：本產品是「依現況」提供，且不提供任何形式的擔保，Google 明確聲明不對任何明示、默示、法定或其他擔保負責，包括但不限於適售性、特定用途適用性和未侵害本產品相關權利的擔保。

您可以透過 Android Automotive 意圖，在 Google 地圖中啟動導航功能。

詳情請參閱「Android 版 Google 地圖意圖」。

如要進一步瞭解如何讓應用程式在搭載 Android Auto 或 Android Automotive OS 的車輛上運作，請參閱「車用 Android」。

總覽

本頁面說明可與 Android Automotive 版 Google 地圖搭配使用的意圖。如需詳細的 Android 開發人員說明文件，請參閱：

意圖要求

如要透過意圖啟動 Android Automotive 版 Google 地圖，您必須先建立 Intent 物件，並指定其動作、URI 和套件。

  • Action。所有 Google 地圖意圖都會以 View 動作 ACTION_VIEW 的形式呼叫。

  • URI。Google 地圖意圖會使用URI 編碼字串，指定所需動作以及執行動作所需的資料。

  • Package。呼叫 setPackage("com.google.android.apps.maps") 可確保 Android 版 Google 地圖應用程式處理 Intent。如果未設定套件，系統會判斷哪些應用程式可以處理意圖。如果有多個應用程式可用，系統可能會詢問您要使用哪一個應用程式。

建立意圖後，您可以要求系統以多種方式啟動相關應用程式。常見的方法是將意圖傳遞至 startActivity() 方法。系統會啟動必要的應用程式 (在本例中為 Google 地圖)，並啟動對應的活動。

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

如果系統無法辨識可回應意圖的應用程式，應用程式可能會當機。因此，請先確認接收應用程式已安裝，再向使用者顯示其中一個意圖。

如要確認應用程式可接收意圖，請在 Intent 物件上呼叫 resolveActivity()。如果結果非空值，至少會有一個應用程式可處理意圖，因此可以放心呼叫 startActivity()。如果結果為空值，則不應使用意圖，並盡可能停用叫用意圖的功能。

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

舉例來說，如要啟動前往雪梨塔龍加動物園 (Taronga Zoo) 的即時路線導航，可以使用以下程式碼：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

URI 編碼查詢字串

傳遞至 Google 地圖意圖的所有字串都必須採用 URI 編碼。舉例來說，字串「1st & Pike, Seattle」應變成 1st%20%26%20Pike%2C%20Seattle。字串中的空格可以使用 %20 編碼，也可以替換成加號 (+)。

您可以使用 android.net.Uri parse() 方法對字串進行編碼。例如：

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

啟動即時路線導航

使用這個意圖，即可啟動 Google 地圖導航功能，並取得一或多個指定地址或座標的即時路線指引。路線指引一律會從使用者目前位置開始。

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

參數

如要啟動導航功能，請使用 place 或 q 搭配 waypoints (選用)。如要選擇將路線點標示為充電站，請參閱「將電動車行程規劃傳送至 Google 地圖」。

  • q 會設定導覽搜尋的終點。這可以是經緯度或查詢格式化的地址。如果查詢字串會傳回多個結果，系統會選取第一個結果。

  • place 會將端點設為住家或公司。指定「住家」即可導航至使用者的住家，「工作」則可導航至使用者的職場。

  • avoid 會設定路線應盡量避免的功能。avoid 為選用項目，可設為下列一或多個選項：

    • t (收費路段)
    • h 代表高速公路
    • f 適用於渡輪

  • waypoints 會指定一或多個中繼地點，以便將路線指示導引至 q 指定的最終目的地。您可以使用直立線字元 (|) 分隔地點，指定多個路線點，例如 Berlin,Germany|Paris,France。您可以視需要使用任意數量的路線點。路標會依照網址中列出的順序加入路線。每個路標可以是地址，也可以是經緯度座標 (以半形逗號分隔)；此外，您可以在同一個意圖中使用地址和經緯度座標。字串應使用網址轉義，因此像是「Berlin,Germany|Paris,France」這類的路線點應轉換為 Berlin%2CGermany%7CParis%2CFrance。

範例

這項意圖會要求逐向導航，前往位於澳洲雪梨的塔龍加動物園：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如果您不想支付通行費或搭乘渡輪，可以要求系統規劃路線，盡量避免這些情況：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

或者，如果你想前往住家，請使用以下指令：

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

如要依序啟動至下列三個地址的即時路線導航，請將塔龍加動物園設為最終目的地 q，並將 Google 雪梨辦公室和雪梨歌劇院設為路徑點：

  1. Google 雪梨

  2. 雪梨歌劇院

  3. 澳洲雪梨塔龍加動物園

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

與 q 類似，您可以使用半形逗號分隔的緯度和經度，而非地址，來表示任何路線點。舉例來說，如要傳遞雪梨歌劇院的緯度和經度，而非地址，則可啟動相同的導航功能：

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

將電動車行程規劃傳送至 Google 地圖

使用這個多目的地導航意圖，指定部分目的地為電動車 (EV) 充電站。這個意圖可擴充多點意圖，協助駕駛人維持充足的電動車電池電量，以便抵達目的地，方法是同步電動車行程規劃應用程式和 Google 地圖之間的充電站資訊。

如要設定充電站，請使用行程意圖：

  • 必須包含名稱和緯度-經度
  • 可選擇加入電力輸出值，用於計算充電時間

Google 會使用充電站名稱和經緯度來找出相符的充電站地點，並顯示豐富的資料，例如連接器類型、總數、速度和即時可用性、支援的付款方式，以及主機搜尋點 (POI)。例如：導航最後路段的室外停車場路線指示、營業時間、評分。為確保充電站與 Google 資料相符，請使用 <brand name>，例如 ChargePoint。

參數

終點站

如要將充電站設為最終目的地，請使用以下指令：

  • q：必須包含充電站的緯度-經度值。
  • q_type：1 指定最終目的地為充電站。
  • q_name：最終目的地的名稱。如果 q_type 是 1，則為必要元素。
  • q_power_output_kw：以千瓦為單位的充電站電力輸出量，為雙精度數字。選用項目。

路點

針對路線點，所有參數都是平行，且以 |- 分隔的陣列值，其順序與路線點相同，但不包含最終目的地。如果平行陣列中的元素數量不相符，系統會將其視為格式錯誤的意圖。

如要新增一或多個充電站路線點，請使用下列參數，所有參數皆為選用。如果其中一個目的地標示為充電站，則該目的地必須有路線點名稱。

  • waypoints：如即時路線導航意圖所述，路線點清單。充電站路標必須為經緯度值。

  • waypoint_types：每個路標的類型，以數字表示。0 是任何停靠站 (預設值)，1 則是充電站。

  • waypoint_names：路線點名稱。這是充電站的必填欄位。

  • waypoint_power_outputs_kw：以千瓦為單位的充電站功率。針對充電站，您可以選擇指定路徑點功率輸出值，如果找不到相符的站點，系統就會使用這個值。空白的插槽代表未提供任何值。

使用者體驗 (UX) 行為

對於有多個目的地的行程意圖，系統會顯示路線總覽畫面，但不會自動啟動導航功能。

如果意圖格式正確，Google 地圖就會顯示行程的路線總覽畫面。路線總覽畫面會顯示意圖中的所有路線點和最終目的地，並在適用情況下提供充電建議。

對於標示為充電站的任何中途點或最終目的地，Google 地圖會在 Google 資料庫中搜尋相符的地點。

如果找到相符項目，Google 地圖會使用 Google 資料，在使用者介面 (UI) 中顯示充電站，並提供充電站的充電建議。如果找不到相符項目，系統會使用充電站意圖中提供的資料 (經緯度、名稱和電力輸出)，在 UI 中顯示這個充電站，並提供充電站的充電建議。

範例

透過多個充電站導航至最終目的地

以下意圖會透過兩個充電站 (ChargePoint 和 Evie) 前往最終目的地：新南威爾斯 Port Macquarie。

目的地順序：

  1. ChargePoint 充電站 (位置：-32.9599188,151.6240806, 輸出功率：6.6kw)

  2. Evie 充電站 (位置：-31.9432539,152.4699808, 輸出功率：350kw)

  3. 新南威爾斯州 Port Macquarie

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

不明的電源輸出

如果不知道功率輸出值，請將 waypoint_power_outputs_kw 的相關位置留空。或者，如果所有時段都空白，則不需要指定 waypoint_power_outputs_kw 參數。

目的地順序：

  1. ChargePoint 充電站 (位置：-32.9599188,151.6240806, 功率輸出：不明)

  2. 新南威爾斯州 Port Macquarie

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

將最終目的地標示為充電站

如要將最終目的地標示為充電站，請指定 q_type、q_name 和 q_power_output_kw 參數。

目的地順序：

  1. 澳洲雪梨塔龍加動物園

  2. ChargePoint 充電站 (位置：-32.9599188,151.6240806, 輸出功率：不明)

  3. Evie 充電站 (位置：-31.9432539,152.4699808, 輸出功率：350kw)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

動作意圖

下列動作意圖含有介面：

動作 說明
geo.action:?act=mute 將所有導航語音導引設為靜音。
geo.action:?act=unmute 取消導航語音導引的靜音設定。
geo.action:?act=show_traffic 在地圖上顯示車流量線。
geo.action:?act=hide_traffic 隱藏地圖上的車流量線。
geo.action:?act=show_satellite 在地圖上顯示衛星圖像。
geo.action:?act=hide_satellite 隱藏地圖上的衛星圖像。
geo.action:?act=query_next_turn Google 地圖會朗讀下一個轉彎指示 (僅限導航中)。
geo.action:?act=distance_to_next_turn Google 地圖會說出下一個轉彎的距離 (僅在導航時有效)。
geo.action:?act=time_to_next_turn Google 地圖會朗讀下一個轉彎的時間 (僅適用於導航中)。
geo.action:?act=distance_to_destination Google 地圖會說出到達目的地的距離 (僅在導航時有效)。
geo.action:?act=go_back Google 地圖會返回 UI 中的上一個畫面。
geo.action:?act=query_current_road Google 地圖會朗讀目前的道路。
geo.action:?act=query_destination Google 地圖會朗讀目的地。
geo.action:?act=apply_electric_vehicle_connector_filter 為電動車充電站搜尋結果套用連接器類型篩選器。
geo.action:?act=remove_electric_vehicle_connector_filter 移除電力車輛充電站搜尋結果的連接器類型篩選器。
geo.action:?act=apply_electric_vehicle_payment_filter 為電動車充電站搜尋結果套用付款篩選器。
geo.action:?act=remove_electric_vehicle_payment_filter 移除電動車充電站搜尋結果的付款篩選器。
geo.action:?act=apply_electric_vehicle_fast_charging_filter 為電動車充電站搜尋結果套用快速充電篩選器。
geo.action:?act=remove_electric_vehicle_fast_charging_filter 移除電動車充電站搜尋結果中的快速充電篩選器。
geo.action:?act=avoid_tolls 如果使用者正在導航，請告知 Google 地圖避開收費路線。如果目前路線有收費站，系統可能會重新規劃路線。
geo.action:?act=allow_tolls 如果使用者正在導航，請告知 Google 地圖允許收費路線。如果允許收費路線可提供更佳的路線，系統可能會重新規劃路線。
geo.action:?act=avoid_ferries 如果使用者正在導航，請告知 Google 地圖避免使用渡輪路線。如果目前的有效路線有渡輪，這可能會導致重新導航。
geo.action:?act=allow_ferries 如果使用者正在導航，請告知 Google 地圖允許含有渡輪的路線。如果允許渡輪可使用更佳的路線，可能會導致重新導航。
geo.action:?act=avoid_highways 如果使用者正在導航，請告知 Google 地圖避免高速公路路線。如果目前的有效路線包含高速公路，這可能會導致重新導航。
geo.action:?act=allow_highways 如果使用者正在導航，請告知 Google 地圖允許高速公路路線。如果允許使用高速公路可讓您取得更佳的路線，系統可能會重新規劃路線。
geo.action:?act=eta 如果使用者正在導航，Google 地圖會朗讀預估抵達目的地時間 (例如上午 9 點 15 分)。
geo.action:?act=time_to_destination 如果使用者正在導航，Google 地圖會朗讀到達目的地的預估時間 (例如 15 分鐘)。
geo.action:?act=exit_navigation 結束導航。
geo.action:?act=select_search_result&id=0 如果目前有搜尋結果顯示在畫面上 (請參閱下方說明)，系統會根據提供的 ID 參數，開始導覽至第 n 個搜尋結果。請注意，索引是以 0 為起點 (也就是說，上述意圖會選取清單中的第 1 個結果)。

畫面上顯示的搜尋結果