GLTFLayer

GLTFLayer是基于WebGL图形技术的GLTF三维模型绘制图层。

GLTFLayer仅支持添加GLTFMarker和MultiGLTFMarker，添加其他数据时会报错。

它是maptalks.OverlayLayer的子类，继承了 OverlayLayer 上所有的方法。

注：2026 源码中 GLTFLayer 的实际继承链为 GLTFLayer → MaskLayerMixin(AbstractGLTFLayer) → maptalks.OverlayLayer，构造函数签名支持 new GLTFLayer(id, geometries?, options?)，省略 geometries 时 options 可作为第二参数传入（2026 核对）

构造函数

import { GLTFLayer } from '@maptalks/gl-layers';

const layer = new GLTFLayer('gltf0');

详细信息

参数：

• id* String 图层id
• options* Object 配置参数，可选的配置项如下：

配置名	类型	描述	默认值
attribution	String	图层版权声明	null
minZoom	Number	图层显示的最小zoom	null
maxZoom	Number	图层显示的最大zoom	null
visible	Boolean	图层是否隐藏	true
opacity	Number	图层透明度	1
hitDetect	Boolean	是否开启图层绘制检测（动态鼠标样式），关闭可以提高性能	true
collisionScope	String	碰撞检测索引的适用范围： map或者layer	"layer"

GLTFLayer 特有的配置项（2026 源码补充）：

配置名	类型	描述	默认值
markerTypes	String[]	图层可接受的几何体类型	['gltfmarker', 'multigltfmarker']
pointSize	Number	点大小（像素）	1
renderer	String	渲染器类型	'gl'
doubleBuffer	Boolean	是否双缓冲渲染	false
glOptions	Object	GL上下文选项	null
markerEvents	Boolean	是否响应marker的鼠标事件	true
forceRenderOnZooming	Boolean	缩放时是否强制重绘	true
forceRenderOnMoving	Boolean	移动时是否强制重绘	true
forceRenderOnRotating	Boolean	旋转时是否强制重绘	true
style	Object	图层样式，结构为 [{filter, symbol}, ...] 数组，或 { $root, style: [{filter, symbol}, ...] }（$root 用于替换 symbol.url 中的 {$root}）	—

继承自OverlayLayer的方法

具体可以参考父类OverlayLayer的API文档。

getGeometryById(id)

用id获取Geometry。

参数：

• id Number | String Geometry的id

返回：

• Geometry

getGeometries(filter, context)

获取所有符合条件的Geometry。

参数：

• filter Function 过滤函数
• context Object fn函数运行时使用的this值

返回：

• Geometry[]

getFirstGeometry()

获取第一个Geometry。

返回：

• Geometry

getLastGeometry()

获取最后一个Geometry。

返回：

• Geometry

getCount()

获取Geometry数量。

返回：

• Number

getExtent()

获取图层上所有Geometry的地理范围。

返回：

• Extent

forEach(fn, context)

遍历Geometry并执行函数。

参数：

• fn Function 每个Geometry的操作函数 function(geometry) {}
• context Object fn函数运行时使用的this值

返回：

• this

isEmpty()

判断图层是否是空图层。

返回：

• Boolean

addGeometry(geometries, fitView)

向图层添加Geometry。

参数：

• geometries Geometry | Geometry[] Geometry或Geometry数组
• fitView Boolean

返回：

• this

removeGeometry(geometries)

从图层删除Geometry

参数：

• geometries Geometry | Geometry[]

返回：

• this

clear()

清空图层，删除所有Geometry。

返回：

• this

setStyle(style)

设置图层的样式，样式说明请参考该链接。

const style = [
  {
    filter : true,            // 数据的过滤条件
    symbol: {                 // 样式定义
      markerWidth: 6,
      markerHeight: 6,
      markerType: 'ellipse',
      markerFill: '#0f0'
    }
  }
];
layer.setStyle(style);

参数：

• style Object[] 图层样式对象，每个样式对象包含filter和symbol两个属性，filter是feature-filter类型的过滤条件，symbol是样式对象。

返回：

• this

getStyle()

获取图层样式。

返回：

• Object[]

removeStyle()

移除图层的样式。

返回：

• this

继承自Layer的方法

具体可以参考父类Layer的API文档。

getId()

获得图层id

返回：

• Number | String

setId(id)

设置图层id

返回：

• this

addTo(map)

添加到地图上。

返回：

• this

getMinZoom()

获取最小瓦片级别。

返回：

• Number

getMaxZoom()

获取最大瓦片级别。

返回：

• Number

getMap()

获取图层添加到的map对象。

返回：

• Map

getProjection()

获取图层的projection。

返回：

• Projection

show()

隐藏图层。

返回：

• this

hide()

隐藏图层。

返回：

• this

isVisible()

判定图层是否显示。

返回：

• Boolean

remove()

删除图层。

返回：

• this

on(events, handler, context)

注册图层的监听事件

返回：

• this

addEventListener(events, handler, context)

同 on 方法

返回：

• this

once(events, handler, context)

注册图层的监听事件，响应后即删除

返回：

• this

off(events, handler, context)

移除图层注册的监听事件

返回：

• this

removeEventListener(events, handler, context)

同 off 方法

返回：

• this

listens(events, handler, context)

判断图层是否监听了events事件。

返回：

• Boolean

fire(event, params)

手动发射一个事件，params是时间参数。

返回：

• this

setOptions(options)

设置图层配置。

返回：

• this

config(key, value)

更新某个图层配置。

返回：

• this

静态方法

fromJSON(json)

从图层的json对象创建一个GLTFLayer对象。

const json = layer.toJSON();

const layerCopied = maptalks.Layer.fromJSON(json);

返回：

• GLTFLayer

方法（2026 源码补充）

NOTE

以下 GLTFLayer 专属方法在 @maptalks/gl-layers 2026 源码中提供，旧版文档未收录：

方法	简化签名	说明
setURLModifier / getURLModifier	(fn) / ()	设置/获取模型 url 改写函数
identify	(coordinate, options?): Object[]	按坐标识别模型（内部转成容器点后走拾取）
identifyAtPoint	(point, options={}): Object[]	按容器点拾取模型；options.filter 过滤结果，includeInternals 返回内部数据
addGeometry	(geometries, fitView?)	添加几何体（支持 GeoJSON），逐个登记 pickingId
addMarker	(markers)	添加 marker 到内部 markerMap
setStyle / getStyle	(layerStyle) / ()	设置/获取图层 style（filter-symbol），setStyle 会触发 setstyle 事件
updateSymbol	(idx, symbolProperties)	更新 style 中第 idx 条 symbol，触发 updatesymbol 事件
getGLTFUrls	(): string[]	获取已加载的模型 url 列表
outlineBatch / outlineAll / cancelOutline	(filterIndex?) / () / ()	按 filter 索引批量描边 / 全部描边 / 取消描边
clear	()	清空所有几何体
toJSON	(options?)	导出图层 JSON
static registerShader / removeShader / getShaders	—	注册/移除/获取 shader（内置 phong、pbr、pbr-lite、depth、pointline、wireframe）

事件

图层事件监听示例代码：

// 监听workerready事件
layer.once('workerready', e => {
  // e为事件参数
  console.log('worker is ready');
});

// 监听tileload事件
layer.on('tileload', e => {
  // e为事件参数
  console.log('loaded a tile', e.tile);
});

图层事件

updatesymbol

更新Layer的style中序号为index的symbol的updatesymbol事件。

参数属性：

属性名	类型	值
type	String	"updatesymbol"
target	GLTFLayer	this
index	Number	样式序号
symbol	Object	symbol对象

setstyle

设置Layer的style后触发的事件（2026 源码补充）。

参数属性：

属性名	类型	值
type	String	"setstyle"
target	GLTFLayer	this
style	Object	设置后的图层样式（filter-symbol 数组或对象）

workerready

worker准备就绪事件。

参数属性：

属性名	类型	值
type	String	"workerready"
target	GLTFLayer	this

modelerror

模型加载错误事件。

参数属性：

属性名	类型	值
type	String	"modelerror"
target	GLTFLayer	this
url	String	加载出错的模型url
info	Object	错误信息

modelload

模型加载成功事件。

参数属性：

属性名	类型	值
type	String	"modelload"
target	GLTFLayer	this
models	String[]	成功加载的模型url

继承自OverlayLayer的事件

addgeo

添加Geometry事件

参数属性：

属性名	类型	值
type	String	"addgeo"
target	Layer	this
geometries	Geometry[]	添加的Geometry

removegeo

移除Geometry事件

参数属性：

属性名	类型	值
type	String	"removegeo"
target	Layer	this
geometries	Geometry[]	移除的Geometry

setstyle

调用图层setStyle设置图层样式后的事件

参数属性：

属性名	类型	值
type	String	"setstyle"
target	Layer	this
style	Object[]	样式数组

removestyle

调用图层removeStyle清除图层样式后的事件

参数属性：

属性名	类型	值
type	String	"removestyle"
target	Layer	this

继承自Layer的事件

clear

图层被清除事件。

参数属性：

属性名	类型	值
type	String	"clear"
target	VectorTileLayer	this

idchange

图层id变化事件。

参数属性：

属性名	类型	值
type	String	"idchange"
target	VectorTileLayer	this
old	String	旧的id
new	String	新的id

renderercreate

renderer创建事件

参数属性：

属性名	类型	值
type	String	"renderercreate"
target	VectorTileLayer	this
renderer	VectorTileLayerRenderer

canvascreate

canvas创建事件

参数属性：

属性名	类型	值
type	String	"canvascreate"
target	VectorTileLayer	this
gl	WebGLRenderingContext2D

renderstart

开始渲染事件。

参数属性：

属性名	类型	值
type	String	"renderstart"
target	VectorTileLayer	this

renderend

结束渲染事件。

参数属性：

属性名	类型	值
type	String	"renderend"
target	VectorTileLayer	this

事件核对（2026 源码）

• modelload：所有模型加载完成，参数为 { models: url 列表 }
• modelerror：模型加载出错，参数为 { url, info }
• setstyle：设置 style 后触发，参数 { style }
• updatesymbol：更新 symbol 后触发，参数 { index, symbol }
• load / add：marker 模型加载完成 / 添加时在 marker 上触发（含 layer 引用）

本文档已与 @maptalks/gl-layers 2026 源码核对（api-notes-others.md）