Source 与 Layer 核心概念
🎯 引言
学完本文,你能把业务数据接入地图,用多个图层复用同一份数据,并正确处理图层顺序、删除和样式重载。
🧱 Source 是数据,Layer 是画法
**Source(数据源)**告诉地图“数据是什么”,**Layer(图层)**告诉地图“把数据画成什么样”。分离后,同一份道路数据既能画宽线作为底色,也能再画细线作为中心线,不必复制数据。
map.addSource('places', {
type: 'geojson',
data: {
type: 'FeatureCollection',
features: [],
},
})
map.addLayer({
id: 'place-circles',
type: 'circle',
source: 'places',
paint: {
'circle-radius': 7,
'circle-color': '#2563eb',
},
})
places 是 Source ID,place-circles 是 Layer ID。每个 Source ID 在数据源中不能重复,每个 Layer ID 在图层中不能重复;后续查询、更新和删除资源都依靠这些 ID。
🗺 常见 Layer 类型
| 类型 | 适合显示 |
|---|---|
circle | 点位置和按数值变化的圆点 |
line | 路线、轨迹和边界线 |
fill | 行政区、地块等面对象 |
symbol | 图标和文字标签 |
raster | 影像、栅格瓦片和已渲染地图图片 |
点表示位置,线表示路径,面表示封闭区域。选择 Layer 类型时先看 Geometry 类型,再看需要的视觉表达。
下面的组件一开始只注册 Source,因此地图上看不到业务数据。点击按钮添加可见 Layer 后,同一份 Source 会同时通过 fill、line、circle 和 symbol 显示。这就是“Source 保存数据,Layer 决定画法”的实际效果。
🥞 复用数据与控制顺序
一个区域通常既要有半透明填充,也要有清晰边框。区域坐标只保存一份,放在 areas Source 中;Fill Layer 和 Line Layer 同时读取这个 Source:
map.addLayer({
id: 'area-fill',
type: 'fill',
source: 'areas',
paint: { 'fill-color': '#60a5fa', 'fill-opacity': 0.25 },
})
map.addLayer({
id: 'area-outline',
type: 'line',
source: 'areas',
paint: { 'line-color': '#2563eb', 'line-width': 2 },
})
这样做的作用是避免复制区域数据。调用一次 setData() 更新 areas Source 后,填充和边框会一起更新。
Layer 按 Style 中的先后顺序绘制,后面的 Layer 会盖在前面的 Layer 上。边框需要显示在填充上面,所以先添加 area-fill,再添加 area-outline。
需要在运行期间调整顺序时,可以调用:
map.moveLayer('area-outline')
map.moveLayer('area-fill', 'area-outline')
第一个写法把边框移到所有 Layer 的顶部;第二个写法把填充移到边框之前,也就是边框下方。
下面的组件使用一份 Source 绘制紫色面、橙色线和绿色点。点击“把点移到面下方”,可以看到绘制顺序如何改变覆盖结果:
🔎 判断与删除资源
地图模块可能被重复打开和关闭。例如,用户打开“区域”模块时添加 Source 和 Layer,关闭模块时再把它们删除。
重复添加相同 ID 会报错,因此添加前要用 getSource()、getLayer() 判断资源是否已经存在。下面是完整的添加函数:
function addAreaResources(areaGeoJSON) {
if (!map.getSource('areas')) {
map.addSource('areas', {
type: 'geojson',
data: areaGeoJSON,
})
}
if (!map.getLayer('area-fill')) {
map.addLayer({
id: 'area-fill',
type: 'fill',
source: 'areas',
paint: { 'fill-color': '#60a5fa', 'fill-opacity': 0.25 },
})
}
if (!map.getLayer('area-outline')) {
map.addLayer({
id: 'area-outline',
type: 'line',
source: 'areas',
paint: { 'line-color': '#2563eb', 'line-width': 2 },
})
}
}
删除时顺序相反。Layer 仍在读取 Source 时,Mapbox 不允许删除 Source,所以要先删除所有相关 Layer:
function removeAreaResources() {
if (map.getLayer('area-outline')) map.removeLayer('area-outline')
if (map.getLayer('area-fill')) map.removeLayer('area-fill')
if (map.getSource('areas')) map.removeSource('areas')
}
getLayer() 和 getSource() 在这里不是查询业务数据,而是检查 Mapbox 中是否已经注册了对应 ID。存在性判断让添加和删除函数可以安全地重复调用。
下面的组件会真实添加和删除一个区域 Source、填充 Layer 和边框 Layer。删除按钮严格按照“先 Layer,后 Source”的顺序执行:
🧭 在 Standard Style 中指定图层位置
Mapbox Standard 的底图结构会随样式更新,业务图层不要依赖某个内部底图 Layer ID。添加 Layer 时使用 slot,可以把业务数据放到相对稳定的位置:
map.addLayer({
id: 'area-fill',
type: 'fill',
source: 'areas',
slot: 'middle',
paint: {
'fill-color': '#60a5fa',
'fill-opacity': 0.35,
},
})
slot | 业务图层所在位置 |
|---|---|
bottom | 位于底图面对象之上 |
middle | 位于道路之上、三维建筑之后 |
top | 位于兴趣点标签之上、地点和交通标签之后 |
| 不设置 | 位于 Standard 自带图层之上 |
同一个 slot 内仍可使用 moveLayer() 调整业务图层之间的顺序。使用 light-v11 等传统 Style 时没有这些插槽,应继续通过 addLayer 的第二个参数或 moveLayer() 指定位置。
Standard Style 的主题和标签显隐不需要遍历底图 Layer,可以在初始化时通过 config 设置,也可以在运行期间修改:
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/standard',
config: {
basemap: {
theme: 'monochrome',
showPointOfInterestLabels: false,
},
},
})
map.setConfigProperty('basemap', 'lightPreset', 'dusk')
theme 控制底图主题,showPointOfInterestLabels 控制兴趣点标签,lightPreset 可使用 dawn、day、dusk 或 night。这类配置只影响 Standard Style,传统 Style 仍通过 Layer 属性或更换 Style 调整外观。
🔄 Style 重载后的业务资源
用户切换浅色、深色底图时,可以调用 setStyle()。这个方法替换的是地图的整套 Style,其中包含底图 Layer,也包含代码运行期间添加的 Source 和 Layer。
因此,下面这次切换完成后,旧 Style 中的 areas Source、area-fill Layer 和 area-outline Layer 都不存在了:
map.setStyle('mapbox://styles/mapbox/dark-v11')
如果仍要显示业务区域,需要等待新 Style 加载完成,再把业务 Source 和 Layer 添加到新 Style 中:
map.on('style.load', () => {
addAreaResources(areaGeoJSON)
})
map.setStyle('mapbox://styles/mapbox/light-v11')
这里的 areaGeoJSON 是应用当前保存的区域数据。style.load 表示新 Style 已经可以接收 Source 和 Layer;前面编写的 addAreaResources() 会重新添加区域资源,并检查相同 ID 是否已经存在。
下面先点击“只切换 Style”,可以看到绿色业务区域随旧 Style 一起消失;再点击“切换并恢复业务区域”,组件会在 style.load 后重新添加 Source 和 Layer:
🧾 小节总结
- Source 保存数据,Layer 决定数据如何显示。
- 一个 Source 可以被多个 Layer 复用。
- Layer 顺序决定覆盖关系,可用
moveLayer调整。 - 添加和删除前使用
getSource、getLayer判断存在性。 - 删除 Source 前先删除引用它的 Layer。
- Standard Style 使用
slot安排图层位置,并通过config调整底图外观。 - 切换 Style 后需要恢复运行时业务资源。
❓ 知识问答
Q1:为什么不能直接给 Source 配颜色?
Source 只负责数据,颜色属于可视化规则,应写在 Layer 的 paint 中。
Q2:同一份面数据为什么常用两个 Layer?
fill 负责内部填充,line 负责清晰轮廓,两者样式可以分别控制。
Q3:moveLayer('a', 'b') 表示什么?
把 a 移到 b 的下方,也就是 Style 图层列表中 b 之前。
🧪 小练习
- 为同一个面 Source 添加填充和轮廓图层。
- 编写一个可重复执行的
addBusinessLayers函数。
// 请在这里编写代码
🎉 恭喜你已经掌握 Source 与 Layer 的核心用法啦!
