加载 Maps JavaScript API

本指南介绍了如何加载 Maps JavaScript API。您可以通过以下三种方法加载：

使用 Dynamic Library Import

动态库导入功能可在运行时加载库。这样，您就可以在需要时请求所需的库，而不是在加载时一次性请求所有库。它还可防止您的网页多次加载 Maps JavaScript API。

将内嵌引导加载程序添加到应用代码中，即可加载 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>

您也可以直接将引导加载程序代码添加到 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 密钥，您可以在授权来自 Maps JavaScript API 的请求时设置 authReferrerPolicy: "origin"，以限制发送的数据量。如果指定了此参数并且在 Cloud 控制台中启用了 HTTP 引荐来源网址限制，则仅当有 HTTP 引荐来源网址限制与当前网站的网域（未指定路径）匹配的情况下，Maps JavaScript API 才能加载。

  • mapIds：一个由多个地图 ID 构成的数组。会导致系统预加载指定地图 ID 的配置。

  • channel：请参阅按渠道跟踪使用情况。

  • solutionChannel：Google Maps Platform 提供了许多类型的示例代码，可帮助您快速上手。为了跟踪更复杂的代码示例的采用情况并提高解决方案质量，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 密钥，您可以在授权来自 Maps JavaScript API 的请求时设置 auth_referrer_policy=origin，以限制发送的数据量。此参数从版本 3.46 开始提供。如果指定了此参数并且在 Cloud 控制台中启用了 HTTP 引荐来源网址限制，则仅当有 HTTP 引荐来源网址限制与当前网站的网域（未指定路径）匹配的情况下，Maps JavaScript API 才能加载。

  • mapIds：地图 ID 的逗号分隔列表。会导致系统预加载指定地图 ID 的配置。

  • channel：请参阅按渠道跟踪使用情况。

  • solution_channel：Google Maps Platform 提供了许多类型的示例代码，可帮助您快速上手。为了跟踪更复杂的代码示例的采用情况并提高解决方案质量，Google 在示例代码的 API 调用中添加了 solution_channel 查询参数。

使用 NPM js-api-loader 软件包

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

迁移步骤

首先，将直接脚本加载标记替换为内嵌引导加载程序标记。

之前

<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();