Leaflet迁移指南

本指南旨在帮助您从Leaflet迁移到MapLibre GL JS；虽然这两个库都是用于创建交互式地图的开源JavaScript库，但它们的架构和功能有显著差异;

Leaflet和MapLibre GL JS之间的主要区别

Leaflet是一个专注于二维地图的轻量级库，主要使用栅格瓦片。而MapLibre GL JS是一个更现代的库，提供了二维和三维地图支持，主要使用矢量瓦片，并利用WebGL进行高性能渲染;

关键差异

特性LeafletMapLibre GL JS
瓦片类型主要是栅格瓦片主要是矢量瓦片
渲染主要是DOM和Canvas主要是WebGL
3D支持有限/通过插件原生支持
性能对于简单用例很好对于复杂可视化和大数据集更好
样式CSS和图像JSON样式规范
移动响应性良好优秀
社区庞大、成熟不断增长

地图初始化

Leaflet

// 初始化Leaflet地图
const map = L.map('map').setView([51.505, -0.09], 13);

// 添加瓦片图层
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

MapLibre GL JS

// 初始化MapLibre地图
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [-0.09, 51.505],
  zoom: 13
});

注意坐标顺序的不同：Leaflet使用[纬度, 经度]，而MapLibre使用[经度, 纬度];

添加标记

Leaflet

// 添加一个标记
const marker = L.marker([51.5, -0.09]).addTo(map);

// 添加一个带有弹出窗口的标记
marker.bindPopup("<b>你好!</b><br>我是一个弹出窗口。").openPopup();

MapLibre GL JS

// 添加一个标记
const marker = new maplibregl.Marker()
  .setLngLat([-0.09, 51.5])
  .addTo(map);

// 添加一个带有弹出窗口的标记
const popup = new maplibregl.Popup({ offset: 25 })
  .setHTML("<b>你好!</b><br>我是一个弹出窗口。");

marker.setPopup(popup);

处理事件

Leaflet

// 添加点击事件到地图
map.on('click', function(e) {
  console.log("点击坐标: " + e.latlng.toString());
});

// 添加事件到标记
marker.on('click', function(e) {
  console.log("标记被点击了!");
});

MapLibre GL JS

// 添加点击事件到地图
map.on('click', function(e) {
  console.log("点击坐标: " + e.lngLat.toString());
});

// 添加事件到标记
marker.getElement().addEventListener('click', function() {
  console.log("标记被点击了!");
});

添加GeoJSON

Leaflet

// 添加GeoJSON数据
const geojson = {
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [-0.09, 51.5]
  }
};

L.geoJSON(geojson).addTo(map);

MapLibre GL JS

// 等待地图加载完成
map.on('load', function() {
  // 添加GeoJSON数据作为源
  map.addSource('point', {
    'type': 'geojson',
    'data': {
      'type': 'Feature',
      'properties': {},
      'geometry': {
        'type': 'Point',
        'coordinates': [-0.09, 51.5]
      }
    }
  });

  // 添加图层来可视化数据
  map.addLayer({
    'id': 'point',
    'type': 'circle',
    'source': 'point',
    'paint': {
      'circle-radius': 10,
      'circle-color': '#3887be'
    }
  });
});

样式

在Leaflet中，样式通常通过CSS和JavaScript选项设置：

// Leaflet样式示例
const circle = L.circle([51.508, -0.11], {
  color: 'red',
  fillColor: '#f03',
  fillOpacity: 0.5,
  radius: 500
}).addTo(map);

在MapLibre GL JS中，样式是通过JSON样式规范和图层属性设置的：

// MapLibre样式示例
map.addLayer({
  'id': 'circle',
  'type': 'circle',
  'source': 'circle-source',
  'paint': {
    'circle-radius': 500,
    'circle-color': '#f03',
    'circle-opacity': 0.5,
    'circle-stroke-color': 'red',
    'circle-stroke-width': 1
  }
});

控件

Leaflet

// 添加缩放控件
L.control.zoom({
  position: 'topright'
}).addTo(map);

// 添加比例尺
L.control.scale().addTo(map);

MapLibre GL JS

// 添加导航控件（包含缩放控件）
map.addControl(new maplibregl.NavigationControl(), 'top-right');

// 添加比例尺
map.addControl(new maplibregl.ScaleControl());

自定义控件

Leaflet

// 创建自定义控件
const customControl = L.Control.extend({
  options: {
    position: 'topright'
  },

  onAdd: function(map) {
    const container = L.DomUtil.create('div', 'leaflet-bar leaflet-control leaflet-control-custom');
    container.style.backgroundColor = 'white';
    container.style.width = '30px';
    container.style.height = '30px';
    container.innerHTML = '<button>C</button>';
    
    container.onclick = function() {
      console.log('自定义控件被点击了!');
    }
    
    return container;
  }
});

// 添加到地图
map.addControl(new customControl());

MapLibre GL JS

// 创建自定义控件
class CustomControl {
  onAdd(map) {
    this._map = map;
    this._container = document.createElement('div');
    this._container.className = 'maplibregl-ctrl maplibregl-ctrl-group';
    this._container.innerHTML = '<button><span>C</span></button>';
    
    this._container.onclick = function() {
      console.log('自定义控件被点击了!');
    };
    
    return this._container;
  }
  
  onRemove() {
    this._container.parentNode.removeChild(this._container);
    this._map = undefined;
  }
}

// 添加到地图
map.addControl(new CustomControl(), 'top-right');

图层控制

Leaflet

// 创建基础图层
const osm = L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
});

const satellite = L.tileLayer('https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}', {
  attribution: 'Tiles &copy; Esri'
});

// 创建图层控制器
const baseMaps = {
  "标准地图": osm,
  "卫星影像": satellite
};

L.control.layers(baseMaps).addTo(map);

MapLibre GL JS

MapLibre GL JS没有内置的图层切换控件，但我们可以创建一个简单的自定义控件：

// 创建自定义图层切换控件
const layerSwitcher = document.createElement('div');
layerSwitcher.className = 'maplibregl-ctrl maplibregl-ctrl-group';
layerSwitcher.innerHTML = `
  <select id="layer-switcher" style="margin: 5px;">
    <option value="standard">标准地图</option>
    <option value="satellite">卫星影像</option>
  </select>
`;

// 切换样式
document.getElementById('layer-switcher').onchange = function(e) {
  const style = e.target.value;
  if (style === 'standard') {
    map.setStyle('https://demotiles.maplibre.org/style.json');
  } else if (style === 'satellite') {
    map.setStyle('https://api.maptiler.com/maps/hybrid/style.json?key=YOUR_KEY');
  }
};

// 添加到地图（作为自定义控件）
document.querySelector('.maplibregl-ctrl-top-right').appendChild(layerSwitcher);

结语

这个指南涵盖了从Leaflet迁移到MapLibre GL JS的基础知识，但两个库之间还有许多其他差异。MapLibre GL JS提供了更强大的功能，如3D地图、高性能渲染和更多的自定义选项，但也有更陡峭的学习曲线;

在迁移过程中，建议查阅MapLibre GL JS文档以获取更详细的信息和示例;