首页 / OpenLayers / API 文档

VectorTileLayer

先看结论

矢量瓦片图层。每个瓦片携带二进制编码的要素，客户端解析后按当前缩放级别重新着色，因此同一份数据在不同层级可以呈现完全不同的信息密度。

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

new ol.layer.VectorTile(options)

构造参数

参数	默认	说明
`source`	—	`ol.source.VectorTile` 实例
`style`	—	样式对象或 `(feature, resolution)` 函数
`renderMode`	'hybrid'	`'vector'` 逐个要素绘制 / `'image'` 整块瓦片绘制 / `'hybrid'` 自动选择
`declutter`	false	自动避让标注，依赖样式里声明了文字或图标
`preload`	0	预加载相邻瓦片的层级数
`useInterimTilesOnError`	true	瓦片加载失败时用上一级的临时瓦片顶替
`opacity` / `visible` / `zIndex`	—	与其他图层一致

常用方法

方法	说明
`getSource()` / `setSource(source)`	读写瓦片数据源
`getStyle()` / `setStyle(style)`	读写样式
`getFeatures(pixel)`	拾取像素位置下的要素集合，返回 `Promise`
`getFeaturesInExtent(extent)`	按地图坐标范围取要素，返回 `Promise`
`setOpacity(o)` / `setVisible(v)`	透明度与显隐
`changed()`	手动触发重绘

示例

var layer = new ol.layer.VectorTile({
  source: new ol.source.VectorTile({
    format: new ol.format.MVT(),
    url: 'https://tiles.example.com/data/{z}/{x}/{y}.pbf'
  }),
  renderMode: 'hybrid',
  declutter: true,
  style: function (feature, resolution) {
    var kind = feature.get('kind');
    return new ol.style.Style({
      stroke: new ol.style.Stroke({
        color: kind === 'river' ? '#2b7fd4' : '#9aa6b2',
        width: resolution < 10 ? 2 : 1
      }),
      text: new ol.style.Text({
        text: feature.get('name') || '',
        font: '12px sans-serif'
      })
    });
  }
});

renderMode 的选择

'vector' 保留每个要素的独立几何，样式函数可以按属性区分，但要素多时绘制调用上升。 'image' 把整块瓦片栅格化后贴到地图上，速度最快，代价是要素无法单独拾取，样式也只在瓦片生成时计算一次，缩放时文字大小不会重新调整。

默认的 'hybrid' 在缩放过程中用图像模式保证流畅，停下后切回矢量模式，兼顾交互与画质。

拾取是异步的

getFeatures(pixel) 返回 Promise，因为瓦片可能尚未加载完成。正确写法是先 forEachFeatureAtPixel 拿到渲染器里的要素，或等待 Promise 后再读属性：

map.on('singleclick', function (event) {
  layer.getFeatures(event.pixel).then(function (features) {
    if (!features.length) {
      return;
    }
    var feature = features[0];
    console.log(feature.get('name'), feature.getProperties());
  });
});

矢量瓦片按层级裁剪。低层级瓦片里的要素几何已经被简化，用它们算面积、长度会明显偏小。量算类功能要回到原始数据，或者只在最大层级取值。

引用本文

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