# @googlemaps/extended-component-library 中文文档

规范地址：https://npmcn.com/package/%40googlemaps/extended-component-library/

版本：0\.8\.0
npm 元数据更新时间：2026-11-04T00:37:25.116Z
中文译文更新时间：2026-11-16T20:07:32.994Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.3 MB，213 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2023-05-10T15:52:56.846Z
- 最新版本发布：2026-11-04T00:37:24.919Z
- 近 30 天下载量：60528（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 3 个）

## 中文简介

与Google Maps JavaScript API建立丰富经验的Web组件.

## 安装

```sh
npm install @googlemaps/extended-component-library
```

也可以使用：`pnpm add @googlemaps/extended-component-library`、`yarn add @googlemaps/extended-component-library`、`bun add @googlemaps/extended-component-library`

## README

# 扩展组件库

Google Maps平台扩展组件库是一组Web组件,帮助开发者更快地并用更少的努力来构建更好的地图. 它囊括了锅炉平板码,最佳做法和应答设计,将复杂的地图UI降低到有效的HTML元素.

最终,这些组件使得阅读,学习,定制和维护与地图相关的代码更加容易.

![](https://raw.githubusercontent.com/googlemaps/extended-component-library/main/doc_src/gmpx-header.png)

## 安装

### 正在装入库

#### 对于捆绑其代码的应用程序

要达到最佳性能,请使用软件包管理器,只导入所需的组件. 在国家预防机制上列出的这套资料是: [@googlemaps/ 扩展组件- 图书馆](https://www.npmjs.com/package/@googlemaps/extended-component-library)中安装

```bash
npm i @googlemaps/extended-component-library
```

然后导入应用程序中使用的任何组件 :

```js
import '@googlemaps/extended-component-library/overlay_layout.js';
```

#### 装入所有组件

或者,我们提供一个由 CDN 托管的捆绑,您可以直接作为 HTML 文件包含 [模块脚本](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html)数字 :

```html
<script type="module" src="https://unpkg.com/@googlemaps/extended-component-library"></script>
```

在使用由CDN托管的捆绑时,所有组件都可以在全球获得,不需要进一步进口. _请注意,unpkg与Google地图平台无关,使用其CDN可能会带来自己的条件和期望._

### 获取您的 API 密钥

这个库中的组件使用Google Maps平台API. 开始,你需要 [注册到 Google 地图平台并创建 API 密钥](https://console.cloud.google.com/google/maps-apis/start?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components)。然后,在您的应用程序的 HTML 根上放置一个 API 装入器元素,指定您的 API 密钥 :

```html
<gmpx-api-loader key="YOUR_API_KEY"></gmpx-api-loader>
```

当您注册时, 默认情况下, 所有 API 都会启用, 但是您可以选择只启用每个组件所需的 API , 方法是在该组件的文档中引用“ API 和定价” 部分 .

## 使用量

这个库包含一组 [Web 组件](https://developer.mozilla.org/en-US/docs/Web/Web_Components),可以在您的网络应用程序的 HTML 中任意使用。 所有现代浏览器都支持Web组件,并曝光了封装UI和功能的框架不可知机制.

这个例子说明如何在HTML中显示特定地点的信息:

```html
<!-- Please note unpkg.com is unaffiliated with Google Maps Platform -->
<script type="module" src="https://unpkg.com/@googlemaps/extended-component-library"></script>

<!-- Configure and load the Maps JS SDK with your API key -->
<gmpx-api-loader key="YOUR_API_KEY"></gmpx-api-loader>

<gmpx-split-layout>
  <gmpx-place-overview slot="fixed" place="ChIJ39Y-tdg1fYcRQcZcBb499do"></gmpx-place-overview>
  <gmp-map slot="main" center="43.880,-103.459" zoom="10" map-id="DEMO_MAP_ID">
    <gmp-advanced-marker position="43.880,-103.459"></gmp-advanced-marker>
  </gmp-map>
</gmpx-split-layout>
```

Web组件还被设计用于与JavaScript. 以下是一个例子, 说明您如何添加一个泛标记动作 :

```html
<!-- Please note unpkg.com is unaffiliated with Google Maps Platform -->
<script type="module" src="https://unpkg.com/@googlemaps/extended-component-library"></script>

<!-- Configure and load the Maps JS SDK with your API key -->
<gmpx-api-loader key="YOUR_API_KEY"></gmpx-api-loader>

<gmp-map id="my-map" center="33.15,-96.20" zoom="10" map-id="DEMO_MAP_ID">
  <gmp-advanced-marker class="pannable" gmp-clickable position="33.15,-96.20"></gmp-advanced-marker>
  <!-- Some more markers ... -->
</gmp-map>

<script>
window.addEventListener('load', () => {
  const mapElement = document.getElementById('my-map');
  const markers = document.querySelectorAll('gmp-advanced-marker.pannable');
  markers.forEach((marker) => {
    marker.addEventListener('gmp-click', () => {
      mapElement.innerMap.panTo(marker.position);
    });
  });
});
</script>
```

### 框架

Web组件与Angular,React,或Vue.js等最受欢迎的前端框架合作良好. 有关如何使用定制元素的更多信息,请查看您的框架文档.

**反应**: 具有本土反应组件的扩展组件库船,以方便整合. 请看 [反应支持](https://npmcn.com/package/%40googlemaps/extended-component-library/src/react/README.md) 开始,然后参考 [示例应用程序](https://npmcn.com/package/%40googlemaps/extended-component-library/examples/react_sample_app)。 。 。 .

**角质**:Angular与Web组件合作良好. 见"角" [示例应用程序](https://npmcn.com/package/%40googlemaps/extended-component-library/examples/angular_sample_app) 要开始.

## 有地图的组件 JS SDK

地图和标记组件可以和扩展组件库一起使用,也可以自行使用. 见 [指南](https://developers.google.com/maps/documentation/web-components/overview?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components) 欲了解更多关于地图中Web组件的信息.

| 构成部分 | 说明 |
| --- | --- |
| [`<gmp-map>`](https://developers.google.com/maps/documentation/javascript/reference/map?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components#MapElement) | 地图组件在网页上显示地图,并可以将其他与地图相关的组件,如HTML中的地图组件内部的标记来包装. |
| [`<gmp-advanced-marker>`](https://developers.google.com/maps/documentation/javascript/reference/advanced-markers?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components#AdvancedMarkerElement) | 标记组件在指定的坐标上显示地图上的一针. |

## 构成部分清单

| 构成部分 | 说明 |
| --- | --- |
| [`<gmpx-api-loader>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/api_loader/README.md) | API加载器组件加载扩展组件所需的Google地图平台库. |
| [`<gmpx-icon-button>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/icon_button/README.md) | 图标按钮组件用于UI中的动作,帮助用户用一个自带来完成事务. 它包含一个图标和一个文本标签. |
| [`<gmpx-overlay-layout>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/overlay_layout/README.md) | 覆盖布局组件允许您在像地图或列表一样坐落在主要内容上方的响应面板视图中显示信息. 您可以使用它来显示模式对话框, 更多关于一个地方或设置的细节 . |
| [`<gmpx-place-overview>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/place_overview/README.md) | 地方概览部分以5个大小和格式预先制作的UI显示数百万个企业的详细信息,包括营业时间,明星评论和相片,以及方向和其他动作. |
| [`<gmpx-place-picker>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/place_picker/README.md) | 取地器组件是一种文本输入,允许终端用户使用自動完成来搜索Google Maps的全球数据库中的特定地址或地點. |
| [`<gmpx-route-overview>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/route_overview/README.md) | 路由概览组件在 `<gmp-map>` 组件,包括原产地和目的地标记、概述的多线和景点管理. |
| [`<gmpx-split-layout>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/split_layout/README.md) | 分块布局组件允许您在响应面板视图中显示自定义的 HTML 信息,同时显示主要内容。 在狭义的容器中,如移动取景口,面板会显示在主要内容下方. |
| [`<gmpx-store-locator>`](https://npmcn.com/package/%40googlemaps/extended-component-library/src/store_locator/README.md) | 商店定位器组件显示您网站的用户可以浏览一个位置列表,找到最近的位置,并查看细节的经验. |
| [地址验证](https://npmcn.com/package/%40googlemaps/extended-component-library/src/address_validation/README.md) | 将地址验证 API 与您的网络应用集成的组件 . |
| [立方块](https://npmcn.com/package/%40googlemaps/extended-component-library/src/place_building_blocks/README.md) | 地点数据提供者组件,连同单个地点细节组件,让你选择如何显示Google地图将诸如开通时间,明星评论,相片等信息放入一个新的自定义视图. |
| [路由构件](https://npmcn.com/package/%40googlemaps/extended-component-library/src/route_building_blocks/README.md) | 路由数据提供者组件,连同路由标记和多线组件,让您选择如何使用自定义标记和多线样式在地图上显示路由. |

## 在演示中探索组件

您可以在组件编辑器中尝试组件,编辑其属性和样式. 然后你可以导出它们与流行的框架如React和Angular一起使用,或者根本没有框架.

[![Open the demo](https://raw.githubusercontent.com/googlemaps/extended-component-library/main/doc_src/open-demo-button.svg)](https://configure.mapsplatform.google/)

## 造型和主题

改变组件的外观和感觉 [CSS 自定义属性](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)。每个组件的文档将显示其支持的CSS自定义属性.

例如,Place Picker组件暴露了 `--gmpx-color-surface` 属性以调整文本输入的背景颜色。 您可以使用以下 CSS 设置此颜色为页面上所有 Place Pickers 的蓝色 :

```css
body {
  --gmpx-color-surface: blue;
}
```

全球主题选项允许您对应用程序中的组件自定义颜色和打字。 您可以选择一个字体和颜色方案来匹配你的品牌,或者默认为Google Maps的外观. 现予分发 _全局样式符号_,适用于多个组件。 本表格列出库中使用的全局风格符号: 这些是持续调整您页面上组件外观和感觉的良好起点.

CSS自定义属性 |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ---------------------------------- | `--gmpx-color-surface` | `#fff` QQ Surface主题颜色,用作背景. | | `--gmpx-color-on-surface` | `#212121` QQ 用于文本和其他元素放入表面颜色上方的颜色 。 XQ | `--gmpx-color-on-surface-variant` | `#757575` QQ 用于支持元数据和其他元素放置在表面颜色上方的颜色 。 XQ | `--gmpx-color-primary` | `#1976d2` QQ 交互式文本和元素所使用的主主题颜色, 如按钮和图标 。 也用于突出显示当前状态或选定的状态, 如焦点文本字段边框中的状态 。 {} | `--gmpx-color-on-primary` | `#fff` 上方文本或图标所用的颜色 `--gmpx-color-primary` ưμ㼯a | `--gmpx-font-family-base` | `'Google Sans Text', sans-serif` QQ 为正文、 标题和标签打字。 | | `--gmpx-font-family-headings` | `'Google Sans Text', sans-serif` 标题的 Typeface | `--gmpx-font-size-base` | `0.875rem` QQ 基线字体大小, 从中缩放组件中的其他文本元素 。 对于大多数有默认设置的用户,这将是 14px. QQ

## 本地化

您的应用程序可以使用 `setStringLiterals()` 函数 :

```js
import {setStringLiterals} from '@googlemaps/extended-component-library/utils/localize.js';

setStringLiterals({'PLACE_CLOSED': 'Cerrado'});
```

参见 `/src/base/strings.ts` 完整的可用术语清单.

## 服务条件

这个库使用Google Maps平台服务,对Google Maps平台的任何使用都服从于 [服务条件](https://cloud.google.com/maps-platform/terms?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components)。 。 。 .

为了明确起见,这个库以及每个基础组件都不是Google Maps平台核心服务.

### 欧洲经济区开发者

如您的账单地址在2025年7月8日生效的欧洲经济区 [谷歌地图平台 EEA 服务条款](https://cloud.google.com/terms/maps-platform/eea?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components) 您将申请使用服务。 功能因区域而异. [学多点](https://developers.google.com/maps/comms/eea/faq?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components)。 。 。 .

## 归属

作为提醒,您必须遵守扩展组件库使用的Google Maps平台API和SDK的所有可应用属性要求.

## 支助

这个图书馆通过开源许可证提供. 它不受Google地图平台管理 [技术支助服务准则](https://cloud.google.com/maps-platform/terms/tssg?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components),则 [苏丹解放军](https://cloud.google.com/maps-platform/terms/sla?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components),或 [折旧政策](https://cloud.google.com/maps-platform/terms?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components) (然而,图书馆使用的任何Google地图平台服务仍受Google地图平台服务条款的约束).

此图书馆所遵循的 [语义版本](https://semver.org/) 以表示何时引入了倒向相容的更改。 因此,虽然库在"0.x"版本中,但可以随时引入与后相容的修改.

如果您找到错误, 或者有特性请求, 请在 GitHub 上存档 。 如果您想从其他 Google 地图平台开发者那里得到技术问题的答案,请通过我们中的一个 [开发者社区频道](https://developers.google.com/maps/developer-community?utm_source=npm&utm_medium=documentation&utm_campaign=&utm_content=web_components)请检查date=中的日期值 (帮助) [贡献指南](https://github.com/googlemaps/extended-component-library/blob/main/CONTRIBUTING.md) 在 GitHub 仓库中.

## 常见问题

### @googlemaps/extended-component-library 是什么？

与Google Maps JavaScript API建立丰富经验的Web组件\.

### 如何安装 @googlemaps/extended-component-library？

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

### @googlemaps/extended-component-library 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/googlemaps\_\_extended-component-library 是否存在。

### @googlemaps/extended-component-library 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @googlemaps/extended-component-library 可以商用吗？

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

### @googlemaps/extended-component-library 的下载量有多少？

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

### @googlemaps/extended-component-library 还在维护吗？

最新版本 0\.8\.0 发布于 2026/11/04（12 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 3 个；首次发布于 2023/05/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

