首页 / MapLibre / API 文档

Map

先看结论

地图实例，负责渲染、视角、数据源、图层和全部交互。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-27 · 引用本文

new maplibregl.Map(options) → Map

构造参数

参数	类型 / 默认	说明
`container`	string / HTMLElement	容器 id 或元素，必须有确定高度
`style`	object / string，必填	样式对象或样式 URL
`center`	`[lng, lat]`	初始中心，经度在前
`zoom`	number	初始缩放级别
`pitch`	0	俯仰角，0–60 常用，最大 85
`bearing`	0	旋转角，正值为顺时针
`minZoom` / `maxZoom`	0 / 22	缩放范围
`maxBounds`	—	`[[西,南],[东,北]]`，限制可拖出范围
`attributionControl`	true	可传对象：`{compact, customAttribution}`
`interactive`	true	是否开启拖拽、缩放等交互
`hash`	false	把视角写进 URL 的 hash，便于分享
`antialias`	false	开启后线条更平滑，显存占用增加
`preserveDrawingBuffer`	false	截图或读取画布像素时必须开启

视角方法

方法	说明
`jumpTo({center, zoom, pitch, bearing})`	立即跳转，无动画
`easeTo(options)`	线性或缓动过渡
`flyTo(options)`	带弧线的飞行动画，长距离时缩放会自动拉远视角
`fitBounds(bounds, {padding, duration})`	缩放到恰好容纳范围
`setCenter` / `setZoom` / `setPitch` / `setBearing`	单项设置，均可带动画参数
`getCenter()`	返回 `LngLat`
`getBounds()`	返回 `LngLatBounds`，`.toArray()` 得到 `[[西,南],[东,北]]`
`getZoom()` / `getPitch()` / `getBearing()`	读取当前视角
`resize()`	容器尺寸变化后调用，等同于 Leaflet 的 invalidateSize

map.flyTo({
  center: [116.391263, 39.907359],
  zoom: 9,
  pitch: 45,
  bearing: -20,
  duration: 2000,
  essential: true
});

/* 动画结束后读取，不要依赖动画开始时的值 */
map.once('moveend', function () {
  console.log(map.getCenter().toArray(), map.getZoom());
});

数据源与图层

方法	说明
`addSource(id, source)`	添加数据源，id 全图唯一
`getSource(id)`	取回源对象，GeoJSON 源可调用 `setData`
`removeSource(id)`	删除源，必须先删除引用它的图层
`addLayer(layer, beforeId)`	添加图层，可指定插入位置
`getLayer(id)` / `removeLayer(id)`	查询与删除图层
`moveLayer(id, beforeId)`	调整绘制顺序
`queryRenderedFeatures(point, options)`	查询屏幕点位下可见的要素
`setPaintProperty` / `setLayoutProperty`	运行时修改样式属性

事件

事件	触发时机	`e` 中的关键字段
`load`	样式与首批资源就绪	—
`style.load`	样式被加载或替换	—
`click`	单击地图	`lngLat`、`point`、`features`
`mousemove`	指针移动，每帧触发	`lngLat`、`point`
`moveend`	拖拽或动画结束	—
`zoomend`	缩放结束	—
`idle`	渲染完成且无待处理任务	—
`error`	瓦片或样式加载出错	`error.message`

map.on('click', function (e) {
  console.log(e.lngLat.lng, e.lngLat.lat);
});

map.on('error', function (e) {
  console.warn('地图错误：', e.error && e.error.message);
});

销毁

map.remove() 释放 WebGL 上下文、事件与 DOM。单页应用里路由切换时务必调用，否则每进一次页面就多占一个 WebGL 上下文，浏览器上限通常是十几个，超出后新地图直接初始化失败。

不要在构造后立刻操作图层。样式是异步加载的，自定义源与图层应放在 load 回调中，否则会得到「源不存在」的错误。

引用本文

经纬志（2026）。《Map》。https://www.jingweizhi.com/maplibre/api/map.html（访问日期 2026-11-03）。