總覽

選取平台: 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;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
查看範例

試用範例

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

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

這些步驟說明如下:

載入 Maps JavaScript API

Bootstrap 載入器是我們建議用來載入 Maps JavaScript API 的方式。您也可以使用 JS API 載入器做為替代方案。建議一併查看這兩個方法,然後選擇最適合您專案程式碼結構的方法。

詳情請參閱載入 Maps JavaScript API

Bootstrap 載入器

將內嵌 Bootstrap 載入器加進應用程式程式碼,即可載入 Maps JavaScript API,如以下程式碼片段所示:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

如要在執行階段載入程式庫,請使用 await 運算子從非同步函式中呼叫 importLibrary(),如下所示:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

NPM js-api-loader 套件

使用 @googlemaps/js-api-load,透過 NPM 載入 Maps JavaScript API。使用下列指令,即可透過 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

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

將應用程式宣告為 HTML5

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

<!DOCTYPE html>

目前多數瀏覽器會在「標準模式」中呈現使用此 DOCTYPE 宣告的內容,也就是說,您的應用程式應具有更高的跨瀏覽器相容性。此外,DOCTYPE 也設計成會優雅降級,但無法理解該宣告的瀏覽器會忽略宣告,而改為採用「相容模式」顯示內容。

請注意,有些在相容模式中可以運作的 CSS,在標準模式中卻無效。具體來說,所有百分比形式的尺寸都必須繼承上層區塊元素,但如果其中任一祖系無法指定尺寸,就會假設尺寸為 0 x 0 像素。基於這個理由,我們加入下列 <style> 宣告:

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

這個 CSS 宣告表示地圖容器 <div> (ID 為 map) 應佔 100% 的 HTML 內文高度。請注意,我們也必須明確宣告 <body><html> 的這些百分比。

載入 Maps JavaScript API

Maps JavaScript API 可使用 script 標記載入 (該標記能以內嵌方式加進 HTML 檔案),也可使用個別的 JavaScript 檔案動態載入。建議一併查看這兩個方法,然後選擇最適合您專案程式碼結構的方法。

內嵌載入

如要在 HTML 檔案中以內嵌方式載入 Maps JavaScript 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-loader 套件即可享有更流暢的動態載入體驗。這個套件可透過 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new 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 時,您可以選擇使用 await 運算子從非同步函式中呼叫 importLibrary(),藉此載入其他「程式庫」。程式庫是由程式碼模組所組成,可提供主要 Maps JavaScript API 的額外功能,但除非您特別要求,否則系統不會載入這些程式庫。詳情請參閱 Maps JavaScript API 中的程式庫

地圖 DOM 元素

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

我們必須在網頁上預留顯示地圖的位置。一般來說,我們會建立名為 div 的元素,然後在瀏覽器文件物件模型 (DOM) 中取得此元素的參照。

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

地圖選項

每張地圖都必須具備以下兩個選項:centerzoom

map = new 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 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 金鑰和帳單錯誤

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

如果程式碼無法運作:

為協助您讓地圖程式碼可以順利運作,Brendan Kenny 與 Mano Marks 在這部影片中指出一些常見問題和修正方式。

  • 檢查是否有錯字。請記住,JavaScript 語言區分大小寫。
  • 檢查基本設定。部分常見問題發生在建立地圖的初始階段,例如:
    • 確認您已在地圖選項中指定 zoomcenter 屬性。
    • 確認您已宣告會在畫面上顯示地圖的 div 元素。
    • 確認地圖的 div 元素已設定高度。根據預設,div 元素建立時的高度為 0,因此不可見。
    請查看範例來參考導入方式
  • 使用 JavaScript 偵錯工具協助找出問題,例如 Chrome 開發人員工具中的偵錯工具。請先透過 JavaScript 控制台找出錯誤。
  • 將問題發布到 Stack Overflow 網站。如要瞭解發布問題的技巧,請參閱「支援」頁面。