載入 Maps JavaScript API

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

使用 Dynamic Library Import (建議採用)
使用 NPM js-api-loader 套件
使用舊版指令碼載入標記

使用 Dynamic Library Import

將內嵌 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()，如以下程式碼範例所示：

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

必要參數

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

自選參數

v：要載入的 Maps JavaScript API 版本。
libraries：逗號分隔的清單，包含要載入的其他 Maps JavaScript API 程式庫。通常不建議指定一組固定的程式庫，如果開發人員想微調網站的快取行為，則可這麼做。
language：要使用的語言。這會影響控制項名稱、版權通知、行車路線和控制項標籤，以及對服務要求的回應。查看支援語言清單。
region：要使用的區碼。這會根據特定國家/地區或地域調整地圖行為。
solutionChannel：Google 地圖平台提供多種程式碼範例，幫助您快速完成設定並開始使用。為追蹤複雜程式碼範例的採用情況，以及改善解決方案品質，Google 會在程式碼範例的 API 呼叫中加入 solutionChannel 查詢參數。
authReferrerPolicy：Maps JS 客戶可在 Cloud 控制台中設定 HTTP 參照網址限制，以限制哪些網址可使用特定 API 金鑰。根據預設，您可以將這些限制設為僅允許特定路徑使用 API 金鑰。如果相同網域或來源的任何網址可能會使用 API 金鑰，您就可以設定 authReferrerPolicy: "origin"，限制在授權 Maps JavaScript API 要求時傳送的資料量。如果指定這個參數，且在 Cloud 控制台中已啟用 HTTP 參照網址限制，則只有在 HTTP 參照網址限制與目前網站網域相符 (未指定路徑) 時，才能載入 Maps JavaScript API。

使用 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 的範例。

使用舊版指令碼載入標記

系統仍支援舊版指令碼載入標記。本節提供相關支援，協助您使用舊版指令碼載入標記進行整合。Google 建議您遷移至 Dynamic Library Loading API。

新增指令碼標記

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

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

舊版指令碼載入網址參數

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

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

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

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

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

必要參數 (舊版)

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

key：您的 API 金鑰。必須指定有效的 API 金鑰，才能載入 Maps JavaScript API。
callback：Maps JavaScript API 載入完成時要呼叫的全域函式名稱。

自選參數 (舊版)

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

v：要使用的 Maps JavaScript API 版本。
libraries：逗號分隔的清單，包含要載入的其他 Maps JavaScript API 程式庫。
language：要使用的語言。這會影響控制項名稱、版權通知、行車路線和控制項標籤，以及對服務要求的回應。查看支援語言清單。
region：要使用的區碼。這會根據特定國家/地區或地域調整地圖行為。
solution_channel：Google 地圖平台提供多種程式碼範例，幫助您快速完成設定並開始使用。為追蹤複雜程式碼範例的採用情況，以及改善解決方案品質，Google 會在程式碼範例的 API 呼叫中加入 solution_channel 查詢參數。

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

遷移至 Dynamic Library Import API

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

遷移步驟

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

完成前

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&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();