@googlemaps/react-wrapper

中文文档
1.2.0发布于 2025/03/29Apache-2.0TypeScriptESM + CJS近 30 天下载 96.6万

React component that wraps the loading of Google Maps JavaScript API.

原始使用文档
文档目录7 节
  1. Description
  2. @googlemaps/js-api-loader
  3. MyMapComponent
  4. Examples
  5. Install
  6. Documentation
  7. Support

Google Maps JavaScript API React Wrapper

npm Build Release codecov GitHub contributors semantic-release

[!IMPORTANT]
This library has been archived. We recommend all users of this package to switch to the new @vis.gl/react-google-maps, which provides a collection of components and hooks and can be configured to be fully compatible with this package.

See the migration guide for more details on how to switch from this package to @vis.gl/react-google-maps.

Description

Wrap React components with this library to load the Google Maps JavaScript API.

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

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

The preceding example will not render any elements unless the Google Maps JavaScript API is successfully loaded. To handle error cases and the time until load is complete, it is recommended to provide render props.

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} />;

When combining children and render props, the children will render on success and the render prop will be executed for other status values.

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

This wrapper uses @googlemaps/js-api-loader to load the Google Maps JavaScript API. This library uses a singleton pattern and will not attempt to load the library more than once. All options accepted by @googlemaps/js-api-loader are also accepted as props to the wrapper component.

MyMapComponent

The following snippets demonstrates the usage of useRef and useEffect hooks with Google Maps.

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" />;
}

Examples

See the examples folder for additional usage patterns.

Install

Available via npm as the package @googlemaps/react-wrapper.

npm i @googlemaps/react-wrapper

or

yarn add @googlemaps/react-wrapper

For TypeScript support additionally install type definitions.

npm i -D @types/google.maps

or

yarn add -D @types/google.maps

Documentation

The reference documentation can be found at this link.

Support

This library is community supported. We're comfortable enough with the stability and features of the library that we want you to build real production applications on it.

If you find a bug, or have a feature suggestion, please log an issue. If you'd like to contribute, please read How to Contribute.

版本与发布记录

@googlemaps/react-wrapper 共发布 41 个版本,首次发布于 2021/03/02;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.2.0latest2025/03/291.6 年前
1.1.422024/08/092 年前
1.1.352022/06/204 年前
1.1.342022/05/194 年前
1.1.332022/05/114 年前
1.1.322022/04/224 年前

关于 @googlemaps/react-wrapper 的常见问题

@googlemaps/react-wrapper 是什么?

React component that wraps the loading of 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 和提交记录判断。