首页 / deck.gl / API 文档

GridLayer

先看结论

把空间切成等边长的方格，统计每格内的数据，用颜色和高度表达统计值。方格与经纬网对齐，便于和行政区划、遥感格网对照。

最后验证 2026-11-03 · deck.gl 9.0 · 更新 2026-10-27 · 引用本文

new deck.GridLayer(props)

核心参数

参数	默认	说明
`data`	`[]`	参与聚合的点数据
`getPosition`	—	返回 `[经度, 纬度]`
`cellSize`	`1000`	方格边长，米
`coverage`	`1`	格子实际绘制占比，0.8 会留出间隙
`extruded`	`false`	是否拉成柱体
`elevationScale`	`1`	高度倍率
`getColorWeight`	`1`	决定颜色的权重
`colorAggregation`	`'SUM'`	`'SUM'`、`'MEAN'`、`'MIN'`、`'MAX'`
`getElevationWeight`	`1`	决定高度的权重，可与颜色不同
`elevationAggregation`	`'SUM'`	同上，作用于高度
`colorRange`	内置	色带，至少两档
`colorDomain`	自动	固定值域，避免切换数据时色标跳动
`elevationRange`	自动	固定高度值域
`upperPercentile`	`100`	高于该百分位的格子不绘制，密集区会出现空洞
`gpuAggregation`	`true`	GPU 聚合，数据量小时可关掉以节省初始化
`pickable`	`false`	开启后可取到格子统计值

示例

var layer = new deck.GridLayer({
  id: 'grid',
  data: points,
  getPosition: function (d) { return [d.lng, d.lat]; },
  cellSize: 800,
  coverage: 0.86,
  extruded: true,
  elevationScale: 0.6,
  getColorWeight: function (d) { return d.flow; },
  colorAggregation: 'MEAN',
  getElevationWeight: function (d) { return 1; },
  elevationAggregation: 'SUM',
  colorRange: [
    [20, 40, 90, 180],
    [30, 110, 170, 200],
    [120, 200, 180, 220],
    [250, 210, 90, 235],
    [235, 90, 60, 245]
  ],
  upperPercentile: 100,
  pickable: true
});

聚合方式的选择

方式	表达	适用
`SUM`	总量	订单数、客流、排放总量
`MEAN`	平均水平	均价、浓度、评分，避免大小区不可比
`MIN` / `MAX`	极值	找短板、找峰值

颜色和高度可以用两套权重：例如颜色取平均车速，高度取车流总量。两者独立配置，比强行用同一个值表达两件事更清楚。

百分位参数要慎用。upperPercentile: 98 会把数值最高的 2% 格子整个去掉，而不是把它们压到色带上限，密集区域的中心因此会变成一片空白。需要压缩极值时，优先固定 colorDomain 与 elevationRange。

拾取

开启 pickable 后，info.object 包含 position（格子中心）、count（落入的点数）、 colorValue 与 elevationValue。提示里直接给出这三个值，就能替代图例。

getTooltip: function (info) {
  if (!info.object) return null;
  var o = info.object;
  return '格内 ' + o.count + ' 点，均值 ' + o.colorValue.toFixed(1);
}

网格与视角

cellSize 以米计，屏幕上的格子大小随缩放变化。缩放层级跨度大时，同一套参数在低层级看不见、高层级过密。常见做法是随缩放调整网格粒度：层级低于 9 用 2000 米，高于 13 用 500 米，通过 setProps 重建图层。

方格聚合的边界是固定的。同一批数据换一个投影或平移原点，格子划分位置会变，统计值随之变化。需要结果可复现时，固定 colorDomain 与初始视角，避免缩放级别改变分箱基准。

引用本文

经纬志（2026）。《GridLayer》。https://www.jingweizhi.com/deckgl/api/grid-layer.html（访问日期 2026-11-03）。