總覽

透過集合功能整理內容 你可以依據偏好儲存及分類內容。
選取平台: Android iOS JavaScript

Maps JavaScript API 可讓您利用自己的內容和圖像自訂地圖,以便在網頁和行動裝置上顯示。Maps JavaScript API 提供四種基本地圖類型 (藍圖、衛星、混合式和地形),您可以使用圖層和樣式、控制項和事件,以及各種服務和程式庫進行修改。

觀眾

本說明文件的適用對象為熟悉 JavaScript 程式設計和物件導向程式設計概念的使用者。您還應該熟悉 Google 地圖 (從使用者的角度出發)。網路上有許多 JavaScript 教學課程

本概念說明文件旨在協助您快速上手,運用 Maps JavaScript API 探索及開發應用程式。我們也發布了 Maps JavaScript API 參考資料

Hello, World

如要開始瞭解 Maps JavaScript API,最簡單的方法就是查看簡易範例。下方範例顯示了以澳洲新南威爾斯雪梨雪梨的地圖為中心。

TypeScript

let map: google.maps.Map;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

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

JavaScript

let map;

function initMap() {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

window.initMap = initMap;

CSS

/* 
 * 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;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
查看範例

查看範例

就算這只是一個簡易範例,仍有幾個地方需要注意:

  1. 我們使用 <!DOCTYPE html> 宣告,將應用程式宣告為 HTML5。
  2. 我們建立名為「quot;map」的 div 元素來存放地圖。
  3. 我們在 div 中定義了建立地圖的 JavaScript 函式。
  4. 我們使用 script 標記載入 Maps JavaScript API。

這些步驟說明如下:

將應用程式宣告為 HTML5

建議您在網頁應用程式中宣告實際的 DOCTYPE。在本範例中,我們使用簡易 HTML5 DOCTYPE 將應用程式宣告為 HTML5,如下所示:

<!DOCTYPE html>

多數瀏覽器會在「標準模式」中轉譯這個 DOCTYPE 宣告的內容,這表示應用程式應更符合跨瀏覽器相容性。DOCTYPE 也設計成會逐漸降級,不瞭解它的瀏覽器就會忽略,並使用「quirks 模式」顯示其內容。

請注意,有些在快速模式下運作的 CSS 在標準模式下無效。具體來說,所有以百分比為基礎的大小都必須沿用父項區塊元素,而且如果任何上階無法指定大小,系統就會假設大小為 0 x 0 像素。因此,我們包含下列 <style> 宣告:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

此 CSS 宣告表示地圖容器 <div> (ID 為 map) 應佔 HTML 主體高度的 100%。請注意,您也必須針對 <body><html> 明確宣告這些百分比。

載入 Maps JavaScript API

Maps JavaScript API 是以 script 標記載入,可用來在 HTML 檔案中以內嵌方式加入,或使用獨立的 JavaScript 檔案動態新增。建議您同時查看這兩個方法,然後選擇最適合您專案程式碼結構的最佳方法。

內嵌載入

如要在 HTML 檔案中內嵌 Maps Maps API,請新增 script 標記,如下所示。

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

動態載入

如要使用單獨的 JavaScript 檔案以動態方式載入 Maps JavaScript API,請參閱下方範例。這個方法可讓您從獨立的 .js 檔案處理所有要用於 API 的程式碼,等同於內嵌指令碼指令碼。

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

動態載入

您也能使用 @googlemaps/js-api-load 套件,提供更流暢的動態載入體驗。可透過 NPM 安裝,如下所示:

npm install @googlemaps/js-api-loader

這個套件可透過以下方式匯入應用程式:

import { Loader } from "@googlemaps/js-api-loader"

載入器會呈現 Promise 和回呼介面。下列示範如何使用預設 Promise 方法 load()

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

指令碼標記屬性

請注意,在上述範例中,建議在 script 標記上設定多個屬性 (建議使用)。以下是每個屬性的說明。

  • src:載入 Maps JavaScript API 的網址,包括使用 Maps JavaScript API 所需的所有符號和定義。 此示例中的網址有兩個參數:key,也就是提供 API 金鑰,callback 則可讓您指定 Maps JavaScript API 載入完成時要呼叫的全域函式名稱。進一步瞭解網址參數
  • async:要求瀏覽器以非同步方式下載並執行指令碼。執行指令碼時,系統會使用 callback 參數呼叫指定的函式。

程式庫

透過網址載入 Maps JavaScript API 時,您也可以選擇使用 libraries 網址參數載入其他程式庫。程式庫是程式碼的模組,可為主要 Maps JavaScript API 提供額外功能,但除非您明確要求,否則無法載入。詳情請參閱 Maps JavaScript API 中的程式庫

同步載入 API

在載入 Maps JavaScript API 的 script 標記中,您可以省略 defer 屬性和 callback 參數。否則 API 會載入,直到載入 API 為止。

這可能會導致網頁載入的速度變慢。但假設 API 已載入,您可以撰寫後續的指令碼標記。

地圖 DOM 元素

<div id="map"></div>

我們必須在地圖上保留地圖,才能讓地圖顯示。常見的做法是建立已命名的 div 元素,並在瀏覽器的文件物件模型 (DOM) 中取得此元素的參照。

在上述範例中,我們使用 CSS 將地圖 div 的高度設為「100%」。這會配合行動裝置的大小展開。您可能需要根據瀏覽器的螢幕大小和邊框間距調整寬度和高度值。請注意,div 通常會從其包含的元素中擷取寬度,而空白的 div 通常有 0 的高度。因此,您必須一律在 <div> 上明確設定高度。

地圖選項

每個地圖都有兩個必要選項:centerzoom

map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

縮放等級

顯示地圖的初始解析度是由 zoom 屬性所設定,其中縮放等級 0 會對應至完全縮小的地球地圖,而較大的縮放等級會以較高的解析度放大。

zoom: 8

如果要提供整個地球地圖做為單一圖片,就必須使用龐大的地圖,或是解析度很低的小型地圖。因此,Google 地圖和 Maps JavaScript API 中的地圖圖片會細分為「圖塊」和「縮放等級」。低縮放等級時,有一組小型地圖圖塊涵蓋大範圍的區域;縮放等級較高的時,圖塊會具備較高的解析度,且會涵蓋較小的區域。以下清單列出各縮放等級大致可顯示的精細程度:

  • 1:全世界
  • 5:自然景觀/大陸
  • 10:城市
  • 15:街道
  • 20:建築

下方三個圖片顯示東京的相同位置,縮放等級為 0、7 和 18。

如要進一步瞭解 Maps JavaScript API 如何依據目前的縮放等級載入圖塊,請參閱地圖和圖塊座標指南。

地圖物件

map = new google.maps.Map(document.getElementById("map"), {...});

代表地圖的 JavaScript 類別為 Map 類別。此類別的物件會定義網頁上的單一地圖 (您可以為這個類別建立多個例項,每個物件都會在網頁上定義一個地圖)。我們會使用 JavaScript new 運算子來將這個類別的新例項建立。

建立新的地圖例項時,您必須在網頁中指定 <div> HTML 元素做為地圖的容器。HTML 節點是 JavaScript document 物件的子項,而我們經由 document.getElementById() 方法取得這個元素的參照。

這個程式碼會定義變數 (名稱為 map),並將該變數指派給新的 Map 物件。函式 Map() 稱為建構函式,其定義如下:

建構函式 說明
Map(mapDiv:Node, opts?:MapOptions ) 使用任何傳遞的 (選用) 參數,在指定的 HTML 容器 (通常是 DIV 元素) 中建立新地圖。

疑難排解

API 金鑰和帳單錯誤

在某些情況下,地圖顏色可能會變得比較深 (有點像「'excluded'街景服務圖片」浮水印並標示「僅供開發使用」)。這通常代表有 API 金鑰或帳單方面的問題。 如要使用 Google 地圖平台產品,您的帳戶必須啟用計費功能,且所有要求一律應包含有效的 API 金鑰。下列流程可協助您排解這個問題:

如果程式碼無法運作:

為協助您順利設定地圖程式碼,Brendan Kenny 和 Mano Marks 明確指出了一些常見錯誤,以及如何在這部影片中修正這個問題。

  • 檢查是否有錯字。請注意,JavaScript 有大小寫之分。
  • 檢查基本概念 - 初始地圖建立過程中最常見的問題。例如:
    • 確認您已在地圖選項中指定 zoomcenter 屬性。
    • 確認您已宣告即將在螢幕上顯示 div 元素的 div 元素。
    • 確認地圖的 div 元素已設定高度。根據預設,div 元素建立高度為 0,因此為不可見。
    請參閱參照實作的範例。
  • 使用 JavaScript 偵錯工具找出問題,例如 Chrome 開發人員工具中的問題。請先透過 JavaScript 控制台找出錯誤。
  • Stack Overflow 上張貼問題。請參閱支援頁面,瞭解如何張貼優質問題。