首页 / OpenLayers / API 文档

VectorImageLayer

先看结论

矢量栅格图层。先把矢量要素画到离屏画布，再把整块结果当图片贴到地图上，要素多时比逐个绘制更快。

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

new ol.layer.VectorImage(options)

构造参数

参数	说明
`source`	矢量数据源，通常是 `ol.source.Vector`
`style`	样式对象或样式函数，签名 `(feature, resolution)`
`imageRatio`	离屏画布相对视口的像素倍数，默认 1，调大提升清晰度
`renderBuffer`	渲染缓冲区像素，默认 100
`declutter`	是否在栅格化时避让标注，默认 false
`updateWhileAnimating`	动画期间是否重绘
`updateWhileInteracting`	拖动期间是否重绘
`opacity` / `visible` / `zIndex`	与其他图层一致

常用方法

方法	返回	说明
`getSource()` / `setSource(s)`	VectorSource / void	读写矢量数据源
`getStyle()` / `setStyle(style)`	Style / void	读写图层样式
`getFeatures(pixel)`	Array<Feature>	命中测试，返回像素附近的要素
`setOpacity(o)`	void	整层透明度
`changed()`	void	手动触发重绘

var layer = new ol.layer.VectorImage({
  source: new ol.source.Vector({
    url: '/data/roads.geojson',
    format: new ol.format.GeoJSON()
  }),
  style: new ol.style.Style({
    stroke: new ol.style.Stroke({ color: '#2a6fdb', width: 2 })
  }),
  imageRatio: 2,
  renderBuffer: 150,
  declutter: true
});

map.addLayer(layer);

// 样式变了要主动通知重绘
layer.setOpacity(0.8);
layer.changed();

注意事项

整层被栅格化，单个要素无法再单独高亮或做动态样式，交互高亮应另用普通矢量图层叠加。
imageRatio 增大会按倍数放大离屏画布，内存占用随平方增长，2 到 3 已能满足多数场景。
缩放跨越层级时会重新栅格化，过程中短暂使用上一次结果，快速连续缩放能看到轻微模糊。
要素数量少时收益不明显，逐个绘制的普通矢量图层反而更灵活。

引用本文

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