您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

幾何圖形程式庫媒體庫

  1. 總覽
  2. 球體幾何圖形概念
    1. 距離與面積函數
    2. 瀏覽函數
  3. 幾何圖形編碼
  4. 多邊形與折線函數
    1. containsLocation()
    2. isLocationOnEdge()

總覽

本文件內的概念將參照僅在 google.maps.geometry 程式庫內提供的功能。此程式庫預設不會在您載入 Maps Javascript API 時載入,而是必須使用 libraries 自舉參數明確指定。

如需詳細資訊,請參閱程式庫總覽

Google Maps JavaScript API 幾何圖形程式庫提供公用函數,計算地球表面上的幾何資料。此程式庫包含三個命名空間:

  • spherical 包含球體幾何圖形公用程式,讓您以緯度和經度計算角度、距離和面積。
  • encoding 包含針對折線路徑進行編碼和解碼的公用程式,這些程式採用編碼折線演算法
  • poly 包含公用函數,以進行多邊形和折線的計算。

google.maps.geometry 程式庫不包含任何類別,而是包含上述命名空間上的靜態方法。

球體幾何圖形概念

Google Maps JavaScript API 內的影像是二維空間的「平面」。然而,地球是三維空間,並通常以扁球體或單純的球體來呈現。在 Maps API 內,我們使用球面。為了用二維的平坦表面 (像是您的電腦螢幕) 來表示地球,Maps API 使用了投影

在二維投影中,外觀有時並非如表面所示。因為地圖投影必須進行一些變形,所以單純的歐幾里得幾何圖形通常並不適用。例如,球體上兩點之間最短的距離不是直線,而是一個大圓 (一種測地線),而構成球體表面上三角形的角度總合將會超過 180 度。

因為這些差異,球體 (或其投影) 上的幾何函數必須使用球體幾何圖形來計算如距離、方向和面積等建構。計算這些球體幾何建構的公用程式,包含於 Maps API 的 google.maps.geometry.spherical 命名空間內。這個命名空間提供計算球體座標(緯度和經度)之純量值的靜態方法。

距離與面積函數

兩點之間的距離是它們最短路徑的長度。此最短路徑被稱為測地線。在球體上,所有測地線都是大圓的區段。如果要計算這個距離,請呼叫 computeDistanceBetween(),並將兩個 LatLng 物件傳遞給它。

如果有好幾個位置,您可以改用 computeLength() 來計算指定路徑的長度。

距離的計算結果以公尺表示。

如果要計算多邊形區域的面積(以平方公尺為單位),請呼叫 computeArea(),並將定義閉合迴圈的 LatLng 物件陣列傳遞給它。

在球體上瀏覽時,「方向」為指向某個固定參照點(通常是正北)的方向角度。在 Google Maps API 內,「方向」是以與正北的角度來定義,也就是從正北 (0 度) 的順時針方向計算的角度。您可以使用 computeHeading() 方法,將兩個 fromtoLatLng 物件傳遞給它,來計算兩個位置之間的方向。

透過特定的方向、原始位置及行進距離(以公尺為單位),便可以使用 computeOffset() 來計算目的地的座標。

根據兩個 LatLng 物件及介於 0 到 1 之間的值,您也可以使用 interpolate() 方法來計算一個位於兩者之間的目的地,這將會在兩個位置之間進行球體線性插值法,結果值將指出沿著原點到目的地之路徑的行進分數距離。

下列範例會在您於地圖上按一下兩個點時建立兩個折線,一個是測地線,另一個則是連接兩個位置的「直線」,然後計算兩個點之間的行進方向:

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 34, lng: -40.605}
  });

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}
<div id="map"></div>
<div id="floating-panel">
  Origin: <input type="text" readonly id="origin">
  Destination: <input type="text" readonly id="destination"><br>
  Heading: <input type="text" readonly id="heading"> degrees
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#floating-panel {
  position: absolute;
  top: 10px;
  left: 25%;
  z-index: 5;
  background-color: #fff;
  padding: 5px;
  border: 1px solid #999;
  text-align: center;
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

var marker1, marker2;
var poly, geodesicPoly;

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 4,
    center: {lat: 34, lng: -40.605}
  });

  map.controls[google.maps.ControlPosition.TOP_CENTER].push(
      document.getElementById('info'));

  marker1 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 40.714, lng: -74.006}
  });

  marker2 = new google.maps.Marker({
    map: map,
    draggable: true,
    position: {lat: 48.857, lng: 2.352}
  });

  var bounds = new google.maps.LatLngBounds(
      marker1.getPosition(), marker2.getPosition());
  map.fitBounds(bounds);

  google.maps.event.addListener(marker1, 'position_changed', update);
  google.maps.event.addListener(marker2, 'position_changed', update);

  poly = new google.maps.Polyline({
    strokeColor: '#FF0000',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    map: map,
  });

  geodesicPoly = new google.maps.Polyline({
    strokeColor: '#CC0099',
    strokeOpacity: 1.0,
    strokeWeight: 3,
    geodesic: true,
    map: map
  });

  update();
}

function update() {
  var path = [marker1.getPosition(), marker2.getPosition()];
  poly.setPath(path);
  geodesicPoly.setPath(path);
  var heading = google.maps.geometry.spherical.computeHeading(path[0], path[1]);
  document.getElementById('heading').value = heading;
  document.getElementById('origin').value = path[0].toString();
  document.getElementById('destination').value = path[1].toString();
}

檢視範例 (geometry-headings.html)

編碼方法

Google Maps JavaScript API 內的路徑通常被指定為 LatLng 物件的 Array。不過,這類陣列通常過於龐大而不適合傳遞。您可以改用 Google 的折線編碼演算法來壓縮指定路徑,之後再透過解碼來解壓縮。

geometry 程式庫包含 encoding 命名空間,讓公用程式得以對折線進行編碼和解碼。

encodePath() 靜態方法能對指定路徑進行編碼。您可以傳遞 LatLng 陣列或 MVCArray (由 Polyline.getPath() 傳回)。

如果要對已編碼的路徑進行解碼,只需呼叫 decodePath() 並將編碼字串傳遞給該方法。

下列範例顯示密西西比州牛津的地圖。在地圖上按一下將能新增一個點到折線。折線建構時,它的編碼會在折線的下層出現。

// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}
<div id="map"></div>
<div id="right-panel">
  <div>Encoding:</div>
  <textarea id="encoded-polyline"></textarea>
</div>
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map {
  height: 100%;
  width: 50%;
  float: left;
}
#right-panel {
  width: 46%;
  float: left;
}
#encoded-polyline {
  height: 100px;
  width: 100%;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=geometry&callback=initMap"
    async defer></script>
// This example requires the Geometry library. Include the libraries=geometry
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=geometry">

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 14,
    center: {lat: 34.366, lng: -89.519}
  });
  var poly = new google.maps.Polyline({
    strokeColor: '#000000',
    strokeOpacity: 1,
    strokeWeight: 3,
    map: map
  });

  // Add a listener for the click event
  google.maps.event.addListener(map, 'click', function(event) {
    addLatLngToPoly(event.latLng, poly);
  });
}

/**
 * Handles click events on a map, and adds a new point to the Polyline.
 * Updates the encoding text area with the path's encoded values.
 */
function addLatLngToPoly(latLng, poly) {
  var path = poly.getPath();
  // Because path is an MVCArray, we can simply append a new coordinate
  // and it will automatically appear
  path.push(latLng);

  // Update the text field to display the polyline encodings
  var encodeString = google.maps.geometry.encoding.encodePath(path);
  if (encodeString) {
    document.getElementById('encoded-polyline').value = encodeString;
  }
}

檢視範例 (geometry-encodings.html)

多邊形與折線函數

幾何圖形程式庫的 poly 命名空間包含能判斷指定點是否位於多邊形或折線的內部或附近的公用函數。

containsLocation()

containsLocation(point:LatLng, polygon:Polygon)

如果要確認指定點是否落在多邊形內部,請將該點和多邊形傳遞至 google.maps.geometry.poly.containsLocation()。如果該點位於多邊形內部或其邊緣上,函數便會傳回「true」。

下面的程式碼會在使用者的點擊位置落在定義的三角形內時,將「true」寫入瀏覽器主控台,反之則寫入「false」。

function initialize() {
  var mapOptions = {
    zoom: 5,
    center: new google.maps.LatLng(24.886, -70.269),
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var bermudaTriangle = new google.maps.Polygon({
    paths: [
      new google.maps.LatLng(25.774, -80.190),
      new google.maps.LatLng(18.466, -66.118),
      new google.maps.LatLng(32.321, -64.757)
    ]
  });

  google.maps.event.addListener(map, 'click', function(event) {
    console.log(google.maps.geometry.poly.containsLocation(event.latLng, bermudaTriangle));
  });
}

google.maps.event.addDomListener(window, 'load', initialize);

此程式碼的另一個版本,會在使用者於地圖上的點擊位置落在百慕達三角洲內部時,繪製一個紅色圓圈,反之則繪製綠色圓圈:

檢視範例 (poly-containsLocation)

isLocationOnEdge()

isLocationOnEdge(point:LatLng, poly:Polygon|Polyline, tolerance?:number)

如果要判斷點是否落在多邊形內部或其附近,或落在多邊形的邊緣上面或其附近,請將點、折線/多邊形,以及以度數表示的公差值(選擇性),傳遞至 google.maps.geometry.poly.isLocationOnEdge()。如果該點與位於線條或邊緣上的最接近點之間的距離落在指定的公差值內,函數便會傳回「true」。預設公差值是 10-9 度。

function initialize() {
  var myPosition = new google.maps.LatLng(46.0, -125.9);

  var mapOptions = {
    zoom: 5,
    center: myPosition,
    mapTypeId: 'terrain'
  };

  var map = new google.maps.Map(document.getElementById('map'),
      mapOptions);

  var cascadiaFault = new google.maps.Polyline({
    path: [
      new google.maps.LatLng(49.95, -128.1),
      new google.maps.LatLng(46.26, -126.3),
      new google.maps.LatLng(40.3, -125.4)
    ]
  });

  cascadiaFault.setMap(map);

  if (google.maps.geometry.poly.isLocationOnEdge(myPosition, cascadiaFault, 10e-1)) {
    alert("Relocate!");
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁