react-google-maps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@vis.gl/react-google-maps

Official React library for Google Maps JavaScript API, maintained by vis.gl with Google sponsorship.

由vis.gl维护、谷歌赞助的Google Maps JavaScript API官方React库。

Quick Start

快速开始

tsx

import { APIProvider, Map, AdvancedMarker, Pin } from '@vis.gl/react-google-maps';

function App() {
  return (
    <APIProvider apiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}>
      <Map
        style={{ width: '100%', height: '400px' }}
        defaultCenter={{ lat: 18.4655, lng: -66.1057 }}
        defaultZoom={12}
        mapId="YOUR_MAP_ID" // Required for AdvancedMarker
      >
        <AdvancedMarker position={{ lat: 18.4655, lng: -66.1057 }}>
          <Pin background="#0f9d58" borderColor="#006425" glyphColor="#60d98f" />
        </AdvancedMarker>
      </Map>
    </APIProvider>
  );
}

tsx

import { APIProvider, Map, AdvancedMarker, Pin } from '@vis.gl/react-google-maps';

function App() {
  return (
    <APIProvider apiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}>
      <Map
        style={{ width: '100%', height: '400px' }}
        defaultCenter={{ lat: 18.4655, lng: -66.1057 }}
        defaultZoom={12}
        mapId="YOUR_MAP_ID" // Required for AdvancedMarker
      >
        <AdvancedMarker position={{ lat: 18.4655, lng: -66.1057 }}>
          <Pin background="#0f9d58" borderColor="#006425" glyphColor="#60d98f" />
        </AdvancedMarker>
      </Map>
    </APIProvider>
  );
}

Installation

安装

bash

npm install @vis.gl/react-google-maps

bash

npm install @vis.gl/react-google-maps

Key Exports

核心导出内容

tsx

// Components
import {
  APIProvider,      // Wraps app, loads Maps JS API
  Map,              // Map container
  AdvancedMarker,   // Modern marker (requires mapId)
  Pin,              // Customizable pin for AdvancedMarker
  InfoWindow,       // Popup windows
  MapControl,       // Custom controls on map
  Marker,           // Legacy marker (deprecated)
} from '@vis.gl/react-google-maps';

// Hooks
import {
  useMap,                  // Access google.maps.Map instance
  useMapsLibrary,          // Load additional libraries (places, geocoding, drawing)
  useAdvancedMarkerRef,    // Connect marker to InfoWindow
  useApiIsLoaded,          // Check if API is loaded
} from '@vis.gl/react-google-maps';

// Enums
import {
  ControlPosition,     // For MapControl positioning
  CollisionBehavior,   // For marker collision handling
} from '@vis.gl/react-google-maps';

tsx

// Components
import {
  APIProvider,      // Wraps app, loads Maps JS API
  Map,              // Map container
  AdvancedMarker,   // Modern marker (requires mapId)
  Pin,              // Customizable pin for AdvancedMarker
  InfoWindow,       // Popup windows
  MapControl,       // Custom controls on map
  Marker,           // Legacy marker (deprecated)
} from '@vis.gl/react-google-maps';

// Hooks
import {
  useMap,                  // Access google.maps.Map instance
  useMapsLibrary,          // Load additional libraries (places, geocoding, drawing)
  useAdvancedMarkerRef,    // Connect marker to InfoWindow
  useApiIsLoaded,          // Check if API is loaded
} from '@vis.gl/react-google-maps';

// Enums
import {
  ControlPosition,     // For MapControl positioning
  CollisionBehavior,   // For marker collision handling
} from '@vis.gl/react-google-maps';

Critical Requirements

关键要求

mapId is required for AdvancedMarker - Create one at Google Cloud Console > Maps > Map Styles
APIProvider must wrap all map components - Place at app root or layout level
Circle, Polygon, Polyline are NOT exported - See
```
references/geometry-components.md
```
for implementations
places.Autocomplete is deprecated (March 2025) - Use AutocompleteService with custom UI instead

AdvancedMarker必须指定mapId - 可在Google Cloud Console > 地图 > 地图样式中创建
APIProvider必须包裹所有地图组件 - 放置在应用根目录或布局层级
未导出Circle、Polygon、Polyline - 请查看
```
references/geometry-components.md
```
获取实现方案
places.Autocomplete已弃用（2025年3月）- 请改用AutocompleteService搭配自定义UI

Reference Files

参考文档

Read these files based on the task:

Task	Reference File
Map, Marker, InfoWindow, Pin details	`references/components-api.md`
useMap, useMapsLibrary, hooks	`references/hooks-api.md`
Circle, Polygon, Polyline	`references/geometry-components.md`
Places Autocomplete, Geocoding	`references/places-autocomplete.md`
Draggable markers + real-time sync, controlled maps	`references/patterns.md`

根据任务需求阅读以下文档：

任务	参考文档
地图、标记、信息窗口、图钉详情	`references/components-api.md`
useMap、useMapsLibrary等钩子	`references/hooks-api.md`
圆形、多边形、折线	`references/geometry-components.md`
地点自动补全、地理编码	`references/places-autocomplete.md`
可拖拽标记+实时同步、受控地图	`references/patterns.md`

Common Patterns

常见实现模式

Marker with InfoWindow

带信息窗口的标记

tsx

const MarkerWithInfo = ({ position }: { position: google.maps.LatLngLiteral }) => {
  const [markerRef, marker] = useAdvancedMarkerRef();
  const [open, setOpen] = useState(false);

  return (
    <>
      <AdvancedMarker ref={markerRef} position={position} onClick={() => setOpen(true)} />
      {open && (
        <InfoWindow anchor={marker} onClose={() => setOpen(false)}>
          <p>Hello!</p>
        </InfoWindow>
      )}
    </>
  );
};

tsx

const MarkerWithInfo = ({ position }: { position: google.maps.LatLngLiteral }) => {
  const [markerRef, marker] = useAdvancedMarkerRef();
  const [open, setOpen] = useState(false);

  return (
    <>
      <AdvancedMarker ref={markerRef} position={position} onClick={() => setOpen(true)} />
      {open && (
        <InfoWindow anchor={marker} onClose={() => setOpen(false)}>
          <p>Hello!</p>
        </InfoWindow>
      )}
    </>
  );
};

Draggable Marker with Real-Time Circle Sync

带实时圆形同步的可拖拽标记

tsx

const DraggableWithCircle = () => {
  const [position, setPosition] = useState({ lat: 18.4655, lng: -66.1057 });

  return (
    <>
      <AdvancedMarker
        position={position}
        draggable
        onDrag={(e) => {
          // Updates DURING drag for real-time sync
          if (e.latLng) setPosition({ lat: e.latLng.lat(), lng: e.latLng.lng() });
        }}
      />
      <Circle center={position} radius={1000} /> {/* Follows marker in real-time */}
    </>
  );
};

tsx

const DraggableWithCircle = () => {
  const [position, setPosition] = useState({ lat: 18.4655, lng: -66.1057 });

  return (
    <>
      <AdvancedMarker
        position={position}
        draggable
        onDrag={(e) => {
          // Updates DURING drag for real-time sync
          if (e.latLng) setPosition({ lat: e.latLng.lat(), lng: e.latLng.lng() });
        }}
      />
      <Circle center={position} radius={1000} /> {/* Follows marker in real-time */}
    </>
  );
};

Custom Map Control

自定义地图控件

tsx

<Map {...props}>
  <MapControl position={ControlPosition.TOP_LEFT}>
    <button onClick={handleClick}>Custom Button</button>
  </MapControl>
</Map>

tsx

<Map {...props}>
  <MapControl position={ControlPosition.TOP_LEFT}>
    <button onClick={handleClick}>Custom Button</button>
  </MapControl>
</Map>

TypeScript Types

TypeScript类型

tsx

// Position types
type LatLngLiteral = { lat: number; lng: number };
type LatLngAltitudeLiteral = { lat: number; lng: number; altitude: number };

// Event types
type MapMouseEvent = google.maps.MapMouseEvent;
type AdvancedMarkerClickEvent = google.maps.marker.AdvancedMarkerClickEvent;

// Library types (from useMapsLibrary)
type PlacesLibrary = google.maps.PlacesLibrary;
type GeocodingLibrary = google.maps.GeocodingLibrary;
type DrawingLibrary = google.maps.DrawingLibrary;

tsx

// Position types
type LatLngLiteral = { lat: number; lng: number };
type LatLngAltitudeLiteral = { lat: number; lng: number; altitude: number };

// Event types
type MapMouseEvent = google.maps.MapMouseEvent;
type AdvancedMarkerClickEvent = google.maps.marker.AdvancedMarkerClickEvent;

// Library types (from useMapsLibrary)
type PlacesLibrary = google.maps.PlacesLibrary;
type GeocodingLibrary = google.maps.GeocodingLibrary;
type DrawingLibrary = google.maps.DrawingLibrary;