首页 / MapLibre / API 文档
Layer
先看结论
图层是绘制指令：拿一个数据源，按几何类型和样式规则画出来。
map.addLayer(layer, beforeId)
通用字段
| 字段 | 必需 | 说明 |
|---|---|---|
id | 是 | 全图唯一，后续改属性、删图层都靠它 |
type | 是 | 见下表 |
source | 是 | 数据源 id；background 图层例外 |
source-layer | 矢量瓦片必填 | 瓦片内部的图层名 |
minzoom / maxzoom | 否 | 可见的缩放区间，包含端点 |
filter | 否 | 按属性或几何类型筛选要素 |
layout | 否 | 排布与可见性 |
paint | 否 | 外观 |
类型
| type | 接受的几何 | 典型用途 |
|---|---|---|
background | 无 | 整幅画布底色 |
fill | Polygon | 面填充 |
line | LineString、Polygon 边界 | 路线、描边 |
circle | Point | 点位，按属性控制半径与颜色 |
symbol | Point、LineString | 图标与文字标注 |
heatmap | Point | 密度热力 |
fill-extrusion | Polygon | 建筑体块等三维面 |
raster | 栅格源 | 影像、扫描图 |
hillshade | raster-dem | 地形晕渲 |
示例
map.addLayer({
id: 'zones-fill',
type: 'fill',
source: 'zones',
paint: {
'fill-color': ['get', 'color'],
'fill-opacity': 0.35
}
}, 'labels'); // 插到 labels 图层下面
beforeId 省略时图层加到最上层。指向不存在的 id 时，
行为等同于加到最上层，不会报错。
筛选与缩放区间
map.addLayer({
id: 'major-roads',
type: 'line',
source: 'base',
'source-layer': 'roads',
filter: ['all',
['==', ['get', 'class'], 'primary'],
['>', ['get', 'length'], 500]
],
minzoom: 8,
paint: { 'line-color': '#c2410c', 'line-width': 2 }
});
条件尽量写在 filter 和 minzoom 里，
让不需要的要素在渲染前就被排除。用表达式在 paint 里返回透明色，
几何仍然会被处理，数据量大时性能差一截。
图层没有出现时的检查顺序
- source 是否存在，id 是否与
addSource一致。 - 矢量瓦片的
source-layer是否真实存在。 - filter 是否把所有要素都排除了。
- 当前缩放是否落在
minzoom–maxzoom之外。 - 图层是否被上层不透明的面或栅格完全遮住。
- 几何类型是否与图层 type 匹配，例如把线交给 fill 图层不会报错但画不出来。
id 命名带上用途前缀。zones-fill、zones-line
比 layer1、layer2 更容易在运行时排查，
也能避免与底图图层重名。
经纬志（2026）。《Layer》。https://www.jingweizhi.com/maplibre/api/layer.html（访问日期 2026-11-03）。