首页 / deck.gl / API 文档

TextLayer

先看结论

把文字作为纹理绘制在坐标上。它本身是复合图层，内部由 IconLayer 渲染。

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

new deck.TextLayer(props)

核心参数

参数	默认	说明
`data`	`[]`	文字点位
`getText`	—	返回要显示的文字
`getPosition`	—	返回 `[经度, 纬度]`
`getSize`	`32`	字号，单位由 `sizeUnits` 决定
`sizeUnits`	`'pixels'`	`'pixels'` 或 `'meters'`
`getColor`	`[0, 0, 0, 255]`	文字颜色
`getAngle`	`0`	旋转角，度
`getTextAnchor`	`'middle'`	`'start'`、`'middle'`、`'end'`
`getAlignmentBaseline`	`'middle'`	`'top'`、`'center'`、`'bottom'`
`getPixelOffset`	`[0, 0]`	像素偏移，避免文字压住图标
`billboard`	`true`	文字始终面向相机
`characterSet`	ASCII	参与图集生成的字符集合
`fontFamily`	等宽字体	字体族名称，由浏览器栅格化
`fontSettings`	内置	`fontSize`、`buffer`、`sdf`、`radius`
`background`	`false`	是否绘制背景框
`getBackgroundColor`	`[255, 255, 255, 255]`	背景色
`backgroundPadding`	`[0, 0]`	背景内边距，`[水平, 垂直]`
`outlineWidth`	`0`	描边宽度，相对字号；需开启 SDF
`outlineColor`	`[0, 0, 0, 255]`	描边颜色
`pickable`	`false`	是否参与拾取

图集是怎么生成的

TextLayer 在初始化时把 characterSet 里的每个字符离屏绘制到一张纹理上，再交给 IconLayer 按字形切片贴图。所以渲染前必须先知道「会用到哪些字符」。默认只包含 ASCII，出现未收录字符时该字符直接不显示，不会报错。

new deck.TextLayer({
  id: 'labels',
  data: cities,
  getText: function (d) { return d.name + ' ' + d.value; },
  getPosition: function (d) { return [d.lng, d.lat]; },
  getSize: function (d) { return 12 + d.value / 20; },
  sizeUnits: 'pixels',
  getColor: [235, 242, 255, 255],
  characterSet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 .-/',
  background: true,
  getBackgroundColor: [12, 20, 34, 200],
  backgroundPadding: [4, 2],
  fontSettings: { sdf: true, fontSize: 64, buffer: 4, radius: 8 },
  outlineWidth: 0.08,
  outlineColor: [0, 0, 0, 180],
  getTextAnchor: 'middle',
  getAlignmentBaseline: 'center'
});

中文与字形覆盖

中文字形数量大，图集体积随字符数增长。做法有两种：把 fontFamily 指向系统字体并显式给出 characterSet（只包含实际要用的字），或改用 TextLayer 之外的方案，例如把文字栅格化成图标再交给 IconLayer。

图集尺寸存在上限，字符集过大时会超过设备的纹理边长限制，表现为部分文字变成空白方块。控制字符数在几百以内比较稳。

SDF 与描边

fontSettings.sdf: true 让字形以距离场形式存储，放大后边缘依然锐利，描边和光晕也依赖它。代价是图集需要预留更多留白，buffer 值要相应增大。

设置	效果
`sdf: false`	图集更小，放大会模糊
`sdf: true` + `outlineWidth`	边缘锐利，可加描边
`fontSize: 64`	字形栅格化基准，越大越精细
`buffer: 4`	字间留白，太小会与相邻字形粘连

锚点与偏移

标签常与图标成对出现。图标用 anchorY 对齐坐标，文字则通过 getPixelOffset 上移 12–18 像素，避免压在图形上。倾斜视角下，billboard: true 让文字保持直立，可读性明显好于贴地文字。

标签数量不等于可读性。几千个标签同时显示会互相遮挡。按数值取前若干名显示，或在缩放到一定层级后再挂载 TextLayer，比调小字号更有效。

引用本文

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