经纬志
首页 / MapLibre / API 文档

addLayer

先看结论

把图层插进样式，图层顺序就是绘制顺序，后添加的画在上面。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文
map.addLayer(layerObject, beforeId?, options?)

参数

参数类型说明
layerobject图层定义，至少包含 id 与 type
beforeIdstring插到该图层之前（视觉上在其下方）；省略则加到最顶
options.validateboolean默认 true，校验图层是否符合样式规范

图层字段

字段必填说明
id是全样式唯一，重复会报错
type是见下方类型表
source除 background 外已添加的数据源 id
source-layer矢量源必需瓦片内的图层名
filter否要素过滤表达式
layout / paint否布局与绘制属性
minzoom / maxzoom否图层可见的级别区间
metadata否自定义信息，原样保留

图层类型

type用途
background整块画布底色，不需要数据源
fill面填充
line线
symbol图标与文字标注
circle圆点
heatmap热力图
fill-extrusion拉伸成体块
raster栅格影像
hillshade高程晕渲
sky天空与雾效，通常用 setSky 配置

相关成员

成员说明
getLayer(id)返回图层对象，不存在时为 undefined
moveLayer(id, beforeId?)调整已有图层的顺序
removeLayer(id)删除图层
addSource(id, spec)先建数据源，再添加引用它的图层

示例

map.addSource('cities', {
  type: 'geojson',
  data: { type: 'FeatureCollection', features: [] }
});

/* 不指定 beforeId，插到最顶 */
map.addLayer({
  id: 'city-dots',
  type: 'circle',
  source: 'cities',
  paint: {
    'circle-radius': 5,
    'circle-color': '#1f5fd0'
  }
});

/* 插到国界线之下，避免压住边界 */
map.addLayer({
  id: 'city-halo',
  type: 'circle',
  source: 'cities',
  paint: {
    'circle-radius': 10,
    'circle-color': '#1f5fd0',
    'circle-opacity': 0.18
  }
}, 'world-line');

注意事项

样式未加载完就调用会报「Style is not done loading」。 把添加逻辑放在 map.on('load') 或 map.on('style.load') 里，是唯一稳定的时机。

同一 id 重复添加会抛错。运行时增删频繁的图层，先 getLayer(id) 判断存在，再决定添加还是更新属性， 比捕获异常更省。

顺序错了看起来像样式错了。面图层压住线图层时，边界会消失； 把新图层插到 beforeId 指定的位置，比事后调透明度可靠。

引用本文

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