使用 JavaScript 新增含有標記的 Google 地圖

簡介

本教學課程說明如何在網頁中加入含有標記的簡易 Google 地圖。適用對象為具備 HTML 和 CSS 初級或中級知識的使用者。 並具備一些 JavaScript 知識

以下是您將在本教學課程中建立的地圖。標記位於烏魯魯卡塔丘塔國家公園的烏魯魯 (又稱艾爾斯岩)。

開始使用

在網頁上建立含有標記的 Google 地圖時，步驟共有三個：

  1. 取得 API 金鑰
  2. 建立 HTML 網頁
  3. 加入含有標記的地圖

您需要使用網路瀏覽器。請從支援的瀏覽器清單中，根據您使用的平台選擇 Google Chrome (建議使用)、Firefox、Safari 或 Edge 等常見瀏覽器。

步驟 1：取得 API 金鑰

本節說明如何使用您自己的 API 金鑰，向 Maps JavaScript API 驗證應用程式。

取得 API 金鑰的步驟如下：

  1. 前往 Google Cloud 控制台。

  2. 建立或選取所需專案。

  3. 按一下「繼續」以啟用 API 和所有相關服務。

  4. 在「憑證」頁面上，取得 API 金鑰 (並設定 API 金鑰限制)。注意：如果您目前有不受限制的 API 金鑰，或是設有瀏覽器限制的金鑰，可以使用該金鑰。

  5. 如要避免配額竊用行為及保護 API 金鑰，請參閱「使用 API 金鑰」。

  6. 啟用計費功能。詳情請參閱「用量與計費」一文。

  7. 取得 API 金鑰後，請按一下「YOUR_API_KEY」，將金鑰加入下列程式碼片段。複製並貼上系統啟動載入程式指令碼標記，以便自行使用 網頁。

    <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",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

步驟 2：建立 HTML 網頁

以下是基本 HTML 網頁程式碼：

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>

index.html

請注意，這是非常基本的網頁，包含第三層標題 (h3) 和一個 div 元素。您可以在網頁中加入任意內容。

瞭解程式碼

這個範例的這個階段有：

  • 使用 !DOCTYPE html 宣告，將應用程式宣告為 HTML5。
  • 建立名為「map」的 div 元素放置地圖。
  • 使用 Bootstrap 載入器載入 Maps JavaScript API。

將應用程式宣告為 HTML5

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

<!DOCTYPE html>

目前的瀏覽器會顯示使用此 DOCTYPE 宣告的內容 在「標準模式」下換句話說，您的應用程式 具備跨瀏覽器相容性DOCTYPE 也設計成會優雅降級。 以「相容模式」為基礎的瀏覽器則會忽略該警告，而採用「相容模式」到 顯示自己的內容

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

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

建立 div 元素

我們必須在網頁上預留顯示地圖的位置。一般而言 我們會建立名為 div 的元素，並取得 加入瀏覽器物件模型 (DOM) 中的元素。

下方程式碼定義網頁上要加入 Google 地圖的區域。

<!--The div element for the map -->
<div id="map"></div>

在教學課程的這個階段中，您尚未加入地圖，因此 div 會顯示為灰色區塊。下方程式碼說明用以設定 div 尺寸和顏色的 CSS。

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

在上述程式碼中，style 元素會設定地圖的 div 尺寸。請將 div 寬度和高度設為大於 0 像素以顯示地圖。在本 範例：div 的高度設為 400 像素，寬度設為 100% 來顯示 請注意，div 通常會取寬 其所含元素的高度為 0，空白 div 的高度通常為 0。為此 原因，您必須一律在 div 上明確設定高度。

載入 Maps JavaScript API

Bootstrap 載入器會準備 Maps JavaScript API 進行載入 (在呼叫 importLibrary() 前不會載入任何程式庫)。

<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",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

如要瞭解如何自行取得 API 金鑰，請參閱「步驟 3：取得 API 金鑰」一節。

步驟 3：加入含有標記的地圖

本節說明如何在網頁中載入 Maps JavaScript API，以及如何自行編寫 JavaScript，以使用 API 加入含有標記的地圖。

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

在上述程式碼中，系統呼叫 initMap() 函式時會載入 Map 和 AdvancedMarkerView 程式庫。

瞭解程式碼

在教學課程的這個階段中，我們會：

  • 定義可在 div 中建立地圖的 JavaScript 函式。
  • 建立 AdvancedMarkerElement 以在地圖中加入標記。

新增地圖

下方程式碼會建立新的 Google 地圖物件，並將屬性加入地圖，包括中心點和縮放等級。請參閱其他屬性選項的說明文件。

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);
index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});

index.js

每張地圖都必須具備以下兩個選項：center 和 zoom。上述 程式碼，new Map() 會建立新的 Google 地圖物件。center 屬性會指示 指定地圖的中心點。

zoom 屬性會指定地圖的縮放等級。「縮放：0」是最低的縮放等級，會顯示整個地球。調高縮放等級，就能以較高的解析度放大地球。

如果以單一圖片提供整個地球的地圖，有可能就需要 或解析度非常低的小型地圖。因此，地圖圖片 在「Google 地圖」中和 Maps JavaScript API 細分為「地圖方塊」 以及「縮放等級」縮放等級較低時，一小群地圖圖塊會涵蓋 區域；縮放等級較高時，地圖方塊的解析度也會提高，並涵蓋 小區域下列清單列出您可以近乎的詳細程度 各縮放等級下可看到的內容：

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

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

加入標記

下方程式碼會在地圖上加入標記。position 屬性會設定標記的位置。

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});
index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});
index.js

完整程式碼範例

完整程式碼範例如下：

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

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

style.css

HTML

<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <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>
index.html

測試範例

進一步瞭解標記：

提示和疑難排解

  • 進一步瞭解如何取得經緯度 或將地址轉換成地理座標。
  • 您可以調整樣式和屬性等選項來自訂地圖。如要進一步瞭解如何自訂地圖，請參閱「樣式」和「在地圖上繪圖」的指南。
  • 您可以在網路瀏覽器中，使用開發人員工具控制台測試及執行程式碼、閱讀錯誤報告，以及解決程式碼問題。
  • 在 Chrome 中使用下列鍵盤快速鍵開啟控制台：
    Command+Option+J 鍵 (Mac) 或 Control+Shift+J 鍵 (Windows)。

  • 請按照下方步驟操作，取得 Google 地圖上某個地點的經緯度座標。

    1. 在瀏覽器中開啟 Google 地圖。
    2. 在地圖上，對需要座標的精確位置按一下滑鼠右鍵。
    3. 從顯示的內容選單中選取「這是哪裡？」，地圖就會在畫面底部顯示資訊卡，並於卡上最後一列提供經緯度座標。

  • 使用地理編碼服務即可將地址轉換成經緯度座標，開發人員指南也提供地理編碼服務的詳細使用方法。