路線規劃服務

注意：伺服器端程式庫

本頁說明 Maps JavaScript API 提供的用戶端服務。如要在伺服器上使用 Google 地圖網頁服務，請參閱「Google 地圖服務適用的 Node.js 用戶端」一文。該連結中的頁面也會介紹 Google 地圖服務適用的 Java 用戶端、Python 用戶端和 Go 用戶端。

總覽

另請參閱 Maps JavaScript API 參考資料： 路線規劃

您可以使用 DirectionsService 物件來計算路線 (使用各種交通方式)。這個物件會與 Google Maps API 路線規劃服務通訊，該服務會接收路線規劃要求並傳回有效路徑。交通時間是經過最佳化調整的主要因素，但系統也會將距離、轉彎次數和許多其他因素納入考量。您可以自行處理這些路線規劃結果，也可以使用 DirectionsRenderer 物件呈現這些結果。

在路線規劃要求中指定起點或目的地時，您可以指定查詢字串 (例如「伊利諾州芝加哥」或「澳洲新南威爾斯州達爾文」)、LatLng 值或 Place 物件。

路線規劃服務會使用一系列路線控點，傳回多個部分的路線。路線規劃結果可以是地圖上以折線繪製的路線，或是在 <div> 元素中的一系列文字描述 (例如「右轉上中港交流道」)。

開始使用

請先在 Google Cloud 控制台中，確認您為 Maps JavaScript API 設定的專案已啟用 Directions API，然後再開始使用 Maps JavaScript API 路線規劃服務。

如要查看已啟用的 API 清單，請按照下列步驟操作：

1. 前往 Google Cloud 控制台。
2. 按一下「選取專案」按鈕，選取您為 Maps JavaScript API 設定的專案，然後點選「開啟」。
3. 在「Dashboard」(資訊主頁) 的 API 清單中，找出 Directions API。
4. 如果在清單中看到該 API，表示一切就緒。如果「沒有」看到這個 API，請按照下列步驟進行啟用：
   1. 選取頁面頂端的「ENABLE API」(啟用 API)，即會顯示「Library」(程式庫) 分頁。或者，您也可以從左側選單中選取「程式庫」。
   2. 搜尋「Directions API」，然後從結果清單中選取該 API。
   3. 選取「啟用」。這個程序完成後，「Dashboard」(資訊主頁) 的 API 清單就會顯示「Directions API」。

定價和政策

定價

自 2018 年 7 月 16 日起，地圖介面集、路徑介面集和地點介面集採用新的「即付即用」定價方案，如要進一步瞭解新的 JavaScript 路線規劃服務使用費和用量限制，請參閱 Directions API 的「用量與計費」一文。

政策

使用路線規劃服務時，必須遵循 Directions API 的既定政策。

路線規劃要求

Google Maps API 必須呼叫外部伺服器，因此路線規劃服務是以非同步的方式存取。基於這個理由，您必須傳遞在完成要求後執行的「回呼」方法。這個回呼方法會處理結果。請注意，路線規劃服務可能會以不同 routes[] 陣列的形式，傳回多個可能行程。

如要在 Maps JavaScript API 中使用路線規劃，請建立 DirectionsService 類型的物件，然後呼叫 DirectionsService.route() 向路線規劃服務發出要求，並傳遞 DirectionsRequest 物件常值，其中包含輸入字詞與收到回應時執行的回呼方法。

DirectionsRequest 物件常值包含下列欄位：

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

這些欄位的說明如下：

• origin (必要) 指定用於計算路線的起點。這個值可指定為 String (例如「伊利諾州芝加哥」)、LatLng 值或 Place 物件。如果使用 Place 物件，可以指定地點 ID、查詢字串或 LatLng 位置。您可以從 Maps JavaScript API 中的 Geocoding、Place Search 和 Place Autocomplete 服務擷取地點 ID。如需使用 Place Autocomplete 服務中地點 ID 的範例，請參閱 Place Autocomplete 和路線規劃。
• destination (必要) 指定用於計算路線的終點。選項與上述 origin 欄位相同。
• travelMode (必要) 指定計算路線時採用的交通方式。如需有效值的說明，請參閱下方的交通方式。
• transitOptions (選用) 指定的值只適用於 travelMode 為 TRANSIT 的要求。如需有效值的說明，請參閱下方的大眾運輸選項。
• drivingOptions (選用) 指定的值只適用於 travelMode 為 DRIVING 的要求。如需有效值的說明，請參閱下方的行車選項。

• unitSystem (選用) 指定顯示結果時要使用的單位系統。如需有效值的說明，請參閱下方的單位系統。

• waypoints[] (選用) 指定 DirectionsWaypoint 的陣列。路線控點是透過行經的指定位置來調整路線。路線控點可以指定為物件常值，欄位如下所示：

  • location 可將路線控點的位置指定為 LatLng、Place 物件，或要進行地理編碼的 String。
  • stopover 為布林值，表示路線控點是路線上的行經點，可將路線一分為二

  (如要進一步瞭解路線控點，請參閱下方的使用路線上的路線控點)。

• optimizeWaypoints (選用) 指定路線使用提供的 waypoints 時，是否可透過更有效率的順序調整路線控點，進而達到最佳化。如果為 true，路線規劃服務會在 waypoint_order 欄位中傳回重新排序的 waypoints (詳情請參閱下方的使用路線上的路線控點)。
• provideRouteAlternatives (選用) 設定為 true 時，表示路線規劃服務可在回應中提供多條替代路線。請注意，提供替代路線可能會延長伺服器的回應時間。這個方法僅適用於沒有中繼路線控點的要求。
• avoidFerries (選用) 設為 true 時，表示計算的路線應盡可能避開渡輪。
• avoidHighways (選用) 設為 true 時，表示計算的路線應盡可能避開主要高速公路。
• avoidTolls (選用) 設定為 true 時，表示計算的路線應盡可能避開收費路段。
• region (選用) 用來指定區碼，採 ccTLD (「頂層網域」) 的兩位字元值 (詳情請參閱下方的區域自訂調整)。

注意：durationInTraffic 欄位現已淘汰。先前我們建議 Google 地圖平台付費方案客戶使用這個欄位，指定結果是否要加入系統考量目前路況後算出的時間長度。建議您現在改用 drivingOptions 欄位。

下方為 DirectionsRequest 範例：

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

交通方式

計算路線時，您必須指定要使用哪種交通方式。目前支援下列交通方式︰

• DRIVING (預設) 表示使用路網的標準行車路線。
• BICYCLING 會要求沿途設有單車道與專用道路的單車路線。
• TRANSIT 會要求使用大眾運輸的路線。
• WALKING 會要求沿途設有人行道和騎樓的步行路線。

如要瞭解特定國家/地區支援的路線範圍，請參閱 Google 地圖平台涵蓋範圍詳細資料。如果要求路線的區域沒有提供指定的路線類型，則回應將傳回 DirectionsStatus="ZERO_RESULTS"。

注意：步行路線有時無法明確提供人行道指示，因此會在 DirectionsResult 中傳回警告，您必須向使用者顯示這類警告。如果未使用預設的 DirectionsRenderer，則您必須負責確保顯示警告。

大眾運輸選項

路線規劃要求的可用選項會因交通方式而異。要求大眾運輸路線時，系統會忽略 avoidHighways、avoidTolls、waypoints[] 和 optimizeWaypoints 選項。您可以透過 TransitOptions 物件常值，指定大眾運輸專屬的路線選項。

大眾運輸路線有時效性，系統只會傳回未來時間的路線。

TransitOptions 物件常值包含下列欄位：

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

這些欄位的說明如下：

• arrivalTime (選用) 會將所需的抵達時間指定為 Date 物件。如果指定抵達時間，系統就會略過出發時間。
• departureTime (選用) 會將所需的出發時間指定為 Date 物件。如果指定 arrivalTime，系統就會略過 departureTime。如未指定 departureTime 或 arrivalTime 的值，則會預設為現在 (也就是目前時間)。
• modes[] (選用) 陣列包含一或多個 TransitMode 物件常值。這個欄位只有在要求包含 API 金鑰時才能加入。每個 TransitMode 都會指定偏好的交通方式。可使用的值如下：
  • BUS 表示計算出的路線應優先選擇以公車做為交通方式。
  • RAIL 表示計算出的路線應優先選擇以火車、電車、輕軌電車和地鐵做為交通方式。
  • SUBWAY 表示計算出的路線應優先選擇以地鐵做為交通方式。
  • TRAIN 表示計算出的路線應優先選擇以火車做為交通方式。
  • TRAM 表示計算出的路線應優先選擇以電車和輕軌電車做為交通方式。
• routingPreference (選用) 會指定大眾運輸路線的偏好設定。使用這個選項時，您可以自訂調整傳回的選項，而不接受 API 選擇的預設最佳路線。這個欄位只有在要求包含 API 金鑰時才能指定。可使用的值如下：
  • FEWER_TRANSFERS 表示計算出的路線應優先選擇轉乘次數較少的選項。
  • LESS_WALKING 表示計算出的路線應優先選擇步行距離較短的選項。

以下是搭乘大眾運輸的 DirectionsRequest 範例：

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

行車選項

您可以透過 DrivingOptions 物件指定行車路線的路線選項。

DrivingOptions 物件包含下列欄位：

{
  departureTime: Date,
  trafficModel: TrafficModel
}

這些欄位的說明如下：

• departureTime (讓 drivingOptions 物件常值有效的必要欄位) 會將所需的出發時間指定為 Date 物件。這個值必須設為目前時間或未來時間，不得設為過去的時間 (API 會將所有日期轉換為世界標準時間，確保不同時區的資料能以一致的方式處理)。針對 Google 地圖平台付費方案客戶，如果您在要求中加入 departureTime，API 就會根據當時的預期路況傳回最佳路線，並在回應中附上預估交通時間 (duration_in_traffic)。如未指定出發時間 (也就是如果要求不包含 drivingOptions)，系統傳回的路線通常是不考慮路況的最佳路線。
• trafficModel (選用) 會指定計算交通時間時要採用的假設。這項設定會影響回應中 duration_in_traffic 欄位傳回的值，其中包含根據歷來平均值預估的交通時間。預設值為 bestguess。可使用的值如下：
  • bestguess (預設) 表示傳回的 duration_in_traffic 應是最準確的預估交通時間 (根據歷來路況和即時車流量兩者的已知相關資訊計算而得)。departureTime 距離現在的時間越近，即時車流量的影響力就越大。
  • pessimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際交通時間長，但偶爾路況特別差時，實際交通時間可能會超過這個值。
  • optimistic 表示傳回的 duration_in_traffic 在大多數日子應該都會比實際交通時間短，但偶爾路況特別好時，實際交通時間可能會短於這個值。

注意：如果不指定出發時間，系統會根據路網及與時間無關的平均路況來選擇路線和時間，不會考量目前路況。因此，路線可能會包含暫時封閉的道路。受到路網變動、平均路況更新，以及這項服務的分散性質影響，特定要求的結果可能會隨時間而改變。此外，在時間或頻率都沒有限制的情況下，即使兩條路線幾乎相同，結果還是有可能不同。

注意：為確保要求使用即時車流量資訊，請將 departureTime 設為現在。使用車流量資訊的要求會以較高的費率計費。 進一步瞭解 Google 地圖平台產品的計費方式。

以下是行車路線的 DirectionsRequest 範例：

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

單位系統

根據預設，路線規劃服務會使用起點國家/地區的單位系統來計算並顯示結果 (注意：在預設情況下，使用經緯度座標而非地址形式表示起點時，一律採用公制單位)。例如，從「伊利諾州芝加哥」到「安大略省多倫多」的路線會以英里顯示結果，但回程路線會以公里顯示結果。只要使用以下其中一個 UnitSystem 值，在要求中明確設定單位，即可覆寫此單位系統：

• UnitSystem.METRIC 會指定使用公制系統。系統會使用公里來顯示距離。
• UnitSystem.IMPERIAL 會指定使用英制系統。系統會使用英里來顯示距離。

注意：此單位系統設定只會影響向使用者顯示的文字。路線規劃結果也會包含一律以公尺表示的距離「值」，但不會向使用者顯示。

路線規劃的區域自訂調整

Google Maps API 路線規劃服務會根據網域 (國家/地區) 傳回地址結果，這些網域是指您載入 JavaScript Bootstrap 的網域 (多數使用者會載入 https://maps.googleapis.com/，因此網域會預設為美國)。如果您從另一個支援的網域載入 Bootstrap，收到的結果將受到該網域的影響。例如，在載入 https://maps.googleapis.com/ (美國) 的應用程式中搜尋「San Francisco」傳回的結果，會與在載入 http://maps.google.es/ (西班牙) 的應用程式中進行搜尋所傳回的結果不同。

您也可以使用 region 參數，讓路線規劃服務只傳回特定區域的結果。這個參數會指定區碼，採用兩位字元 (非數字) 萬國碼 (Unicode) 區域子標記。在大多數情況下，這些標記會直接對應到 ccTLD (「頂層網域」) 的兩位字元值，例如「co.uk」的「uk」。而在某些情況下，region 標記也支援 ISO-3166-1 代碼，這些代碼有時會與 ccTLD 值不同 (例如「GB」代表「Great Britain」)。

使用 region 參數時的注意事項如下：

• 請只指定一個國家/地區。如果超過一個，除了會遭到忽略以外，還可能會導致要求失敗。
• 請只使用兩位字元區域子標記 (萬國碼 (Unicode) CLDR 格式)，所有其他輸入內容都會造成錯誤。

區域自訂調整僅適用於支援路線規劃服務的國家/地區。請參閱 Google 地圖平台涵蓋範圍詳細資料，瞭解 Directions API 的全球涵蓋範圍。

呈現路線

使用 route() 方法向 DirectionsService 發出路線規劃要求時，您必須傳遞一個回呼，以便在完成服務要求後執行。這個回呼會在回應中傳回 DirectionsResult 和 DirectionsStatus 代碼。

路線規劃查詢狀態

DirectionsStatus 可能會傳回下列值：

• OK 表示回應包含有效的 DirectionsResult。
• NOT_FOUND 表示在要求的起點、目的地或路線控點中，有至少一個指定地點無法進行地理編碼處理。
• ZERO_RESULTS 表示系統在起點和目的地之間找不到路線。
• MAX_WAYPOINTS_EXCEEDED 表示 DirectionsRequest 中提供的 DirectionsWaypoint 欄位過多。請參閱下文，瞭解路線控點的限制。
• MAX_ROUTE_LENGTH_EXCEEDED 表示要求的路線過長，無法處理。系統傳回更複雜的路線時，就會發生這項錯誤。請嘗試減少路線控點、轉彎或指示的數量。
• INVALID_REQUEST 表示提供的 DirectionsRequest 無效。這個錯誤代碼最常見的原因，是要求中缺少起點或目的地，或是大眾運輸要求包含路線控點。
• OVER_QUERY_LIMIT 表示在允許的時間範圍內，網頁傳送過多要求。
• REQUEST_DENIED 表示系統拒絕網頁使用路線規劃服務。
• UNKNOWN_ERROR 表示伺服器發生錯誤，無法處理路線規劃要求。如果再試一次，要求可能會成功。

您應該檢查這個值，確認路線規劃查詢傳回有效的結果，接著再處理結果。

顯示 DirectionsResult

DirectionsResult 包含路線規劃查詢結果，您可以自行處理這些結果，或將結果傳遞至 DirectionsRenderer 物件，該物件會自動在地圖上處理並顯示結果。

如要使用 DirectionsRenderer 顯示 DirectionsResult，您必須執行下列操作：

1. 建立 DirectionsRenderer 物件。
2. 在轉譯器上呼叫 setMap()，將此函式繫結到傳遞的地圖中。
3. 在轉譯器上呼叫 setDirections()，向此函式傳遞前述的 DirectionsResult。轉譯器為 MVCObject，因此可自動偵測其中屬性的任何變更，然後在相關聯的路線有異動時更新地圖。

以下範例會計算「66 號公路」上兩個地點之間的路線，其中起點和目的地會設定為下拉式清單中指定的 "start" 和 "end" 值。DirectionsRenderer 會負責顯示指定地點之間的折線，並在起點、目的地和任何路線控點上放置標記 (如有)。

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

在 HTML 內文中：

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

查看範例

以下範例顯示使用不同交通工具的路線，路線為加州舊金山的海特艾許伯里前往大洋灘︰

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

在 HTML 內文中：

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

查看範例

DirectionsRenderer 不僅可負責顯示折線和任何相關聯的標記，還可透過一系列步驟顯示文字路線。如要執行此作業，方法是在 DirectionsRenderer 上呼叫 setPanel()，然後向此函式傳遞用於顯示這項資訊的 <div>。這樣做還可確保顯示正確的版權資訊，以及與結果相關的任何警告。

提供文字路線時，系統會使用瀏覽器的偏好語言設定，或使用您以 language 參數載入 API JavaScript 時所指定的語言 (詳情請參閱本地化)。在大眾運輸路線中，顯示的時間會以大眾運輸站點所在的時區為準。

以下範例與上述範例相同，不同之處在於以下範例包含顯示路線的 <div> 面板：

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

在 HTML 內文中：

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

查看範例

DirectionsResult 物件

向 DirectionsService 傳送路線規劃要求時，您會收到回應，其中包含狀態碼和結果 (即 DirectionsResult 物件)。DirectionsResult 為物件常值，包含下列欄位：

• geocoded_waypoints[] 包含 DirectionsGeocodedWaypoint 物件的陣列，每個物件皆包含起點、目的地和路線控點地理編碼的詳細資料。
• routes[] 包含 DirectionsRoute 物件的陣列。每條路線都指出要如何從起點到達目的地的方法 (由 DirectionsRequest 提供)。一般來說，除非將要求的 provideRouteAlternatives 欄位設為 true，才會傳回多條路線，否則每個指定的要求都僅會傳回一條路線。

注意：替代路線中的 via_waypoint 屬性已淘汰。3.27 版是最新版 API，可在替代路線中新增額外的路線控點。針對 3.28 以上版本的 API，您可以停用替代路線的拖曳功能，繼續使用路線規劃服務導入可拖曳的路線。只有主要路線可拖曳。使用者可以拖曳主要路線，直到該路線與替代路線相符為止。

經過地理編碼的路線控點

DirectionsGeocodedWaypoint 包含起點、目的地和路線控點地理編碼的詳細資料。

DirectionsGeocodedWaypoint 為物件常值，包含下列欄位：

• geocoder_status 表示地理編碼作業產生的狀態碼。這個欄位可能包含的值如下：
  • "OK" 表示沒有發生任何錯誤。地址剖析成功，且系統傳回至少一組地理編碼。
  • "ZERO_RESULTS" 表示地理編碼成功，但沒有傳回任何結果。如果地理編碼器收到不存在的 address，就有可能發生這種情況。

• partial_match 指出地理編碼器沒有傳回與原始要求完全相符的結果，但可以比對部分要求的地址。建議您檢查原始要求，確認是否有拼寫錯誤和/或不完整的地址。

  出現部分相符結果的最常見原因，是系統在要求中傳遞的縣市內找不到街道地址。如果要求比對同一個縣市內的兩個或更多地點，也可能會傳回部分相符的結果。舉例來說，「Hillpar St, Bristol, UK」會傳回 Henry Street 和 Henrietta Street 這兩項部分相符的結果。請注意，如果要求包含拼寫錯誤的地址元件，地理編碼服務可能就會建議使用替代地址。透過這種方式觸發的建議，也會標示為部分相符。

• place_id 是地點的專屬 ID，可與其他 Google API 搭配使用。舉例來說，您可以搭配 Google Places API 程式庫使用 place_id，以取得當地商家的詳細資料，例如電話號碼、營業時間和使用者評論等等。請參閱地點 ID 總覽。
• types[] 是一個陣列，用來指出傳回結果的「類型」。這個陣列不含任何標記或包含一個以上標記的組合，用於識別結果中傳回的地圖項目類型。舉例來說，「台北」的地理編碼會傳回「縣市」，指出「台北」是一個城市，並傳回「政治」，指出這是一個政治實體。

導航路線

注意：舊版 DirectionsTrip 物件已重新命名為 DirectionsRoute。請注意，路線現在是指從起點到終點的整段旅程，而不只是整個行程中的一段。

DirectionsRoute 包含從指定起點到目的地的一項結果。路線可能包含一個以上的路段 (類型為 DirectionsLeg)，視路線中是否指定任何路線控點而定。同樣地，路線也包含版權和警告資訊，因此顯示路線資訊時，您必須向使用者顯示這些資訊。

DirectionsRoute 為物件常值，包含下列欄位：

• legs[] 包含 DirectionsLeg 物件的陣列，其中的每個物件都包含指定路線中，兩個地點之間路線的路段相關資訊。每指定一個路線控點或目的地時，就會有一個不同的路段 (沒有路線控點的路線只會包含一個 DirectionsLeg)。每個路段包含一系列的 DirectionStep。
• waypoint_order 包含一個陣列，表示計算的路線中任何路線控點的順序。如果向 DirectionsRequest 傳遞 optimizeWaypoints: true，則此陣列包含的順序可能經過調整。
• overview_path 包含 LatLng 的陣列，用來表示導航路線的近似 (順暢) 路徑。
• overview_polyline 包含單一 points 物件，其中包含路線的編碼折線表示法。這條折線是導航路線的近似 (順暢) 路徑。
• bounds 包含 LatLngBounds，表示指定路線中的折線範圍。
• copyrights 包含這條路線中要顯示的版權文字。
  注意：如果您沒有使用提供的 DirectionsRenderer 物件，就必須自行處理並顯示這項資訊。
• warnings[] 包含警告的陣列，以供在顯示導航路線時同時顯示。如果您沒有使用提供的 DirectionsRenderer 物件，就必須自行處理並顯示這些警告。
• fare 包含這條路線的總車資 (也就是總票價)。這個屬性只會針對大眾運輸要求傳回，且僅適用於所有大眾運輸路段皆有車資資訊的路線。這些資訊包括：
  • currency：ISO 4217 貨幣代碼，表示金額採用的貨幣。
  • value：總車資金額，以上方指定的貨幣為單位。

導航路段

注意：舊版 DirectionsRoute 物件已重新命名為 DirectionsLeg。

在計算的路線中，DirectionsLeg 代表從起點到目的地之間的一個旅程路段。如果路線沒有任何路線控點，路線只會包含一個「路段」，但如果路線定義一個以上的路線控點，路線會包含一或多個路段，對應旅程中的特定路段。

DirectionsLeg 為物件常值，包含下列欄位：

• steps[] 包含 DirectionsStep 物件的陣列，表示旅程路段中每個不同步驟的相關資訊。

• distance 表示這個路段所涵蓋的總距離，會以下列格式的 Distance 物件表示：

  • value 表示距離 (以公尺為單位)
  • text 包含以字串形式表示的距離，根據預設，顯示的單位與起點使用的單位相同 (例如，美國境內的任何起點都會使用英里做為單位)。您可以在原始查詢中明確設定 UnitSystem，覆寫這個單位系統。請注意，無論使用何種單位系統，distance.value 欄位的值一律會使用公尺做為單位。

  如果沒有距離資訊，就無法定義這些欄位。

• duration 表示這個路段所需的總時間，會以下列格式的 Duration 物件表示：

  • value 表示所需時間 (以秒為單位)。
  • text 包含以字串形式表示的所需時間。

  如果沒有所需時間資訊，就無法定義這些欄位。

• duration_in_traffic 表示在考量目前路況的情況下，這個路段所需的總時間。只有符合下列所有條件時，系統才會傳回 duration_in_traffic：

  • 要求不含行經停靠點的路線控點。也就是說，不包含 stopover 為 true 的路線控點。
  • 專為行車路線發出的要求，也就是 mode 設為 driving。
  • 要求中的 drivingOptions 欄位會納入 departureTime。
  • 要求的路線可提供路況。

  duration_in_traffic 包含下列欄位：

  • value 表示所需時間 (以秒為單位)。
  • text 包含所需時間 (清楚易懂的表示法)。
• arrival_time 包含這個路段的預計到達時間。只有大眾運輸路線才會傳回這個屬性。結果會以 Time 物件的形式傳回，其中包含三個屬性：
  • value 表示時間，以 JavaScript Date 物件的形式指定。
  • text 表示時間，以字串的形式指定。顯示的時間以大眾運輸站點所在的時區為準。
  • time_zone 包含這個站點所在的時區。這個值是時區名稱 (如 IANA 時區資料庫中所定義)，例如「America/New_York」。
• departure_time 包含這個路段的預計出發時間，以 Time 物件的形式指定。departure_time 僅適用於大眾運輸路線。
• start_location 包含這個路段的起點 LatLng。路線規劃網路服務在計算地點之間的路線時，會使用距離起點和終點最近的交通選項 (通常是道路)，因此 start_location 可能與這個路段的起點不同 (例如道路不位於起點附近)。
• end_location 包含這個路段的目的地 LatLng。DirectionsService 在計算地點之間的路線時，會使用距離起點和終點最近的交通選項 (通常是道路)，因此 end_location 可能和這個路段的目的地不同 (例如道路不位於目的地附近)。
• start_address 包含這個路段起點的清楚易懂地址 (通常是街道地址)。
  
  這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。
• end_address 包含這個路段終點的清楚易懂地址 (通常是街道地址)。
  
  這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。

導航步驟

DirectionsStep 是導航路線中最小的組成單位，其中包含單一步驟，用來描述旅程中某條具體指示。例如：「在自由路向左轉」。步驟不僅描述指示，也提供距離和所需時間相關資訊，說明目前步驟和下個步驟之間的關係。例如，在步驟「併入國道六號」中，可能包含「37 公里」和「40 分鐘」的所需時間，表示從目前步驟到下個步驟的所需時間為 37 公里/40 分鐘。

當您使用路線規劃服務搜尋大眾運輸路線時，步驟陣列還會包含以 transit 物件形式表示的額外大眾運輸專屬資訊。如果路線規劃包含多種交通方式，系統就會在 steps[] 陣列中提供步行或行車步驟的詳細路線。舉例來說，步行步驟會包含從開始到結束地點的路線指示：「從火車站步行到 228 公園」。這個步驟會在 steps[] 陣列中包含該路線的詳細步行路線，例如：「向左轉，朝館前路前進」、「請於襄陽路向左轉」以及「請於公園路向右轉」。

DirectionsStep 為物件常值，包含下列欄位：

• instructions 包含目前步驟的指示，以文字字串表示。
• distance 包含目前步驟到下個步驟所涵蓋的距離，以 Distance 物件表示 (請參閱上方的 DirectionsLeg 說明)。如果沒有距離資訊，就無法定義這個欄位。
• duration 包含執行目前步驟直到下個步驟的預計所需時間，以 Duration 物件表示 (請參閱上方的 DirectionsLeg 說明)。如果沒有時間資訊，就無法定義這個欄位。
• start_location 包含目前步驟中經過地理編碼的起點 LatLng。
• end_location 包含目前步驟中的終點 LatLng。
• polyline 包含單一 points 物件，其中包含步驟的編碼折線表示法。這條折線是步驟的近似 (順暢) 路徑。
• steps[] 是 DirectionsStep 物件常值，包含大眾運輸路線中步行或行車步驟的詳細路線。只有大眾運輸路線才會提供子步驟。
• travel_mode 包含目前步驟中使用的 TravelMode。大眾運輸路線可以結合步行和大眾運輸路線。
• path 包含 LatLngs 陣列，用於說明目前步驟的過程。
• transit 包含大眾運輸專屬資訊，例如抵達和出發時間，以及大眾運輸路線名稱。

大眾運輸專屬資訊

大眾運輸路線會傳回與其他交通方式無關的額外資訊。這些額外屬性會透過 TransitDetails 物件顯示，並以 DirectionsStep 的屬性傳回。您可以透過 TransitDetails 物件，取得 TransitStop、TransitLine、TransitAgency 和 VehicleType 物件的額外資訊，如下所述。

大眾運輸詳細資料

TransitDetails 物件會顯示下列屬性：

• arrival_stop 包含 TransitStop 物件，表示內含下列屬性的抵達車站/站點：
  • name 轉運站/站點的名稱。例如：「光復廣場」。
  • location 轉運站/站點的地點，以 LatLng 表示。
• departure_stop 包含代表出發車站/站點的 TransitStop 物件。
• arrival_time 包含抵達時間，以 Time 物件形式指定，內涵下列三個屬性：
  • value 表示時間，以 JavaScript Date 物件的形式指定。
  • text 表示時間，以字串的形式指定。顯示的時間以大眾運輸站點所在的時區為準。
  • time_zone 包含這個站點所在的時區。這個值是時區名稱 (如 IANA 時區資料庫中所定義)，例如「America/New_York」。
• departure_time 包含出發時間，以 Time 物件的形式指定。
• headsign 指定這條路線的行進方向，如交通工具或出發站上所標示的方向。這通常是終點站。
• headway (如果有提供) 指定從目前同一站點出發的預計間隔秒數。例如，假設 headway 的值為 600，則表示如果錯過上一班公車，下一班預計要等 10 分鐘。
• line 包含 TransitLine 物件常值，其中含有目前步驟中使用的大眾運輸路線相關資訊。TransitLine 提供路線的名稱和運輸公司，以及 TransitLine 參考文件中描述的其他屬性。
• num_stops 包含目前步驟中的停靠站數量，其中包含抵達站，但不包含出發站。例如，假設您的路線是從 A 站出發，途經 B、C 兩站，最後抵達 D 站，則 num_stops 會傳回 3。

大眾運輸路線

TransitLine 物件會顯示下列屬性：

• name 包含這條大眾運輸路線的全名。例如，「指南客運」或「台北捷運」。
• short_name 包含這條大眾運輸路線的簡稱。通常是一個路線編號，例如「板南線」或「237」。
• agencies 是包含單一 TransitAgency 物件的陣列。TransitAgency 物件提供路線的運輸公司相關資訊，其中包含下列屬性：
  • name 包含運輸公司的名稱。
  • phone 包含運輸公司的電話號碼。
  • url 包含運輸公司的網址。

  重要資訊：如果您要手動呈現大眾運輸路線，而不使用 DirectionsRenderer 物件，請務必顯示行程結果中提供服務的運輸公司名稱和網址。

• url 包含這條大眾運輸路線的網址 (由運輸公司提供)。
• icon 包含這條路線相關圖示的網址。大多數城市會使用按照不同交通工具類型設計的通用圖示，而部分大眾運輸路線 (例如紐約地鐵系統) 會有該路線專用的圖示。
• color 包含這條路線常用的顏色，以十六進位字串的形式指定，例如 #FF0033。
• text_color 包含這條路線常用的文字顏色，以十六進位字串的形式指定。
• vehicle 包含 Vehicle 物件，其中含有下列屬性：
  • name 包含這條路線的交通工具名稱。例如：「捷運」。
  • type 包含這條路線使用的交通工具類型。如需支援的值完整清單，請參閱交通工具類型說明文件。
  • icon 包含此交通工具類型常用圖示的網址。
  • local_icon 包含此交通工具類型相關圖示的網址 (根據本地交通標誌)。

交通工具類型

VehicleType 物件會顯示下列屬性：

值	定義
VehicleType.RAIL	火車。
VehicleType.METRO_RAIL	輕軌電車運輸。
VehicleType.SUBWAY	地下輕軌電車。
VehicleType.TRAM	地上輕軌電車。
VehicleType.MONORAIL	單軌電車。
VehicleType.HEAVY_RAIL	重軌電車。
VehicleType.COMMUTER_TRAIN	通勤鐵路。
VehicleType.HIGH_SPEED_TRAIN	高速火車。
VehicleType.BUS	公車。
VehicleType.INTERCITY_BUS	城際巴士。
VehicleType.TROLLEYBUS	無軌電車。
VehicleType.SHARE_TAXI	共乘計程車可視為一種公車，可供乘客沿路任意上下車。
VehicleType.FERRY	渡輪。
VehicleType.CABLE_CAR	靠電纜運作的交通工具，通常在地面上行駛。空中纜車可視為 VehicleType.GONDOLA_LIFT 類型。
VehicleType.GONDOLA_LIFT	空中纜車。
VehicleType.FUNICULAR	靠電纜從陡坡往上拉升的交通工具。纜索鐵路通常由兩個車廂組成，兩個車廂彼此保持平衡。
VehicleType.OTHER	所有其他交通工具都會傳回這個類型。

檢查 DirectionsResults

剖析任何路線規劃回應時，系統會檢查及使用 DirectionsResults 元件 (包括 DirectionsRoute、DirectionsLeg、DirectionsStep 和 TransitDetails)。

重要資訊：如果您要手動呈現大眾運輸路線，而不使用 DirectionsRenderer 物件，請務必顯示行程結果中提供服務的運輸公司名稱和網址。

以下範例規劃前往紐約市內特定旅遊景點的步行路線。我們會檢查路線的 DirectionsStep，為每個步驟新增標記，然後將資訊附加到 InfoWindow，其中包含該步驟的指示文字。

注意：我們計算的是步行路線，因此也會在另一個 <div> 面板中向使用者顯示任何警告。

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

在 HTML 內文中：

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

查看範例

使用路線上的路線控點

注意：如果要求使用超過 10 個路線控點或路線控點最佳化，系統會以較高的費率計費。 進一步瞭解 Google 地圖平台產品的計費方式。

如同 DirectionsRequest 中所述，在使用路線規劃服務計算步行、單車或行車路線時，您也可以指定「路線控點」(類型為 DirectionsWaypoint)。大眾運輸路線無法使用路線控點。您可以運用路線控點計算行經其他地點的路線，因此傳回的路線會通過指定的路線控點。

waypoint 包含下列欄位：

• location (必要) 指定路線控點的地址。
• stopover (選用) 指出這個路線控點是否為路線上的實際停靠點 (true)，或只是偏好經過的指定地點 (false)。停靠點預設為 true。

注意：將 stopover 設為 false 來避免行經停靠點，會導致路線對路線控點的解釋過於嚴格。這可能會導致路線嚴重繞路，或者，如果路線規劃服務無法建立行經該點的路線，回應狀態碼可能會傳回 ZERO_RESULTS。

在預設情況下，路線規劃服務會依指定的路線控點順序計算路線。或者，您可以選擇在 DirectionsRequest 中傳送 optimizeWaypoints: true，如此一來，路線規劃服務就能透過更有效率的順序調整路線控點，規劃出最佳路線 (這項最佳化做法是旅行推銷員問題的實際應用)。交通時間是最佳化的主要因素，但在判斷哪條路線最有效率時，系統也會將距離、轉彎次數和許多其他因素納入考量。所有路線控點都必須為停靠點，路線規劃服務才能進行路線最佳化。

如果您指示路線規劃服務進行路線控點順序最佳化，系統會在 DirectionsResult 物件的 waypoint_order 欄位中傳回這些順序。

以下範例使用各種起點、終點和路線控點，計算橫越美國的路線 (如要選取多個路線控點，在清單中選取項目時，請按下 Ctrl 鍵 + 滑鼠左鍵)。請注意，我們會檢查 routes.start_address 和 routes.end_address，以取得每條路線的起點和終點文字資訊。

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

注意：請參閱這份指南，瞭解如何在 Google 地圖上使用 TypeScript。

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

路線控點的限制和上限

請務必遵守下列用量限制和上限：

• 在 Maps JavaScript API 中使用路線規劃服務時，最多可包含 25 個路線控點，再加上起點和目的地。Directions API 網路服務的限制也相同。
• 在 Directions API 網路服務 中，客戶可以使用 25 個路線控點，再加上起點和目的地。
• Google 地圖平台付費方案客戶可以使用 25 個路線控點，再加上起點和目的地。
• 大眾運輸路線不支援路線控點。

可拖曳的路線

如果顯示的單車、步行或行車路線為「可拖曳」路線，使用者便可使用 DirectionsRenderer 動態修改這些路線。這樣一來，使用者就能點選並拖曳地圖上產生的路徑，藉此選取及調整路線。您也可將轉譯器的 draggable 屬性設為 true，指定轉譯器顯示可拖曳的路線。大眾運輸路線無法設定為可拖曳的路線。

只要是可拖曳的路線，使用者即可選取結果路徑上的任一點 (或路線控點)，將指定元件移至新的位置。系統會動態更新 DirectionsRenderer，以顯示修改後的路徑。修改後的路徑出現後，系統會在地圖上新增一個精簡路線控點 (以白色小標記表示)。選取並移動路徑區段會變更路線中的該路段，選取並移動路線控點標記 (包括起點與終點) 則會變更在路線中通過該路線控點的路段。

可拖曳的路線是由用戶端進行修改與呈現，因此建議您監控及處理 DirectionsRenderer 上的 directions_changed 事件，以便在使用者修改顯示的路線時收到通知。

下列程式碼顯示的行程起點為澳洲西岸的伯斯，終點為東岸的雪梨。程式碼會監控 directions_changed 事件，以更新旅程中所有路段的總距離。

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

注意：請參閱這份指南，瞭解如何在 Google 地圖上使用 TypeScript。

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js

注意：JavaScript 是從 TypeScript 程式碼片段編譯而成。

查看範例

測試範例程式碼

JSFiddle.net Google Cloud Shell