Mapbox 与 deck.gl 深度集成

理解 MapboxOverlay、interleaved、相机同步和 Mapbox Layer 与 deck.gl Layer 的协作方式。

🎯 引言

学完这篇文章,你能解释 Mapbox 和 deck.gl 如何共同渲染一张地图,并根据图层顺序和交互需求选择合适的集成方式。

🧭 相机同步、图层顺序与渲染模式

MapboxOverlay 已经把 deck.gl Layer 接入 Mapbox。接入之后需要重点处理三个问题:两套图层如何参与渲染、相机状态由谁管理,以及地图事件和图形事件如何分工。

职责边界仍然是:Mapbox 管地图,deck.gl 管业务数据可视化。不要把 Mapbox Layer 和 deck.gl Layer 当成同一个 API。

⚡ interleaved 与渲染模式

默认的 interleaved: true 会让 deck.gl 和 Mapbox 尽量共享 WebGL 渲染流程,图层可以更自然地参与地图样式的前后关系。非 interleaved 模式会把 deck.gl 内容作为覆盖层绘制在 Mapbox 画布上,理解起来更简单,但图层和地图样式的混合能力较弱。

需要让 deck.gl 与 Mapbox 共享 WebGL 渲染流程时,可以这样设置:

const overlay = new MapboxOverlay({
    interleaved: true,
    layers,
});

🧭 相机同步与图层顺序

Mapbox Camera 是相机的唯一来源:

Mapbox Camera
    ↓
MapboxOverlay
    ↓
deck.gl Layer

拖动地图时不需要手动把 viewState 传给 deck.gl。需要控制 deck.gl 图层和 Mapbox 样式图层的前后关系时,可以使用 beforeId;使用 Mapbox Standard Style 时,还要根据样式版本考虑 slot 等配置。

new ScatterplotLayer({
    id: 'stations',
    data: stations,
    beforeId: 'road-label',
    getPosition: (item) => item.position,
    getRadius: 400,
});

实际效果可以理解为:Mapbox 底图、道路和地名与 deck.gl 面、线、点共同组成一张地图。

Mapbox 地图可以加载底图,同时叠加 deck.gl 路径和点图层:

Mapbox:底图与相机 deck.gl:业务图层

🔁 两套 Layer 与两套事件

Mapbox Layer:依赖 Source、Style、filter 和地图样式系统
deck.gl Layer:依赖 data、accessor、GPU 属性和 Picking

同理,map.on('move') 是 Mapbox 地图事件,onHover 是 deck.gl 图层事件。项目中可以同时使用它们,但要明确每个回调属于哪套系统。

🧾 小节总结

  • MapboxOverlay 把 deck.gl Layer 接入 Mapbox。
  • interleaved: true 是本课程的统一集成方式。
  • Mapbox Camera 驱动地图视角,deck.gl 自动跟随。
  • beforeId 和样式图层顺序决定两套渲染内容的前后关系。

❓ 知识问答

Q1:为什么不再单独维护 deck.gl 的 ViewState?

因为 Mapbox 管理地图相机,Overlay 会把相机变化同步给 deck.gl。

Q2:Mapbox Layer 和 deck.gl Layer 能互相替换吗?

它们有重叠场景,但底层能力不同。应根据数据量、样式系统、动画和拾取需求选择。

Q3:什么时候使用非 interleaved 模式?

需要简单覆盖层、或当前 Mapbox 渲染环境不适合共享 WebGL 流程时,可以考虑非 interleaved 模式。

🧪 小练习

  1. 给 deck.gl 图层增加 beforeId,观察它和 Mapbox 地名图层的前后关系。
  2. 监听 Mapbox 的 zoomend,在缩放结束后打印当前地图缩放级别。

🎉 这一篇完成后,你已经理解了 Mapbox + deck.gl 的整体渲染架构。