# @googlemaps/map-loader 中文文档

规范地址：https://npmcn.com/package/%40googlemaps/map-loader/

版本：0\.2\.0
npm 元数据更新时间：2026-05-14T23:26:29.396Z
中文译文更新时间：2026-11-16T20:35:07.914Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40googlemaps/map-loader
原文对照：https://npmcn.com/package/%40googlemaps/map-loader/?lang=original
项目主页：https://github.com/googlemaps/js-map-loader#readme
源码仓库：https://github.com/googlemaps/js-map-loader

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：568 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2020-03-27T19:21:04.351Z
- 最新版本发布：2021-01-20T22:48:22.034Z
- 近 30 天下载量：11755（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

自动初始化并加载地图 JS API 基础地图到 DOM

## 安装

```sh
npm install @googlemaps/map-loader
```

也可以使用：`pnpm add @googlemaps/map-loader`、`yarn add @googlemaps/map-loader`、`bun add @googlemaps/map-loader`

## README

![Test](https://github.com/googlemaps/js-map-loader/workflows/Test/badge.svg) [![codecov](https://codecov.io/gh/googlemaps/js-map-loader/branch/master/graph/badge.svg)](https://codecov.io/gh/googlemaps/js-map-loader) ![TypeScript](https://badgen.net/badge/icon/Typed?icon=typescript&label&labelColor=blue&color=555555) ![Apache-2.0](https://img.shields.io/badge/license-Apache-blue)

# Google 地图平台的地图装入器 JavaScript API v3

## 说明

用 JavaScript 或 TypeScript 的几行自动将 Google 地图加载到您的网站上 。 您提供您想要初始化或附图的 div 的ID, 您的设置, 用于地图的外观, 也可以选择您的设置, 用于加载 Maps JS API, 此模块处理其他的 .

Google 地图平台 JavaScript API 的加载工作为您提供了同步礼遇 [@googlemaps/js-api-loader (英语)](https://www.npmjs.com/package/@googlemaps/js-api-loader)。 。 。 .

## 国家预防机制

国家防范机制作为一揽子方案提供 `@googlemaps/map-loader`

## 示例

### 设置地图加载器选项

```javascript
import { GoogleMap } from 'map-loader';

const googleMapsAPIKey = "YOUR API KEY";

/* Options for how the map should initially render. */
const mapOptions = {
  center: {
    lat: 47.649196,
    lng: -122.350384
  },
  zoom: 12
}

/* Options for loading the Maps JS API. */
const apiOptions = {
  version: 'weekly',
  libraries: ['places']
}

/*
 * Set ID of the div where the map will be loaded,
 * and whether to append to that div.
 */
const mapLoaderOptions = {
  apiKey: googleMapsAPIKey,
  divId: 'google_map',
  append: true, // Appends to divId. Set to false to init in divId.
  mapOptions: mapOptions,
  apiOptions: apiOptions
};
```

### 装入地图 :

```javascript
// Instantiate map loader
const mapLoader = new GoogleMap();

// Load the map
mapLoader
  .initMap(mapLoaderOptions)
  .then(googleMap => {
    // returns instance of google.maps.Map
  });
```

### 或者,如果你喜欢, 用Aync/await

```javascript
// Instantiate map loader
const mapLoader = new GoogleMap();

// Load the map
const await googleMap = mapLoader.initMap(mapLoaderOptions);
```

## 文档

如果您使用 TypeScript, 地图加载器导出接口用于 `MapLoaderOptions` 财务报告和审定财务报表 `MapsJSAPIOptions`。为基础地图设置提供了google.maps的礼节。 映射选项 [@ types/ googlemaps (英语)](https://www.npmjs.com/package/@types/googlemaps)。 。 。 .

### 地图记录选项

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 键 | 字符串 | 你的API密钥. 有关生成 API 密钥的信息,参见 [如何为 Google 地图平台生成和限制 API 密钥](https://youtu.be/2_HZObVbe-g)。 。 。 . |
| 数字 | 字符串 | 您想要初始化或附加地图的地名录的ID . |
| 映射选项 | [google.maps (英语). 地图选项](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/googlemaps/index.d.ts#L479) | 如何显示地图的设置 。 完整的地图选项列表见 [google.maps (英语). 地图选项](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/googlemaps/index.d.ts#L479)。 。 。 . |
| api 选项 | [地图JSAPI 选项](https://npmcn.com/package/%40googlemaps/map-loader/#readme-mapsjsapioptions) | 设置装入地图 JavaScriptAPI 。 API 选项的完整列表参见 [地图JSAPI 选项](https://npmcn.com/package/%40googlemaps/map-loader/#readme-mapsjsapioptions)。 。 。 . |
| 附录 | 布尔 | _可选的._ 默认为假. 设定是初始化地图还是附加到 `divId`。 。 。 . |

### 地图JSAPI 选项

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| 版本 | 字符串 | _可选的._ 默认为 `weekly`要装入的地图版本 JS API 。 关于所支持值的更多信息,参见 [发布频道和版本编号](https://developers.google.com/maps/documentation/javascript/versions#release-channels-and-version-numbers)。 。 。 . |
| 图书馆 | 阵列 | _可选的._ 附加地图 JS API 库可加载. 支持的值为 `drawing`, (中文(简体) ), `geometry`, (中文(简体) ), `places`, (中文(简体) ), `visualization`。 。 。 . |
| 语言 | 字符串 | _可选的._ 默认为 `en`。该语言的语言代码可以使地图本地化。 关于所支持值的更多信息,参见 [支持的语言](https://developers.google.com/maps/faq#languagesupport)。 。 。 . |
| 区域 | 字符串 | _可选的._ 默认为 `us`设置区域下的Unicode区域标识符,使地图本地化。 关于所支持值的更多信息,参见 [地区本地化](https://developers.google.com/maps/documentation/javascript/localization#Region)。 。 。 . |

## 支助

这个图书馆是社区支持的。 我们很适应 稳定与特点 我们想让你在上面 建立真正的生产应用程序的图书馆.

如果您发现错误, 或者有特性建议, 请 [日志一个问题](https://github.com/googlemaps/js-map-loader/issues)如果你愿意的话 请填写 [如何贡献](https://github.com/googlemaps/js-map-loader/blob/master/CONTRIBUTING.md)。 。 。 .

## 常见问题

### @googlemaps/map-loader 是什么？

自动初始化并加载地图 JS API 基础地图到 DOM

### 如何安装 @googlemaps/map-loader？

在项目目录运行 npm install @googlemaps/map-loader，或使用 pnpm add / yarn add / bun add。

### @googlemaps/map-loader 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @googlemaps/map-loader 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @googlemaps/map-loader 可以商用吗？

@googlemaps/map-loader 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @googlemaps/map-loader 的下载量有多少？

根据 npm 官方下载统计，@googlemaps/map-loader 在 2026/10/17 – 2026/11/15 这 30 天内被下载 11,755 次，日均约 392 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @googlemaps/map-loader 还在维护吗？

最新版本 0\.2\.0 发布于 2021/01/21（5 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

