載入 Maps JavaScript API

本指南將說明如何載入 Maps JavaScript API。載入方法分為三種：

使用 Dynamic Library Import

動態程式庫匯入功能可在執行階段載入程式庫。這樣一來，您就能在需要時要求所需的程式庫，而不是在載入時一次要求所有程式庫。這也能避免網頁多次載入 Maps JavaScript API。

將內嵌 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",
    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>

您也可以將 Bootstrap 載入器程式碼直接加進 JavaScript 程式碼。

如要在執行階段載入程式庫，請使用 await 運算子從 async 函式中呼叫 importLibrary()。為所需類別宣告變數，可讓您略過使用限定路徑 (例如 google.maps.Map)，如以下程式碼範例所示：

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  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,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();
index.js

您的函式也可以在不需要的類別中宣告變數，藉此載入程式庫，這在您使用 gmp-map 元素新增地圖時特別實用：

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

或者，您也可以直接在 HTML 中載入程式庫，如下所示：

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

瞭解如何遷移至 Dynamic Library Loading API。

必要參數

  • key：您的 API 金鑰。必須指定有效的 API 金鑰，才能載入 Maps JavaScript API。

選用參數

  • v：要載入的 Maps JavaScript API 版本。

  • libraries：逗號分隔的清單，包含要載入的其他 Maps JavaScript API 程式庫。我們通常不建議指定一組固定的程式庫，開發人員如想微調網站的快取行為，則可以這麼做。

  • language：要使用的語言。這會影響控制項名稱、版權通知、行車路線和控制項標籤，以及對服務要求的回應。查看支援語言清單。

  • region：要使用的區碼。這會根據特定國家/地區或地域調整地圖行為。

  • authReferrerPolicy：Maps JS 客戶可在 Cloud 控制台中設定 HTTP 參照網址限制，以限制哪些網址可使用特定 API 金鑰。根據預設，您可以將這些限制設為僅允許特定路徑使用 API 金鑰。如果相同網域或來源的任何網址可能會使用 API 金鑰，您就可以設定 authReferrerPolicy: "origin"，限制在授權 Maps JavaScript API 要求時傳送的資料量。如果指定這個參數，且在 Cloud 控制台中已啟用 HTTP 參照網址限制，則只有在 HTTP 參照網址限制與目前網站網域相符 (未指定路徑) 時，才能載入 Maps JavaScript API。

  • mapIds：地圖 ID 陣列。會導致系統預先載入指定地圖 ID 的設定。

  • channel：請參閱「依管道追蹤使用情形」。

  • solutionChannel：Google 地圖平台提供多種程式碼範例，幫助您快速完成設定並開始使用。為追蹤複雜程式碼範例的採用情況，以及改善解決方案品質，Google 會在程式碼範例的 API 呼叫中加入 solutionChannel 查詢參數。

使用直接指令碼載入標記

本節說明如何使用直接指令碼載入標記。由於直接指令碼會在地圖載入時載入程式庫，因此可簡化使用 gmp-map 元素建立的地圖，因為您不必在執行階段明確要求程式庫。由於直接指令碼載入標記會在載入指令碼時一次載入所有要求的程式庫，因此部分應用程式的效能可能會受到影響。每個網頁載入時，只包含直接指令碼載入標記一次。

新增指令碼標記

如要在 HTML 檔案中以內嵌方式載入 Maps JavaScript API，請新增 script 標記，如下所示。

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

直接指令碼載入網址參數

本節探討載入 Maps JavaScript API 時，您可以在指令碼載入網址的查詢字串中指定的所有參數。有些是必要參數，有些則是自選參數。依照網址標準，所有參數都會以 & 字元分隔。

下列網址範例包含所有可用參數的預留位置：

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

下列 script 標記範例中的網址會載入 Maps JavaScript API：

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

必要參數 (直接)

載入 Maps JavaScript API 時，必須提供下列參數。

  • key：您的 API 金鑰。必須指定有效的 API 金鑰，才能載入 Maps JavaScript API。

選用參數 (直接)

您可以使用這些參數來要求特定版本的 Maps JavaScript API、載入其他程式庫、將地圖本地化，或是指定 HTTP 參照網址檢查政策

  • loading：Maps JavaScript API 可使用的程式碼載入策略。將其設為 async，表示 Maps JavaScript API 並未同步載入，且指令碼的 load 事件不會觸發任何 JavaScript 程式碼。強烈建議您盡可能將這項屬性設為 async，以提升效能。(如果 Maps JavaScript API 可用，請改用 callback 參數來執行動作)。自 3.55 版起提供。

  • callback：Maps JavaScript API 載入完成時要呼叫的全域函式名稱。

  • v：要使用的 Maps JavaScript API 版本。

  • libraries：逗號分隔的清單，包含要載入的其他 Maps JavaScript API 程式庫。

  • language：要使用的語言。這會影響控制項名稱、版權通知、行車路線和控制項標籤，以及對服務要求的回應。查看支援語言清單。

  • region：要使用的區碼。這會根據特定國家/地區或地域調整地圖行為。

  • auth_referrer_policy：客戶可在 Cloud 控制台中設定 HTTP 參照網址限制，以限制哪些網址可使用特定 API 金鑰。根據預設，您可以將這些限制設為僅允許特定路徑使用 API 金鑰。如果相同網域或來源的任何網址可能會使用 API 金鑰，您就可以設定 auth_referrer_policy=origin，限制在授權 Maps JavaScript API 要求時傳送的資料量。這項功能從 3.46 版開始提供。如果指定這個參數，且在 Cloud 控制台中已啟用 HTTP 參照網址限制，則只有在 HTTP 參照網址限制與目前網站網域相符 (未指定路徑) 時，才能載入 Maps JavaScript API。

  • mapIds：以半形逗號分隔的地圖 ID 清單。會導致系統預先載入指定地圖 ID 的設定。

  • channel：請參閱「依管道追蹤使用情形」。

  • solution_channel：Google 地圖平台提供多種程式碼範例，幫助您快速完成設定並開始使用。為追蹤複雜程式碼範例的採用情況，以及改善解決方案品質，Google 會在程式碼範例的 API 呼叫中加入 solution_channel 查詢參數。

使用 NPM js-api-loader 套件

您可以透過 NPM 套件管理員載入 @googlemaps/js-api-loader 套件。請使用以下指令完成安裝：

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,
  });
});
index.ts

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

index.js

查看含有 js-api-loader 的範例。

以下範例說明如何使用 loader.importLibrary() 載入程式庫：

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

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

遷移至 Dynamic Library Import API

本節將說明遷移整合項目的必要步驟，協助您使用 Dynamic Library Import API。

遷移步驟

首先，將直接指令碼載入標記換成內嵌 Bootstrap 載入器標記。

之前

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

完成後

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

接著，請更新應用程式程式碼：

  • 將 initMap() 函式變更為非同步。
  • 呼叫 importLibrary() 載入並存取所需的程式庫。

完成前

let map;

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

window.initMap = initMap;

完成後

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();