首页 / OpenLayers / API 文档

Text

先看结论

文字样式。给要素加标注，控制内容、字体、位置、描边和背景，是矢量样式里参数最多的一项。

最后验证 2026-11-03 · OpenLayers 10.3.1 · 更新 2026-10-27 · 引用本文

new ol.style.Text(options)

构造参数

参数	默认	说明
`text`	—	文字内容，空字符串时不渲染
`font`	`'10px sans-serif'`	CSS 字体简写，含字号与字重
`fill`	—	文字颜色
`stroke`	—	文字描边，提升可读性
`offsetX` / `offsetY`	0	相对锚点的像素偏移，向下为正
`textAlign`	`'center'`	水平对齐：`left`、`right`、`center`
`textBaseline`	`'middle'`	垂直对齐：`top`、`bottom`、`middle` 等
`rotation`	0	文字旋转弧度
`scale`	1	缩放倍数
`overflow`	false	是否允许文字超出要素范围
`backgroundFill`	—	文字背景块填充
`backgroundStroke`	—	文字背景块描边
`padding`	—	背景块内边距 `[上, 右, 下, 左]`
`declutterMode`	`'declutter'`	避让模式

var label = new ol.style.Text({
  text: '王府井',
  font: '600 12px "PingFang SC", sans-serif',
  fill: new ol.style.Fill({ color: '#16181d' }),
  stroke: new ol.style.Stroke({ color: '#ffffff', width: 3 }),
  offsetY: -16,
  overflow: true
});

偏移与对齐

offsetY 为负值时文字向上移，正值向下。点标注一般用 -16 到 -20，线标注则用 textBaseline 控制压在线的上方还是下方。

textAlign 与 offsetX 配合可以做出 “左侧编号、右侧名称”这类排版：对齐改成 left 后，文字从锚点向右延伸，偏移量才是实际留白。

常用方法

方法	说明
`getText()` / `setText(t)`	读写内容
`getFont()` / `setFont(f)`	读写字体
`getOffsetX()` / `setOffsetX(v)`	读写水平偏移
`getOffsetY()` / `setOffsetY(v)`	读写垂直偏移
`getFill()` / `setFill(f)`	读写文字颜色
`getStroke()` / `setStroke(s)`	读写文字描边
`clone()`	复制文字样式

动态文字

文字内容通常来自要素属性，所以在样式函数里创建，或者克隆模板后只改内容：

var labelTemplate = new ol.style.Text({
  font: '500 12px sans-serif',
  fill: new ol.style.Fill({ color: '#16181d' }),
  stroke: new ol.style.Stroke({ color: '#ffffff', width: 3 }),
  offsetY: -15
});

function styleFunction(feature) {
  var text = labelTemplate.clone();
  text.setText(feature.get('name') + ' · ' + feature.get('code'));

  return new ol.style.Style({
    image: new ol.style.Circle({ radius: 5 }),
    text: text
  });
}

offsetY 是像素值，缩放地图时文字与点的距离在屏幕上看不变，但对应的地面距离会变。密集点位在缩小时标注会重叠，打开图层的 declutter: true 让渲染器自动隐藏重叠文字。

背景块

底图颜色复杂时，白色描边可能不够。给文字加背景块更彻底：

new ol.style.Text({
  text: '监测站 A',
  font: '12px sans-serif',
  fill: new ol.style.Fill({ color: '#ffffff' }),
  backgroundFill: new ol.style.Fill({ color: 'rgba(22,24,29,0.82)' }),
  backgroundStroke: new ol.style.Stroke({ color: '#1f5fd0', width: 1 }),
  padding: [3, 6, 3, 6]
});

padding 不设置时背景块紧贴文字边缘，可读性差。四个值按顺时针方向分别是上、右、下、左。

引用本文

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