跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

mapbox-google-maps-migration

Migration guide for developers moving from Google Maps Platform to Mapbox GL JS, covering API equivalents, pattern translations, and key differences

mapbox · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add mapbox/mapbox-agent-skills --skill mapbox-google-maps-migration

技能说明


name: mapbox-google-maps-migration description: Migration guide for developers moving from Google Maps Platform to Mapbox GL JS, covering API equivalents, pattern translations, and key differences

Mapbox Google Maps Migration Skill

Comprehensive guidance for migrating from Google Maps Platform to Mapbox GL JS. Provides API equivalents, pattern translations, and strategies for successful migration.

Core Philosophy Differences

Google Maps: Imperative & Object-Oriented

  • Create objects (Marker, Polygon, etc.)
  • Add to map with .setMap(map)
  • Update properties with setters
  • Heavy reliance on object instances

Mapbox GL JS: Declarative & Data-Driven

  • Add data sources
  • Define layers (visual representation)
  • Style with JSON
  • Update data, not object properties

Key Insight: Mapbox treats everything as data + styling, not individual objects.

Map Initialization

Google Maps

const map = new google.maps.Map(document.getElementById('map'), {
  center: { lat: 37.7749, lng: -122.4194 },
  zoom: 12,
  mapTypeId: 'roadmap' // or 'satellite', 'hybrid', 'terrain'
});

Mapbox GL JS

mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12', // or satellite-v9, outdoors-v12
  center: [-122.4194, 37.7749], // [lng, lat] - note the order!
  zoom: 12
});

Key Differences:

  • Coordinate order: Google uses {lat, lng}, Mapbox uses [lng, lat]
  • Authentication: Google uses API key in script tag, Mapbox uses access token in code
  • Styling: Google uses map types, Mapbox uses full style URLs

API Equivalents Reference

Map Methods

Google MapsMapbox GL JSNotes
map.setCenter(latLng)map.setCenter([lng, lat])Coordinate order reversed
map.getCenter()map.getCenter()Returns LngLat object
map.setZoom(zoom)map.setZoom(zoom)Same behavior
map.getZoom()map.getZoom()Same behavior
map.panTo(latLng)map.panTo([lng, lat])Animated pan
map.fitBounds(bounds)map.fitBounds([[lng,lat],[lng,lat]])Different bound format
map.setMapTypeId(type)map.setStyle(styleUrl)Completely different approach
map.getBounds()map.getBounds()Similar

Map Events

Google MapsMapbox GL JSNotes
google.maps.event.addListener(map, 'click', fn)map.on('click', fn)Simpler syntax
event.latLngevent.lngLatEvent property name
'center_changed''move' / 'moveend'Different event names
'zoom_changed''zoom' / 'zoomend'Different event names
'bounds_changed''moveend'No direct equivalent
'mousemove''mousemove'Same
'mouseout''mouseleave'Different name

Markers and Points

Simple Marker

Google Maps:

const marker = new google.maps.Marker({
  position: { lat: 37.7749, lng: -122.4194 },
  map: map,
  title: 'San Francisco',
  icon: 'custom-icon.png'
});

// Remove marker
marker.setMap(null);

Mapbox GL JS:

// Create marker
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// Remove marker
marker.remove();

Multiple Markers

Google Maps:

const markers = locations.map(
  (loc) =>
    new google.maps.Marker({
      position: { lat: loc.lat, lng: loc.lng },
      map: map
    })
);

Mapbox GL JS (Equivalent Approach):

// Same object-oriented approach
const markers = locations.map((loc) => new mapboxgl.Marker().setLngLat([loc.lng, loc.lat]).addTo(map));

Mapbox GL JS (Data-Driven Approach - Recommended for 100+ points):

// Add as GeoJSON source + layer (uses WebGL, not DOM)
map.addSource('points', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: locations.map((loc) => ({
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [loc.lng, loc.lat] },
      properties: { name: loc.name }
    }))
  }
});

map.addLayer({
  id: 'points-layer',
  type: 'circle', // or 'symbol' for icons
  source: 'points',
  paint: {
    'circle-radius': 8,
    'circle-color': '#ff0000'
  }
});

Performance Advantage: Google Maps renders all markers as DOM elements (even when using the Data Layer), which becomes slow with 500+ markers. Mapbox's circle and symbol layers are rendered by WebGL, making them much faster for large datasets (1,000-10,000+ points). This is a significant advantage when building applications with many points.

Info Windows / Popups

Google Maps

const infowindow = new google.maps.InfoWindow({
  content: '<h3>Title</h3><p>Content</p>'
});

marker.addListener('click', () => {
  infowindow.open(map, marker);
});

Mapbox GL JS

// Option 1: Attach to marker
const marker = new mapboxgl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setHTML('<h3>Title</h3><p>Content</p>'))
  .addTo(map);

// Option 2:
阅读完整来源 ↗