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 决定画法”的实际效果。

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 之前。


🧪 小练习

  1. 为同一个面 Source 添加填充和轮廓图层。
  2. 编写一个可重复执行的 addBusinessLayers 函数。
// 请在这里编写代码

🎉 恭喜你已经掌握 Source 与 Layer 的核心用法啦!