react-google-maps
在React中实现Google Maps的@vis.gl/react-google-maps库专家。在构建地图、标记、图钉、信息窗口、地点自动完成、地理编码、可拖动标记、多边形、圆形、折线、绘图工具或React/Next.js应用程序中任何Google Maps JavaScript API集成时使用
📖 中文导读:在React中实现Google Maps的@vis.gl/react-google-maps库专家。在构建地图、标记、图钉、信息窗口、地点自动完成、地理编码、可拖动标记、多边形、圆形、折线、绘图工具或React/Next.js应用程序中任何Google Maps JavaScript API集成时使用 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: react-google-maps description: Expert implementation of @vis.gl/react-google-maps library for Google Maps in React. Use when building maps, markers, pins, infowindows, places autocomplete, geocoding, draggable markers, polygons, circles, polylines, drawing tools, or any Google Maps JavaScript API integration in React/Next.js applications.
@vis.gl/react-google-maps
Official React library for Google Maps JavaScript API, maintained by vis.gl with Google sponsorship.
Quick Start
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
npm install @vis.gl/react-google-maps
Key Exports
// 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.mdfor implementations - places.Autocomplete is deprecated (March 2025) - Use AutocompleteService with custom UI instead
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 |
Common Patterns
Marker with InfoWindow
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
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
<Map {...props}>
<MapControl position={ControlPosition.TOP_LEFT}>
<button onClick={handleClick}>Custom Button</button>
</MapControl>
</Map>
TypeScript Types
// 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;