Class: GroupLayer

GroupLayer

new GroupLayer(options)

document/layer/GroupLayer.js, line 10

组图层，用于对多个业务图层进行统一管理和控制。

  • 支持对子图层进行批量添加、删除、顺序调整；
  • 可通过 visible、opacity 等属性统一影响所有子图层；
  • 可递归嵌套使用（组图层中仍可包含 GroupLayer）。
Name Type Default Description
options Object {} 可选

构造参数

Name Type Default Description
layers Array.<Layer> [] 可选

初始子图层数组。
visible Boolean true 可选

图层可见性。
opacity Number 1 可选

图层透明度，0 到 1 之间的数字。
id String 可选

图层 id，未提供时会自动生成随机 id。
title String '组图层' 可选

组图层名称。
Example

组图层示例

// 初始化图层管理容器
// ES5引入方式
const { IGSMapImageLayer,WMTSLayer,GroupLayer } = zondy.layer

// ES6引入方式
import { IGSMapImageLayer,WMTSLayer,GroupLayer} from "@mapgis/webclient-common"
// 创建一个矢量图层
const igsMapImageLayer = new IGSMapImageLayer({
  url: 'http://192.168.82.89:8089/igs/rest/services/Map/WorldJWVector/MapServer'
});
// 创建一个WMS图层
const wmsLayer = new WMTSLayer({
  url: 'http://192.168.82.89:8089/igs/rest/services/Tile/北京市/WMTSServer'
});
// 创建一个组图层
const groupLayer = new GroupLayer({
  // 添加子图层
  layers: [igsMapImageLayer, wmsLayer]
})

Extends

Members

allLayersCollection.<Layer>

扁平化后的子图层容器。

该集合会随 GroupLayer#layers 动态更新。 当子图层中包含嵌套的组图层时，会按照深度遍历顺序展开，便于一次性遍历所有节点。

autoAddTo2DBoolean

是否自动添加到二维引擎的地图对象。

该属性主要用于部分第三方引擎：图层的加载与添加由应用侧自行控制，而不是框架自动添加。

Default Value:
true

autoAddTo3DBoolean

是否自动添加到三维引擎的场景对象。

该属性主要用于部分第三方引擎：图层的加载与添加由应用侧自行控制，而不是框架自动添加。

Default Value:
true

capabilitiesObject

图层支持能力。

capabilities 通常由两部分组成：

  • client：客户端（渲染引擎）侧能力描述（如是否可加载、属性是否可读写等）
  • server：服务端能力描述（不同服务类型可扩展）

基类默认认为：所有引擎均支持加载该图层；服务端能力为空。

版权所有

descriptionString

图层描述

extendPropsObject

额外属性，当前图层对象上不支持的属性，二次开发用户希望挂在图层对像上的属性可以存储到该属性中

Default Value:
{}

extensionOptionsObject

初始化图层的额外参数，可以通过该参数传入引擎原生的构造参数

Default Value:
{}

extentExtent null

当前组图层的范围。

该属性会根据所有子图层的范围计算得到；当没有可用子图层范围时返回 null。

forceRefreshDebounceDelayNumber

强制刷新防抖延迟（毫秒）。

某些引擎实现会将刷新请求做合并/防抖处理，该参数用于控制防抖窗口。

Default Value:
5

headersObject

设置服务请求头

httpMethodFetchMethod

http请求方式

idString

图层id

layersCollection.<Layer>

子图层容器（第一层子节点）。

通过 GroupLayer#add / GroupLayer#addMany 添加的子图层会放入该容器。 当容器发生变化时，会在当前组图层及其父级链上依次触发 layerChange 事件。

loadErrorObject

请求失败后的错误信息，toJSON方法不会导出该属性

Default Value:
null

loadStatusString

图层加载状态

Default Value:
not-loaded

loadedBoolean

是否加载完毕

Default Value:
false

maxScaleNumber

最大显示比例尺，图层在视图中可见的最大比例尺(最放大)。如果地图被放大到超过这个比例，图层将不可见。默认值为0，如果图层是瓦片类型，maxScale、minScale的默认值能和tileInfo上的保持一致，如果图层是动态图层，则和地图视图保持一致。maxScale应该始终小于minScale。

Default Value:
0

minScaleNumber

最小显示比例尺，图层在视图中可见的最小比例尺(最缩小)。如果地图被缩小到超过这个比例，图层将不可见。默认值为0，如果图层是瓦片类型，maxScale、minScale的默认值能和tileInfo上的保持一致，如果图层是动态图层，则和地图视图保持一致。minScale应该始终大于maxScale。

Default Value:
0

opacityNumber

图层透明度，0到1之间的值，0为完全透明，1为不透明，会触发图层更新完毕事件。IGSSceneLayer图层类型为地形时，不支持该属性。

spatialReferenceSpatialReference null

图层坐标系对象

titleString

图层名称

tokenAttachTypeTokenAttachType

token附加类型。默认 post 请求优先附加到 body，get 请求优先附加到 url 末尾。

tokenKeyString

token名

Default Value:
token

tokenValueString

token值

typeLayerType

图层类型

visibleBoolean

图层显示或隐藏，true则显示，false则隐藏，会触发图层更新完毕事件

Events

inherited layer-update

document/layer/baseLayer/Layer.js, line 126

图层属性更新事件。

当调用 refresh()、setProperty() 或图层内部主动触发更新时，会向 Map/View 分发该事件。 该事件主要用于渲染层同步图层状态。

Properties:
Name Type Description
event LayerViewUpdateEvent

事件对象

Properties
Name Type Default Description
type String 'layer-update' 可选

事件类型
layer Layer 可选

图层对象
updateContent Array.<Object> 可选

更新详情
Example

Create Layer instance

// ES5 import style
const { Layer } = zondy

// ES6 import style
import { Layer } from '@mapgis/webclient-common'

inherited layerview-created

document/layer/baseLayer/Layer.js, line 52

图层在视图中创建完毕事件。

当图层被添加到 View，并且该引擎对应的图层视图对象创建成功后触发。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layerview-created' 可选

事件类型
message String null 可选

描述信息
layer Layer null 可选

图层对象
layerView * null 可选

图层视图对象（不同引擎类型不同）
sourceTarget * null 可选

事件发起对象
target * null 可选

事件接收对象（通常为 View/Map）
Example
layer.on('layerview-created', (event) => {
  console.log('图层视图创建完毕', event.layer, event.layerView)
})

inherited layerview-remove

document/layer/baseLayer/Layer.js, line 71

图层从视图中移除事件。

当图层从 View 移除，并且对应的图层视图对象已释放后触发。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layerview-remove' 可选

事件类型
message String null 可选

描述信息
layer Layer null 可选

图层对象
layerView * null 可选

图层视图对象
sourceTarget * null 可选

事件发起对象
target * null 可选

事件接收对象（通常为 View/Map）
Example
layer.on('layerview-remove', (event) => {
  console.log('图层视图已移除', event.layer)
})

inherited layerview-scale-visible

document/layer/baseLayer/Layer.js, line 109

图层比例尺显示/隐藏状态更新事件。

该事件由 View 层在比例尺变化导致图层显示状态（因 minScale/maxScale 约束）变化时触发。 当前仅支持非组图层以及场景子图层。

Properties:
Name Type Description
event Object

事件对象

Properties
Name Type Default Description
type String 'layerview-scale-visible' 可选

事件类型
target * 可选

事件接收对象
sourceTarget * 可选

事件发起对象
Example
layer.on('layerview-scale-visible', (event) => {
  console.log('比例尺可见性变更', event)
})

inherited layerview-update

document/layer/baseLayer/Layer.js, line 90

图层视图更新事件。

该事件通常由 View 层触发，用于通知外部“渲染层已完成一次图层更新”。 event.updateContent 中会描述本次更新涉及的属性或方法（例如：visible、opacity、refresh）。

Properties:
Name Type Description
event LayerViewUpdateEvent

事件对象

Properties
Name Type Description
updateContent Array.<Object> 可选

更新详情数组
Example
layer.on('layerview-update', (event) => {
  const updateContent = event.updateContent || []
  const hasVisibleChange = updateContent.some((c) => c.name === 'visible')
  const hasOpacityChange = updateContent.some((c) => c.name === 'opacity')
  const hasRefresh = updateContent.some((c) => c.name === 'refresh')
  console.log('更新完毕', { hasVisibleChange, hasOpacityChange, hasRefresh })
})

Methods

add(layer, index){void}

document/layer/GroupLayer.js, line 188

向组图层中添加一个子图层。

添加前会校验图层 id 是否重复，并同步建立子图层与当前组图层、地图对象之间的父子关系。 添加成功后会触发图层添加相关事件。

Name Type Description
layer Layer

要添加的子图层。
index Number 可选

子图层插入位置；未传入时追加到末尾。
Returns:
Type Description
void

addMany(layers, index){void}

document/layer/GroupLayer.js, line 212

批量添加多个子图层。

连续添加多个图层时推荐优先使用该接口，可统一完成合法性校验、父子关系绑定和变更事件触发。

Name Type Description
layers Array.<Layer>

要添加的子图层数组。
index Number 可选

子图层插入起始位置；未传入时追加到末尾。
Returns:
Type Description
void

clone(){GroupLayer}

document/layer/GroupLayer.js, line 342

克隆当前组图层。

会基于当前实例及其子图层的序列化结果创建新的组图层实例。

Returns:
Type Description
GroupLayer 克隆后的组图层实例。

destroy(){void}

document/layer/GroupLayer.js, line 382

销毁当前组图层。

调用后会清空子图层、移除内部监听，并执行基类销毁逻辑。

Returns:
Type Description
void

findLayerById(layerId){Layer|null}

document/layer/GroupLayer.js, line 314

根据图层 id 查找直接子图层。

仅在当前 layers 容器的第一层子节点中查找，不会递归搜索嵌套组图层内部的子图层。

Name Type Description
layerId String

子图层 id。
Returns:
Type Description
Layer | null 匹配到的子图层；未找到时返回 null。

getFlatLayers(){Array.<Layer>}

document/layer/GroupLayer.js, line 302

获取组图层扁平化后的全部子图层。

返回结果会按照深度遍历顺序展开多层嵌套组图层，便于统一遍历所有子节点。

Returns:
Type Description
Array.<Layer> 组图层中展开后的全部子图层数组。

inherited getProperty(path){*}

document/layer/baseLayer/Layer.js, line 825

获取属性或属性路径对应的值。

Name Type Description
path String

属性路径
Returns:
Type Description
* 属性值

isLoaded(){Boolean}

document/layer/GroupLayer.js, line 176

判断当前组图层是否已完成加载。

仅当当前组图层自身状态为已加载，且全部子图层也都处于已加载状态时返回 true。

Returns:
Type Description
Boolean 是否已完成当前组图层及全部子图层的加载。

load(){Promise.<GroupLayer>}

document/layer/GroupLayer.js, line 134

加载组图层及其尚未加载的子图层。

会依次调用当前组图层中未加载子图层的 load 方法，全部子图层处理完成后再将当前组图层状态标记为已加载。 子图层加载成功或失败时会分别转发对应图层事件。

Returns:
Type Description
Promise.<GroupLayer> Promise 对象，resolve 时返回当前组图层实例。

inherited refresh(){void}

document/layer/baseLayer/Layer.js, line 743

刷新图层。

该方法会触发 layer-update 事件（若图层已添加到地图且已加载），用于通知渲染层重新拉取/绘制。

Returns:
Type Description
void

remove(layer){void}

document/layer/GroupLayer.js, line 235

从组图层中移除一个子图层。

移除后会清理子图层与当前组图层、地图对象的关联关系，并触发图层移除事件。

Name Type Description
layer Layer

要移除的子图层。
Returns:
Type Description
void

removeAll(){void}

document/layer/GroupLayer.js, line 268

移除当前组图层中的全部子图层。

调用后 layers 容器会被清空，并为原有子图层批量清理父子关系与地图关联。

Returns:
Type Description
void

removeMany(layers){void}

document/layer/GroupLayer.js, line 252

批量移除多个子图层。

适用于一次性清理多张子图层，会同步清理父子关系并触发图层移除事件。

Name Type Description
layers Array.<Layer>

要移除的子图层数组。
Returns:
Type Description
void

reorder(layer, index){void}

document/layer/GroupLayer.js, line 284

调整子图层在当前组图层中的顺序。

调整完成后会触发图层顺序变更事件，适用于控制子图层在视图中的绘制前后关系。

Name Type Description
layer Layer

要移动的子图层。
index Number

目标位置索引。
Returns:
Type Description
void
Example

调整子图层顺序

groupLayer.reorder(layer, 1)

setMap(map){void}

document/layer/GroupLayer.js, line 368

设置当前组图层关联的地图对象。

除了更新当前图层自身状态外，还会同步将地图对象传递给全部直接子图层。

Name Type Description
map *

地图对象。
Returns:
Type Description
void

inherited setProperty(path, value){Boolean}

document/layer/baseLayer/Layer.js, line 777

设置属性值或属性路径对应的值。

由于默认仅支持第一级属性响应，此方法提供“属性路径”写入能力。 例如：setProperty('tileInfo.startLevel', 3) 可更新 tileInfo.startLevel。

若设置的是多级属性路径，会额外触发一次 layer-update 事件（updateContent.name 为路径字符串）。

Name Type Description
path String

属性路径，可以传入单个属性后者一个属性的路径
value *
Returns:
Type Description
Boolean 是否设置成功

toJSON(){Object}

document/layer/GroupLayer.js, line 328

导出为 JSON 配置。

会递归导出当前组图层及其子图层配置，适用于持久化图层树结构。

Returns:
Type Description
Object 包含当前组图层及其子图层信息的 JSON 配置对象。

GroupLayer.fromJSON(json){GroupLayer}

document/layer/GroupLayer.js, line 354

通过 JSON 配置创建一个组图层实例。

适用于从持久化配置恢复组图层及其子图层结构，通常与 toJSON 配套使用。

Name Type Default Description
json Object {} 可选

图层配置对象。
Returns:
Type Description
GroupLayer 新的组图层实例。