Class: VectorTileLayer

VectorTileLayer

new VectorTileLayer(options)

document/layer/baseLayer/VectorTileLayer.js, line 22

矢量瓦片图层。

该类封装矢量瓦片服务（MVT / Mapbox Style）加载、子图层组织（基于 mapinfo）以及样式图层增删改查能力， 是 IGSVectorTileLayer、ArcGISVectorTileLayer 等具体矢量瓦片图层的基础实现。

若需要自定义元信息加载逻辑，可通过重写 load() 实现（示例见下方），典型过程包括：初始化空间参考系、设置瓦片参数、设置图层范围和样式等。

Name Type Default Description
options Object {} 可选

构造参数

Name Type Default Description
url String '' 可选

服务基地址。
opacity Number 1 可选

图层透明度（0~1）。
minScale Number 0 可选

最小显示比例尺（最缩小）。
maxScale Number 0 可选

最大显示比例尺（最放大）。
tokenKey String 'token' 可选

Token 参数名。
tokenValue String | null null 可选

Token 值。仅当该值存在时才会在请求中附加 Token。
tileInfo TileInfo | Object 可选

瓦片切图信息配置。通常由服务端元信息决定，包含瓦片级别范围、行列号起止、原点和分辨率等，用于支撑按级别/行列号请求瓦片。
mvtExtent Number 4096 可选

MVT 矢量瓦片相对坐标范围。默认为 4096，表示矢量瓦片内部坐标从 0 到 4096。
currentStyleInfo Object {} 可选

当前矢量瓦片样式元信息，例如 serviceUrl、styleUrl、spriteUrl、glyphsUrl 以及内存中的 style 对象，便于调试或序列化。
sublayers Array.<(SubLayer|Object)> 可选

客户端预配置的子图层列表。若提供该参数，将与服务端 mapinfo 进行合并，用于过滤或覆盖子图层属性。
tileDisplayStrategy TileDisplayStrategy TileDisplayStrategy.stretch 可选

当图层显示比例尺超出瓦片数据级别范围后的显示策略，详见 TileDisplayStrategy。
elevationInfo ElevationInfo 可选

高程模式配置，仅在三维场景中生效；仅支持 ElevationMode.onTheScene 和 ElevationMode.onTheGround，默认值为 ElevationMode.onTheGround。
labelsRenderMode String 'off-screen' 可选

注记渲染模式（仅三维视图中有效）：

  • on-screen：使用 Cesium 接口实时渲染注记；
  • off-screen：在离屏 Canvas 中通过矢量瓦片绘制注记。

注意：三维注记目前不支持修改透明度和显隐参数；模式切换可能带来性能损耗。示例请参考 IGSVectorTileLayer。
clippingArea Polygon | Extent | Circle | MultiPolygon | null null 可选

图层空间裁剪范围，仅支持多多边形、多边形、矩形、圆形裁剪，用于在客户端按空间范围裁剪矢量瓦片。
Examples

自定义矢量瓦片业务逻辑-es5

// ES5引入方式
const { VectorTileLayer } = zondy.layer

// ES6引入方式
import { VectorTileLayer } from "@mapgis/webclient-common"
// 初始化矢量瓦片图层
const vectorTileLayerCustom = new VectorTileLayer({
  // 矢量瓦片基地址
  url: ''
});
// 例如通过重写vectorTileLayerCustom对象的load方法，来自定义矢量瓦片业务逻辑
vectorTileLayerCustom.load = (customStyle) => {
  // 你自己的业务逻辑，必须完成如下步骤
  // 1 初始化参考系
  // this.spatialReference = 参考系
  // 2 设置图层瓦片参数
  // this.tileInfo = 图层瓦片参数
  // 3 设置图层范围
  // this.extent = 图层范围
  // 4 设置矢量瓦片mvt样式
  // this.style = 矢量瓦片mvt样式
  // 5 如果有雪碧图参数，则要设置
  // this.style.sprite = 雪碧图参数
  // 6 必须返回一个Promise对象，并更新图层状态
  return new Promise((resolve) => {
    this.loadStatus = LoadStatus.loaded
    this.loaded = true
    resolve(this)
  })
}
// 在ES5模式下，如果更改了图层的业务逻辑，则必须通过图层的load方法来加载元信息，之后再添加图层
vectorTileLayerCustom.load().then(() => {
  // 添加图层
  map.add(vectorTileLayerCustom)
})

自定义矢量瓦片业务逻辑-es6

// ES6引入方式
import { VectorTileLayer } from "@mapgis/webclient-common"
// 在ES6模式下继承VectorTileLayer，并重写其业务逻辑
class VectorTileLayerCustom extends VectorTileLayer {
  constructor(options) {
    super(options)
  }
}
// 重写方法
VectorTileLayerCustom.prototype.load = (customStyle) => {
  // 你自己的业务逻辑，必须完成如下步骤
  // 1 初始化参考系
  // this.spatialReference = 参考系
  // 2 设置图层瓦片参数
  // this.tileInfo = 图层瓦片参数
  // 3 设置图层范围
  // this.extent = 图层范围
  // 4 设置矢量瓦片mvt样式
  // this.style = 矢量瓦片mvt样式
  // 5 如果有雪碧图参数，则要设置
  // this.style.sprite = 雪碧图参数
  // 6 必须返回一个Promise对象，并更新图层状态
  return new Promise((resolve) => {
    this.loadStatus = LoadStatus.loaded
    this.loaded = true
    resolve(this)
  })
}
const customLayer = new VectorTileLayerCustom({
  // 矢量瓦片基地址
  url: ''
})

Extends

Members

allSublayersCollectionFlattener.<SubLayer>

所有子图层的扁平化集合。

通过 CollectionFlattener 对 sublayers 做递归展开，便于按 id 查找和批量遍历。

autoAddTo2DBoolean

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

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

Default Value:
true

autoAddTo3DBoolean

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

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

Default Value:
true

capabilitiesObject

图层支持能力。

capabilities 通常由两部分组成：

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

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

clippingAreaPolygon Extent Circle MultiPolygon null

空间裁剪范围。

支持多多边形、多边形、矩形（Extent）、圆形等几何对象，用于在客户端按空间范围裁剪矢量瓦片显示范围。

版权所有

currentStyleInfoObject

当前矢量瓦片样式元信息。

通常包含以下字段：serviceUrl、styleUrl、spriteUrl、glyphsUrl 以及内存中的 style 对象， 便于在调试或序列化时恢复当前正在使用的 MVT 样式配置。

descriptionString

图层描述

elevationInfoElevationInfo

高程模式参数。矢量瓦片图层仅支持 ElevationMode.onTheScene 和 ElevationMode.onTheGround。

extendPropsObject

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

Default Value:
{}

extensionOptionsObject

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

Default Value:
{}

extentExtent null

图层的范围。从元信息或数据中获取，默认为null表示取不到范围。

forceRefreshDebounceDelayNumber

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

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

Default Value:
5

headersObject

设置服务请求头

httpMethodFetchMethod

http请求方式

idString

图层id

labelsRenderModeString

矢量瓦片注记渲染模式。

仅在三维视图中生效：

  • on-screen：使用 Cesium 接口实时渲染注记；
  • off-screen：通过矢量瓦片在离屏 Canvas 中绘制注记。

请注意：模式切换会带来一定性能开销，在显卡较弱的环境中可能触发卡顿。

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

mvtExtentNumber

MVT 矢量瓦片相对坐标范围。

默认为 4096，表示矢量瓦片内部坐标从 0 到 4096。该值通常与服务端发布时设置的 extent 保持一致。

Default Value:
4096

opacityNumber

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

spatialReferenceSpatialReference null

图层坐标系对象

styleObject null

矢量瓦片的mvt样式对象

sublayersCollection.<SubLayer> null

子图层列表对象。

子图层由服务端 mapinfo 与客户端配置合并生成；图层未加载完成时会暂存到 _clientSublayers。

tileDisplayStrategyTileDisplayStrategy

当视图比例尺超出瓦片数据自身级别范围时的显示策略。

由 TileDisplayStrategy 枚举定义，例如：

  • TileDisplayStrategy.hide：大于最大级别或小于最小级别时隐藏；
  • TileDisplayStrategy.stretch：大于最大级别时拉伸，小于最小级别时缩小。

tileInfoTileInfo null

瓦片切图信息。

该对象描述矢量瓦片的切片规则（级别范围、行列号范围、原点、分辨率等）， 通常由服务端元信息生成，也可以通过 options.tileInfo 传入自定义配置。

titleString

图层名称

tokenAttachTypeTokenAttachType

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

tokenKeyString

token名

Default Value:
token

tokenValueString

token值

typeLayerType

图层类型

urlString

矢量瓦片服务地址

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

clone(){VectorTileLayer}

document/layer/baseLayer/VectorTileLayer.js, line 981

克隆当前图层。

Returns:
Type Description
VectorTileLayer 克隆后的新实例

deleteStyleLayer(styleLayerId){void}

document/layer/baseLayer/VectorTileLayer.js, line 535
删除样式图层。

成功删除后会通过地图对象触发一次 layer-update 事件（LayerEventType#layerUpdate），用于通知视图刷新。

Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
void

inherited destroy(){void}

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

销毁图层。

基类不做具体释放逻辑，子类可根据需要重写（例如：释放请求、解绑引擎对象等）。

Returns:
Type Description
void

findSublayerById(sublayerID){SubLayer|null}

document/layer/baseLayer/VectorTileLayer.js, line 1030

根据子图层id查询图层

Name Type Description
sublayerID String

图层ID
Returns:
Type Description
SubLayer | null 子图层对象（未找到时返回 null）
Example

根据子图层id查询图层

// ES5引入方式
const { IGSVectorTileLayer } = zondy.layer

// ES6引入方式
import { IGSVectorTileLayer} from "@mapgis/webclient-common"
const igsVectorTileLayer = new IGSVectorTileLayer({
  // 服务基地址
  url: 'http://{ip}:{port}/igs/rest/services/{serviceName}/VectorTileServer'
});
map.add(igsVectorTileLayer);
// 根据id获取子图层
const subLayer = igsVectorTileLayer.findSublayerById('子图层id')

getExtendProperties(styleLayerId, key){Any}

document/layer/baseLayer/VectorTileLayer.js, line 714
获取样式图层的扩展属性（extendProperties）。
Name Type Description
styleLayerId String

样式图层 id
key String

扩展属性名
Returns:
Type Description
Any 扩展属性值；未找到时返回 null。

getLayoutProperties(styleLayerId){Object|null}

document/layer/baseLayer/VectorTileLayer.js, line 646
获取样式图层布局属性（layout）。

layout 属性通常用于控制图层的布局、可见性、符号摆放等。

Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
Object | null layout 对象；未找到时返回 null。

getPaintProperties(styleLayerId){Object|null}

document/layer/baseLayer/VectorTileLayer.js, line 602
获取样式图层绘制属性（paint）。

paint 属性通常用于控制颜色、透明度、线宽、填充等视觉渲染效果。

Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
Object | null paint 对象；未找到时返回 null。

inherited getProperty(path){*}

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

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

Name Type Description
path String

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

getStyleLayer(styleLayerId){Object|null}

document/layer/baseLayer/VectorTileLayer.js, line 433
通过矢量瓦片样式图层的 id 获取样式图层对象。

适用于对矢量瓦片样式进行精细化控制或调试，例如在调用 VectorTileLayer#setStyleLayer 前先获取当前图层样式。

注意：该方法依赖 VectorTileLayer#style 已存在且包含 layers 数组；通常需要先完成图层元信息/样式加载。

Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
Object | null 样式图层对象（Mapbox Style Layer），未找到时返回 null。

getStyleLayerId(index){Object|null}

document/layer/baseLayer/VectorTileLayer.js, line 471
通过矢量瓦片样式图层的序号获取样式图层对象。

注意：该方法依赖 VectorTileLayer#style 已存在。

Name Type Description
index Number

样式图层序号（从 0 开始）
Returns:
Type Description
Object | null 样式图层对象（包含 id 字段）；越界时返回 null。

getStyleLayerIndex(styleLayerId){Number}

document/layer/baseLayer/VectorTileLayer.js, line 455
通过矢量瓦片样式图层的 id 获取其在 `style.layers` 中的序号。

注意：该方法依赖 VectorTileLayer#style 已存在。

Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
Number 样式图层序号（从 0 开始）；未找到时返回 -1。

getStyleLayerVisibility(styleLayerId){Boolean}

document/layer/baseLayer/VectorTileLayer.js, line 586
获取样式图层可见性。
Name Type Description
styleLayerId String

样式图层 id
Returns:
Type Description
Boolean 是否可见。若未找到对应样式图层或 layout 不存在，默认返回 true。

inherited isLoaded(){Boolean}

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

判断图层是否加载成功

Returns:
Type Description
Boolean 图层是否加载成功

inherited load(){Promise.<Layer>}

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

图层资源加载。

默认实现会调用内部 _load()，并维护 loadStatus/loaded/loadError 等状态字段。 子类通常通过重写 _load() 来实现“请求元数据/初始化参数”的业务逻辑。

Returns:
Type Description
Promise.<Layer> 加载完成后的图层对象（resolve 为当前实例）

inherited refresh(){void}

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

刷新图层。

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

Returns:
Type Description
void

setExtendProperties(styleLayerId, key, value){void}

document/layer/baseLayer/VectorTileLayer.js, line 690
设置样式图层的扩展属性（extendProperties）。

该接口用于在样式图层对象上挂载业务自定义字段，例如三维注记控制参数等。

注意：该方法仅更新内存中的样式对象，不会触发图层更新事件。

Name Type Description
styleLayerId String

样式图层 id
key String

扩展属性名
value Any

扩展属性值
Returns:
Type Description
void

setLayoutProperties(styleLayerId, layout){void}

document/layer/baseLayer/VectorTileLayer.js, line 664
设置样式图层布局属性（layout）。

该方法会将 layout 合并到现有 layout 对象中，并触发一次 layer-update 事件（LayerEventType#layerUpdate）。

Name Type Description
styleLayerId String

样式图层 id
layout Object

layout 配置（会与原 layout 合并）
Returns:
Type Description
void

inherited setMap(map){void}

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

设置图层所属的地图/场景管理容器。

该方法通常由 Map 在添加图层时调用，外部一般无需手动调用。

Name Type Description
map *

地图/场景管理对象（不同引擎类型不同）
Returns:
Type Description
void

setPaintProperties(styleLayerId, paint){void}

document/layer/baseLayer/VectorTileLayer.js, line 620
设置样式图层绘制属性（paint）。

该方法会将 paint 合并到现有 paint 对象中，并触发一次 layer-update 事件（LayerEventType#layerUpdate）。

Name Type Description
styleLayerId String

样式图层 id
paint Object

paint 配置（会与原 paint 合并）
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 是否设置成功

setStyleLayer(styleLayer, index){void}

document/layer/baseLayer/VectorTileLayer.js, line 487
更新指定的样式图层对象。

该方法可用于：

  • 替换指定 id 的样式图层；
  • 通过传入 index 调整样式图层在 style.layers 中的顺序。

注意：布局属性和绘制属性的局部更新，推荐使用 VectorTileLayer#setLayoutProperties 和 VectorTileLayer#setPaintProperties。

成功更新后会通过地图对象触发一次 layer-update 事件（LayerEventType#layerUpdate），用于通知视图刷新。

Name Type Description
styleLayer Object

样式图层对象
index Number 可选

样式图层顺序（从 0 开始）。传入后会将图层移动到指定位置。
Returns:
Type Description
void

setStyleLayerVisibility(styleLayerId, visible){void}

document/layer/baseLayer/VectorTileLayer.js, line 566
设置样式图层可见性。

底层通过更新 layout.visibility 实现：visible → 'visible'，false → 'none'。

该方法会触发 layer-update 事件（LayerEventType#layerUpdate）。

Name Type Description
styleLayerId String

样式图层 id
visible Boolean

是否可见
Returns:
Type Description
void

toJSON(){Object}

document/layer/baseLayer/VectorTileLayer.js, line 960

导出为 JSON 配置。

Returns:
Type Description
Object JSON 配置对象

VectorTileLayer.fromJSON(json){VectorTileLayer}

document/layer/baseLayer/VectorTileLayer.js, line 942

通过传入的json构造并返回一个新的VectorTileLayer对象

注意：该方法会将 loadStatus/loaded 直接置为已加载状态， 适用于“已具备元信息”的场景（例如从持久化配置恢复）。

Name Type Description
json Object

JSON 对象
Returns:
Type Description
VectorTileLayer 新的 VectorTileLayer 实例