首页 / deck.gl / API 文档

IconLayer

先看结论

把图标贴到坐标上。所有图标来自同一张图集，一次绘制完成上万次调用。

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

new deck.IconLayer(props)

核心参数

参数	默认	说明
`data`	`[]`	图标点位
`getPosition`	—	返回 `[经度, 纬度]`
`iconAtlas`	—	图集图片地址，可用 data URL 或 canvas
`iconMapping`	`{}`	图标名到图集区域的映射
`getIcon`	—	返回 `iconMapping` 中的键名
`getSize`	`1`	图标尺寸，单位由 `sizeUnits` 决定
`sizeUnits`	`'pixels'`	`'pixels'`、`'meters'` 或 `'common'`
`sizeScale`	`1`	统一倍率
`sizeMinPixels` / `sizeMaxPixels`	`0` / 无	像素上下限
`getColor`	`[0, 0, 0, 255]`	与图标像素相乘，白色图标可任意染色
`billboard`	`false`	始终正对相机
`alphaCutoff`	`0.05`	低于该 alpha 的像素丢弃，边缘更干净
`pickable`	`false`	是否参与拾取

iconMapping 的结构

每个图标描述图集中的一个矩形，加上锚点偏移：

var mapping = {
  office:   { x: 0,   y: 0, width: 64, height: 64, anchorY: 64 },
  station:  { x: 64,  y: 0, width: 64, height: 64, anchorY: 64 },
  school:   { x: 128, y: 0, width: 64, height: 64, anchorY: 64 }
};

字段	含义
`x` / `y`	图标左上角在图集中的像素坐标
`width` / `height`	图标在图集中的像素尺寸
`anchorX` / `anchorY`	锚点相对图标左上角的位置，默认居中
`mask`	只使用 alpha 通道着色，适合纯色剪影

水滴形标记要把锚点放在尖角处，也就是 anchorY: height，否则地图缩放时图标会「浮」在坐标点上方。

示例

var layer = new deck.IconLayer({
  id: 'poi',
  data: pois,
  iconAtlas: '/img/poi-atlas.png',
  iconMapping: mapping,
  getIcon: function (d) { return d.type; },
  getPosition: function (d) { return [d.lng, d.lat]; },
  getSize: function (d) { return d.weight + 12; },
  sizeUnits: 'pixels',
  sizeMinPixels: 12,
  sizeMaxPixels: 42,
  getColor: function (d) { return d.color; },
  billboard: true,
  pickable: true
});

图集怎么来

图集是普通的 PNG 或 canvas，约定每个图标等宽等高，按行排列。没有现成资源时，可以用 canvas 现场绘制、导出 data URL，这样单文件示例也能运行：

var cv = document.createElement('canvas');
cv.width = 192;
cv.height = 64;
var ctx = cv.getContext('2d');
/* 在 0–64、64–128、128–192 三个槽位绘制白色图形 */
var atlas = cv.toDataURL('image/png');

让图标以白色绘制，配合 getColor 就能得到任意颜色，不必为每种配色准备一套图。

尺寸单位

'pixels' 保持视觉大小恒定，适合界面标记； 'meters' 让图标随地图缩放，适合表达实际占地； 'common' 以图标原始像素为基准，配合 sizeScale 做整体缩放，避免了不同图集尺寸不一致的问题。

图标数量过多时改用符号图层。几万个图标每个都是一次贴图绘制，在低端设备上容易掉帧。数量大时用 ScatterplotLayer 配合形状区分，或先聚合再显示。

引用本文

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