首页 / OpenLayers / API 文档

LayerGroup

先看结论

图层组。把若干图层当成一个整体管理，一次切换显隐、统一设置透明度，也能嵌套成树状结构。

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

new ol.layer.Group(options)

构造参数

参数	说明
`layers`	图层数组或 `ol.Collection`，也可传返回它们的函数
`opacity`	组透明度，与子图层透明度相乘
`visible`	组显隐，false 时整组不渲染
`extent`	组的作用范围，超出范围不绘制
`zIndex`	组在地图中的叠放顺序
`minZoom` / `maxZoom`	组的可见缩放区间
`properties`	附加属性，便于业务侧挂载元数据

方法

方法	返回	说明
`getLayers()`	Collection	子图层集合，可直接 `push`、`remove`
`setLayers(layers)`	—	整体替换子图层
`getLayersArray()`	Array	展平后的全部图层，含嵌套组内部
`getLayerStatesArray()`	Array	各图层的渲染状态，含继承后的透明度与可见性
`getOpacity()` / `setOpacity(o)`	Number	组透明度
`getVisible()` / `setVisible(v)`	Boolean	组显隐

示例：底图组与专题组

var baseGroup = new ol.layer.Group({
  layers: [
    new ol.layer.Tile({ source: new ol.source.OSM() }),
    new ol.layer.Tile({
      source: new ol.source.XYZ({ url: '/tiles/labels/{z}/{x}/{y}.png' })
    })
  ],
  zIndex: 0
});

var themeGroup = new ol.layer.Group({
  layers: [
    new ol.layer.Vector({ source: roads, style: roadStyle }),
    new ol.layer.Vector({ source: pois, style: poiStyle })
  ],
  opacity: 0.9,
  zIndex: 10
});

var map = new ol.Map({
  target: 'map',
  layers: [baseGroup, themeGroup],
  view: new ol.View({ center: [12958190, 4825000], zoom: 8 })
});

// 整组关掉，不影响子图层各自的 visible 状态
themeGroup.setVisible(false);

// 组内追加图层
themeGroup.getLayers().push(new ol.layer.Vector({ source: districts }));

透明度与可见性的叠加规则

组的 opacity 会与每个子图层的 opacity 相乘，组的 visible 为 false 时子图层一律不绘制，但子图层自身的 visible 值保持不变。因此恢复组显隐后，之前单独隐藏的图层仍然隐藏。

与图层树面板的关系

用 ol.control.LayerSwitcher 之类的第三方控件时，组通常表现为可折叠节点。这些控件读取的就是 getLayersArray() 与 getLayerStatesArray()，所以组内再嵌套组也能正确显示层级。

组不改变绘制顺序。子图层仍按各自的 zIndex 与加入顺序排序，组的 zIndex 只决定整组相对于其他顶层图层的先后。期望「组内顺序整体沉底」时，要给组内每个图层单独设置层级。

引用本文

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