首页 / deck.gl / API 文档
Deck
先看结论
deck.gl 的主类。管理画布、视角控制器、图层栈和拾取。
new deck.Deck(props)
核心参数
| 参数 | 说明 |
|---|---|
canvas | 画布元素或 id。用这种方式必须给 width / height |
width / height | 尺寸，可传数字或 '100%' |
layers | 图层数组，每次更新整体替换 |
initialViewState | 初始视角：longitude、latitude、zoom、pitch、bearing |
viewState | 受控视角，配合 onViewStateChange 使用 |
controller | 是否启用拖拽缩放旋转，可传对象配置限制 |
initialViewState.maxPitch | 俯仰角上限，一般设 60，防止翻到地平线以下 |
effects | 后处理效果数组，如光照、描边 |
parameters | WebGL 参数覆盖，深度测试、混合模式等 |
getTooltip | 悬停时的提示内容回调 |
useDevicePixels | 是否按设备像素比渲染，高分屏更清晰但更耗性能 |
常用方法
| 方法 | 说明 |
|---|---|
setProps(props) | 更新任意属性，包括 layers 和视角 |
getViewports() | 取当前视口，用于坐标换算 |
pickObject({x, y}) | 按屏幕坐标拾取要素 |
redraw() | 强制重绘 |
finalize() | 销毁 WebGL 资源 |
图层更新
deck.gl 不做逐图层 diff。每次 setProps({layers}) 传入新的数组，
它会按 id 匹配同名图层，数据引用没变就不重建。
所以给图层设稳定的 id 很重要，缺了会导致每帧重建、帧率暴跌。
deckgl.setProps({
layers: [
new deck.ScatterplotLayer({
id: 'points', // 稳定 id，避免重建
data: newData,
getPosition: function (d) { return [d.lng, d.lat]; },
getRadius: 2
})
]
});拾取
图层开 pickable: true 之后，getTooltip 或
onClick 里就能拿到 info.object，也就是原始数据对象。
不开 pickable 的话拿到的永远是 null。
离开页面记得 finalize。单页应用里反复创建 Deck 而不销毁，
会持续占用 WebGL 上下文，最终出现 Too many active WebGL contexts 警告，
表现为画面变黑。
经纬志（2026）。《Deck》。https://www.jingweizhi.com/deckgl/api/deck.html（访问日期 2026-11-03）。