从Leaflet迁移到MapLibre GL JS的完整指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00458/article/details/148443212

从Leaflet迁移到MapLibre GL JS的完整指南

maplibre-gl-js MapLibre GL JS - Interactive vector tile maps in WebGL2 项目地址: https://gitcode.com/gh_mirrors/ma/maplibre-gl-js

前言

MapLibre GL JS是一个开源的Web地图库，基于WebGL技术构建，相比传统的Leaflet库具有更强大的功能和性能优势。本文将详细介绍如何将现有的Leaflet项目迁移到MapLibre GL JS，帮助开发者理解两者之间的差异并顺利完成迁移。

核心差异概述

在开始迁移前，了解两个库的主要差异非常重要：

渲染技术：Leaflet使用DOM和Canvas渲染，而MapLibre GL JS基于WebGL，性能更高
功能支持：MapLibre支持3D地图、地图旋转、矢量切片等高级功能
数据加载：MapLibre采用"样式-数据"分离的架构，与Leaflet的直接加载方式不同
坐标系：Leaflet使用LatLng(纬度,经度)，MapLibre使用LngLat(经度,纬度)

环境准备

首先需要安装MapLibre GL JS库：

npm install maplibre-gl

同时需要在项目中引入CSS样式文件：

import 'maplibre-gl/dist/maplibre-gl.css';

基础地图初始化对比

Leaflet方式

const map = L.map('map').setView([0, 0], 2);

L.tileLayer('https://{s}.tile.example.com/{z}/{x}/{y}.png', {
  attribution: '&copy; 地图数据贡献者'
}).addTo(map);

MapLibre方式

import {Map} from 'maplibre-gl';

const map = new Map({
  container: 'map',  // 容器ID
  style: 'https://example.org/style.json',  // 地图样式
  center: [0, 0],    // 初始中心点[经度,纬度]
  zoom: 2            // 初始缩放级别
});

关键区别：

MapLibre需要指定完整的样式配置而非单独瓦片URL
坐标顺序不同(经度在前)
初始化方式为构造函数而非链式调用

常用功能迁移指南

1. 添加标记点(Marker)

Leaflet实现：

L.marker([51.5, -0.1])
  .addTo(map)
  .bindPopup('示例城市');

MapLibre实现：

new maplibregl.Marker()
  .setLngLat([-0.1, 51.5])  // 注意坐标顺序
  .setPopup(new maplibregl.Popup().setHTML('示例城市'))
  .addTo(map);

2. 加载GeoJSON数据

Leaflet实现：

L.geoJSON(geojsonData, {
  style: {color: '#ff0000'}
}).addTo(map);

MapLibre实现：

map.on('load', () => {
  map.addSource('my-data', {
    type: 'geojson',
    data: geojsonData
  });
  
  map.addLayer({
    id: 'data-layer',
    type: 'fill',
    source: 'my-data',
    paint: {
      'fill-color': '#ff0000',
      'fill-opacity': 0.8
    }
  });
});

重要说明：

MapLibre需要显式定义数据源(source)和图层(layer)
样式通过paint属性配置，支持更丰富的样式表达式
操作需要在map加载完成后进行

3. 事件处理

点击事件对比：

// Leaflet
map.on('click', (e) => {
  console.log(e.latlng);  // {lat: 51.5, lng: -0.1}
});

// MapLibre
map.on('click', (e) => {
  console.log(e.lngLat);  // {lng: -0.1, lat: 51.5}
});

4. 自定义瓦片图层

Leaflet实现：

L.tileLayer('https://tile.example.com/{z}/{x}/{y}.png').addTo(map);

MapLibre实现：

map.addSource('custom-tiles', {
  type: 'raster',
  tiles: ['https://tile.example.com/{z}/{x}/{y}.png'],
  tileSize: 256
});

map.addLayer({
  id: 'custom-layer',
  type: 'raster',
  source: 'custom-tiles'
});

高级功能迁移

1. 地图旋转

MapLibre支持地图旋转功能，这是Leaflet不具备的：

map.setBearing(45);  // 旋转45度

2. 3D地形

MapLibre可以添加3D地形效果：

map.addSource('terrain', {
  type: 'raster-dem',
  url: 'https://example.org/terrain-tiles/tiles.json',
  tileSize: 256
});

map.setTerrain({source: 'terrain', exaggeration: 1.5});