# @googlemaps/react-wrapper 中文文档

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

版本：1\.2\.0
npm 元数据更新时间：2026-05-14T23:26:34.083Z
中文译文更新时间：2026-11-16T19:55:22.460Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：37.2 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0
- 首次发布：2021-03-01T23:16:04.373Z
- 最新版本发布：2025-03-28T18:30:20.666Z
- 近 30 天下载量：966228（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 0 个）

## 中文简介

反应组件包装了Google Maps JavaScript API.

## 安装

```sh
npm install @googlemaps/react-wrapper
```

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

## README

# Google 地图 JavaScript API 反应收发器

[![npm](https://img.shields.io/npm/v/@googlemaps/react-wrapper)](https://www.npmjs.com/package/@googlemaps/react-wrapper) ![Build](https://github.com/googlemaps/react-wrapper/workflows/Test/badge.svg) ![Release](https://github.com/googlemaps/react-wrapper/workflows/Release/badge.svg) [![codecov](https://codecov.io/gh/googlemaps/react-wrapper/branch/master/graph/badge.svg)](https://codecov.io/gh/googlemaps/react-wrapper) ![GitHub contributors](https://img.shields.io/github/contributors/googlemaps/react-wrapper?color=green) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![](https://github.com/jpoehnelt/in-solidarity-bot/raw/main/static//badge-flat-square.png)](https://github.com/apps/in-solidarity)

> \[大  
> 此库已存档 . 我们建议这个软件包的所有用户切换到新的 [`@vis.gl/react-google-maps`](https://www.npmjs.com/package/@vis.gl/react-google-maps), (中文(简体) ), 它提供了组件和钩子的集合,可以配置 与此软件包完全兼容.
> 
> 见 [迁移指南](https://visgl.github.io/react-google-maps/docs/guides/migrating-from-react-wrapper) 关于如何从此软件包切换到 `@vis.gl/react-google-maps`。 。 。 .

## 说明

使用此库来包裝 Google Maps JavaScript API 的回放组件 .

```jsx
import {Wrapper} from '@googlemaps/react-wrapper';

const MyApp = () => (
  <Wrapper apiKey={'YOUR_API_KEY'}>
    <MyMapComponent />
  </Wrapper>
);
```

前面的例子不会使任何元素生效,除非Google Maps JavaScript API成功加载. 为了处理出错的案件和完成装载前的时间,建议提供渲染道具.

```jsx
import {Wrapper, Status} from '@googlemaps/react-wrapper';

const render = status => {
  switch (status) {
    case Status.LOADING:
      return <Spinner />;
    case Status.FAILURE:
      return <ErrorComponent />;
    case Status.SUCCESS:
      return <MyMapComponent />;
  }
};

const MyApp = () => <Wrapper apiKey={'YOUR_API_KEY'} render={render} />;
```

在合并子女和制作道具时,儿童将获得成功,而成品道具将按其他状态值执行.

```tsx
import {Wrapper, Status} from '@googlemaps/react-wrapper';

const render = (status: Status): ReactElement => {
  if (status === Status.FAILURE) return <ErrorComponent />;
  return <Spinner />;
};

const MyApp = () => (
  <Wrapper apiKey={'YOUR_API_KEY'} render={render}>
    <MyMapComponent />
  </Wrapper>
);
```

### @googlemaps/js-api-loader (英语)

此包装器使用 [@googlemaps/js-api-loader (英语)](https://www.npmjs.com/package/@googlemaps/js-api-loader) 装入 Google 地图 JavaScript API。 这个库使用单通图案,不会试图多次加载库. 接受的所有选项 [@googlemaps/js-api-loader (英语)](https://www.npmjs.com/package/@googlemaps/js-api-loader) 也可以作为包装器组件的道具.

### MyMap 组件

以下片段显示了使用 `useRef` 财务报告和审定财务报表 `useEffect` 与Google地图的钩子.

```tsx
function MyMapComponent({
  center,
  zoom,
}: {
  center: google.maps.LatLngLiteral;
  zoom: number;
}) {
  const ref = useRef<HTMLDivElement>();
  const [map, setMap] = useState<google.maps.Map | null>(null);

  useEffect(() => {
    const map = new google.maps.Map(ref.current, {center, zoom});
    setMap(map);

    return () => {
      google.maps.event.clearInstanceListeners(map);
      setMap(null);
    };
  }, []);

  useEffect(() => {
    if (!map) return;

    // do something with the map instance
  }, [map]);

  return <div ref={ref} id="map" />;
}
```

## 实例

见 [实例](https://github.com/googlemaps/react-wrapper/tree/main/examples) 用于附加使用模式的文件夹.

-   [基本民主](https://googlemaps.github.io/react-wrapper/public/basic/)

## 安装

通过 npm 作为软件包可用 [@ googlemaps/ 反应- wrapper](https://www.npmjs.com/package/@googlemaps/react-wrapper)。 。 。 .

```sh
npm i @googlemaps/react-wrapper
```

或者说

```sh
yarn add @googlemaps/react-wrapper
```

对于TypeScript支持额外安装类型定义.

```sh
npm i -D @types/google.maps
```

或者说

```sh
yarn add -D @types/google.maps
```

## 文档

参考文件见此 [链接](https://googlemaps.github.io/react-wrapper/index.html)。 。 。 .

## 支助

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

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

## 常见问题

### @googlemaps/react-wrapper 是什么？

反应组件包装了Google Maps JavaScript API\.

### 如何安装 @googlemaps/react-wrapper？

在项目目录运行 npm install @googlemaps/react-wrapper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @googlemaps/react-wrapper 支持 TypeScript 吗？

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

### @googlemaps/react-wrapper 支持 ESM 还是 CommonJS？

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

### @googlemaps/react-wrapper 可以商用吗？

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

### @googlemaps/react-wrapper 的下载量有多少？

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

### @googlemaps/react-wrapper 还在维护吗？

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

