首页 / MapLibre / API 文档
moveLayer
先看结论
调整图层在样式中的位置，从而改变绘制先后；后画的压在上面。
map.moveLayer(id, beforeId?) → this
参数
| 参数 | 说明 |
|---|---|
id | 要移动的图层 id |
beforeId | 移动到该图层之前（即显示在它下面）；省略时移到最上层 |
这里的「之前」指样式数组中的前一位，绘制更早，视觉上更靠下。
要把 A 压在 B 上面，应写 moveLayer('A', B 的下一个图层)，
或者直接把 A 移到最顶层。
移到最顶层
map.addLayer({
id: 'hover-outline',
type: 'line',
source: 'districts',
paint: { 'line-color': '#ff8a3d', 'line-width': 3 }
});
/* 高亮层必须在最上面，否则被填充盖住 */
map.moveLayer('hover-outline');插到指定位置
/* 自定义注记放在路网之上、官方标注之下 */
map.moveLayer('my-labels', 'road-label');
/* 想放在某个图层之上，就找它后面那一层的 id */
var order = map.getStyle().layers.map(function (l) { return l.id; });
var idx = order.indexOf('my-labels');
console.log(order[idx + 1]);
map.getStyle().layers 按从下到上的顺序返回全部图层，
用它可以算出相邻图层的 id。样式切换后这个顺序会变，不能写死。
为什么顺序重要
| 影响 | 说明 |
|---|---|
| 遮挡 | 面图层放在注记之上会盖住文字 |
| 半透明叠加 | 多层半透明填充叠加，颜色随顺序变化 |
| 命中查询 | queryRenderedFeatures 每层都会命中，挑选时要看图层优先级 |
| 性能 | 同类型图层相邻可减少绘制状态切换 |
与 addLayer 的 beforeId 一致
addLayer(layer, beforeId) 也接受同样的位置参数。
新加图层时直接给位置，比先加再 moveLayer 少一次样式更新。
map.addLayer({
id: 'mask',
type: 'fill',
source: 'mask',
paint: { 'fill-color': '#000', 'fill-opacity': 0.35 }
}, 'district-line');beforeId 不存在时移动不会生效。
样式切换、图层重命名后旧 id 失效，控制台会给出提示。
移动前先用 map.getLayer(beforeId) 确认目标存在，省略参数则总是移到顶层。
经纬志（2026）。《moveLayer》。https://www.jingweizhi.com/maplibre/api/move-layer.html（访问日期 2026-11-03）。