加载 Maps JavaScript API

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

使用 Dynamic Library Import

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

要在运行时加载库，请在 async 函数中使用 await 运算符调用 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 Maps Platform 提供了许多类型的示例代码，可帮助您快速上手。为了跟踪更复杂的代码示例的采用情况并提高解决方案质量，Google 在示例代码的 API 调用中添加了 solutionChannel 查询参数。

  • authReferrerPolicy：Maps JS 客户可以在 Cloud 控制台中配置 HTTP 引荐来源网址限制，以限制哪些网址可以使用特定的 API 密钥。默认情况下，这类限制可以配置为仅允许某些路径使用某个 API 密钥。如果同一网域或同一来源的任何网址都可以使用该 API 密钥，您可以在授权来自 Maps JavaScript API 的请求时设置 authReferrerPolicy: "origin"，以限制发送的数据量。如果指定了此参数并且在 Cloud 控制台中启用了 HTTP 引荐来源网址限制，则仅当有 HTTP 引荐来源网址限制与当前网站的网域（未指定路径）匹配的情况下，Maps JavaScript API 才能加载。

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

使用旧版脚本加载标记

目前仍然支持旧版脚本加载标记。提供此部分是为了支持使用旧版脚本加载标记进行的集成，但更建议您迁移至 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 Maps Platform 提供了许多类型的示例代码，可帮助您快速上手。为了跟踪更复杂的代码示例的采用情况并提高解决方案质量，Google 在示例代码的 API 调用中添加了 solution_channel 查询参数。

  • auth_referrer_policy：Maps JS 客户可以在 Cloud 控制台中配置 HTTP 引荐来源网址限制，以限制哪些网址可以使用特定的 API 密钥。默认情况下，这类限制可以配置为仅允许某些路径使用某个 API 密钥。如果同一网域或同一来源的任何网址都可以使用该 API 密钥，您可以在授权来自 Maps JavaScript API 的请求时设置 auth_referrer_policy=origin，以限制发送的数据量。此参数从版本 3.46 开始提供。如果指定了此参数并且在 Cloud 控制台中启用了 HTTP 引荐来源网址限制，则仅当有 HTTP 引荐来源网址限制与当前网站的网域（未指定路径）匹配的情况下，Maps JavaScript API 才能加载。

迁移到 Dynamic Library Import API

本部分介绍了需要完成哪些步骤，才能迁移集成以使用 Dynamic Library Import API。

迁移步骤

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

之前

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