GeoJSONVectorTileLayer

GeoJSONVectorTileLayer 是用于在地图上绘制渲染GeoJSON数据的矢量瓦片图层。

该图层基于 geojson-vt 开源库，在worker中对GeoJSON数据实时切片后返回给主线程渲染绘制。

采用矢量瓦片机制加载GeoJSON数据的优点：

性能高，轻松支持上百M GeoJSON文件的解析与渲染
体验好，数据处理都在worker中进行，不会造成主线程的卡顿

它是 VectorTileLayer的子类，同样继承了VectorTileLayer上的方法和配置。

同样的，VectorTileLayer上的样式也无需修改应用到GeoJSONVectorTileLayer上，实现服务端矢量瓦片数据和本地GeoJSON数据的统一化。

NOTE

参数或配置名称上带 * 表示该参数或配置不能为空，例如下面id后的*号表示参数id是不能为空的：

id* String 图层id

样式

矢量瓦片即支持矢量（点线面）的样式，也有把线和面构造为三维线和三维面后，用三维pbr材质渲染的能力。

矢量瓦片整合了feature-filter和function-type来支持数据过滤和动态样式，能方便的把矢量瓦片中的数据分门别类用不同样式和不同级别结合材质魔法渲染出惊人的效果。

因此矢量瓦片很适合大场景下的数据分类渲染，如城市建筑群。比起3dtiles等静态数据，矢量瓦片因为生态更好，样式和数据分离的特点，能在消除数据更新成本的同时，提供3dtiles很难达到的样式设计能力。

矢量瓦片的样式采用了插件式设计，样式由一个个渲染插件来定义的，渲染插件的详细信息可以参考样式手册，以下是一个样式的简单示例：

样式示例

json

{
  "style": [
    {
      "renderPlugin": {
        "type": "fill",
        "dataConfig": {
          "type": "fill",
          "only2D": true
        },
        "sceneConfig": {
          "depthFunc": "always",
          "blendSrc": "one"
        }
      },
      "symbol": {
        "visible": true,
        "polygonFill": "rgba(0,0,0,1)",
        "polygonOpacity": 1
      },
      "filter": {
        "title": "desert",
        "value": [
          "all",
          [
            "==",
            "$layer",
            "desert"
          ],
          [
            "==",
            "$type",
            "Polygon"
          ]
        ]
      }
    },
    {
      "renderPlugin": {
        "type": "line",
        "dataConfig": {
          "type": "line",
          "only2D": true
        },
        "sceneConfig": {
          "blendSrc": "one"
        }
      },
      "symbol": {
        "visible": true,
        "lineOpacity": 1,
        "lineWidth": 1,
        "lineColor": "rgba(0,0,0,1)",
        "lineJoin": "miter",
        "lineCap": "butt",
        "lineDx": 0,
        "lineDy": 0,
        "lineDasharray": [
          0,
          0,
          0,
          0
        ],
        "lineDashColor": "rgba(0,0,0,1)",
        "lineStrokeWidth": 0,
        "lineStrokeColor": "rgba(0,0,0,1)"
      },
      "detail": {
        "layer": "desert-outline",
        "enable": {
          "lineWidth": false,
          "lineColor": false,
          "lineStrokeWidth": false,
          "lineStrokeColor": false
        }
      },
      "filter": {
        "title": "desert-outline",
        "value": [
          "all",
          [
            "==",
            "$layer",
            "desert"
          ],
          [
            "==",
            "$type",
            "Polygon"
          ]
        ]
      }
    }
  ]
}

构造函数

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

new GeoJSONVectorTileLayer('geojson0', {
  data: 'path/to/example.geojson'
});

详细信息

参数：

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

配置名	类型	描述	默认值
data*	Object/String	GeoJSON数据对象或者url	null
features	Boolean	瓦片是否返回feature数据，对GeoJSON图层只返回要素id	true
tileBuffer	Number	瓦片缓冲大小	64
extent	Number	瓦片坐标范围（extent，即几何编码精度）	8192
simplifyTolerance	Number	瓦片简化容差（越大越简化）	3
generateOMBB	Boolean	是否生成最小外接矩形（OMBB，加速拾取）	true
convertFn	String	数据转换函数字符串（在worker中执行convert(data)）	null
fetchOptions	Object	fetch参数	null
style	Object	图层样式对象	null
subdomains	String[]	subdomains, 用于替换url模板中的	null
tileSize	Number[]	瓦片高宽，单位像素	[512, 512]
offset	Number[]/Function	瓦片的偏移量，单位像素，二维数组或函数，函数的参数为 zoom，瓦片的zoom级别，offset(zoom) {}	[0, 0]
features	Boolean	瓦片是否返回feature数据	true
schema	Boolean	瓦片是否返回数据的属性schema	false
collision	Boolean	是否开启点和文字的碰撞检测	true
picking	Boolean	是否允许图层用identify或identifyAtPoint方法查询数据	true
pickingPoint	Boolean	identify或identifyAtPoint方法的查询结果是否返回查询点的三维空间坐标	true
pickingGeometry	Boolean	identify或identifyAtPoint方法的查询结果是否包含Geometry	false
iconErrorUrl	String	icon请求失败后的替换图片url	null
collisionFrameLimit	Number	每帧用于计算Collision的时间限制，单位ms	1.5
defaultRendering	Boolean	是否开启没有style时的默认样式绘制	true
textGamma	Number	文字的Gamma值，可以用于调整文字清晰度	1
maxIconSize	Number	图标最大尺寸限制	254
styleScale	Number	图层图标和文字的整体放大系数	1
spatialReference	String / Object	图层的空间参考	"preset-vt-3857"
tileSystem	Number[]	一个四位数数组，用于描述 TileSystem，TileSystem用于定义瓦片的起始坐标和X/Y轴上的编号规律，具体含义参考该链接	null
maxAvailableZoom	Number	最大可用级别，当地图级别超过maxAvailableZoom后，则显示maxAvailableZoom级别的瓦片。	null
repeatWorld	Boolean	在低级别时，整个世界不满一屏时，是否重复显示世界	true
crossOrigin	String	瓦片数据的cross origin	null
debug	Boolean	是否开启调试信息，开启后地图上会绘制瓦片的编号和范围	false
maxCacheSize	Number	瓦片缓存的最大数量	256
zoomOffset	Number	瓦片zoom级别和地图zoom级别的差值	0
errorUrl	String	瓦片请求失败后的替代链接	null
token	String	用于替换url模板中的{token}，例如 http://foo/bar/{z}/{x}/{y}?token={token}	null
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"

成员方法

getData()

获取GeoJSON数据。

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const data = layer.getData();

String | Object

setData(data)

更新图层数据。

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
layer.setData('path/to/another.geojson');

参数：

data String | Object GeoJSON数据或数据远程地址。

this

getExtent()

获取GeoJSON数据的Extent。

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const extent = layer.getExtent();

maptalks.Extent

getFeature(id)

获取给定ID的Feature。

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const feature = layer.getFeature(id);

Object

getGeometryById(id)

按id获取要素（getFeature的别名）。

const layer = new GeoJSONVectorTileLayer('vt0', {
  data: 'path/to/example.geojson'
});
const feature = layer.getGeometryById(id);

参数：

id Number | String 要素id

Object

继承自VectorTileLayer的方法

setStyle(layerStyle)

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

const style = {
  style: [
    {
      filter : true,            // 数据的过滤条件
      renderPlugin: {           // 渲染插件
        type : 'native-point',
        dataConfig : {
          type : 'native-point'
        }
      },
      symbol: {                 // 样式定义
        markerSize: 6,
        markerType: 'circle',
        markerFill: '#0f0'
      }
    }
  ]
};
layer.setStyle(style);

参数：

style Object 图层样式对象，可选的属性如下:

属性名	类型	描述	默认值
style	Object[]	渲染插件数组	[]
featureStyle	Object[]	单个Feature的渲染插件列表	[]
$root	String	资源目录根路径	null

this

getStyle()

获取图层样式

Object

getComputedStyle()

获取处理后的图层样式，与style的区别主要是：

如果style中定义了$root, computedStyle中的资源路径都是合并后的路径
style中的样式定义可能是被压缩后的，computedStyle中都是未压缩的

Object

outlineAll()

高亮图层上所有的数据。

因为高亮是采用后处理实现的，图层需要加入GroupGLLayer，且outline后处理是开启的。

layer.addTo(groupGLLayer);
layer.outlineAll();

this

outlineBatch(idx)

高亮style中序号为idx的渲染插件渲染的数据。

同outlineAll相同，需要加入GroupGLLayer并开启outline后处理。

layer.addTo(groupGLLayer);
layer.outlineBatch(0);

参数：

idx Number style的序号

this

outline(idx, featureIds)

序号为idx的渲染插件渲染的数据中，高亮指定的feature。

layer.addTo(groupGLLayer);
layer.outline(0, [0]);

参数：

idx Number style的序号
featureIds Number[] | String[] feature id 数组

this

cancelOutline()

取消高亮。

this

updateSymbol(idx, symbol)

更新序号为idx的渲染插件的symbol。

layer.updateSymbol(0, { polygonFill: '#0f0' });

参数：

idx Number 渲染插件序号
symbol Object 要更新的symbol属性

this

updateFeatureSymbol(idx, styleIdx, symbol)

更新序号为idx的Feature样式里，序号为styleIdx的渲染插件的symbol。

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureSymbol(0, 0, { polygonFill: '#0f0' });

参数：

idx Number featureStyle中的Feature样式序号
styleIdx Number 样式编号
symbol Object 要更新的symbol属性

this

updateSceneConfig(idx, sceneConfig)

更新序号为idx的渲染插件的sceneConfig。

layer.updateSceneConfig(0, { collision: false });

参数：

idx Number 渲染插件序号
sceneConfig Object 要更新的sceneConfig属性

this

updateFeatureSceneConfig(idx, styleIdx, sceneConfig)

更新序号为idx的Feature样式里，序号为styleIdx的渲染插件的sceneConfig。

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureSceneConfig(0, 0, { antialias: true });

参数：

idx Number featureStyle样式序号
styleIdx Number 渲染插件编号
sceneConfig Object 要更新的sceneConfig属性

this

updateDataConfig(idx, dataConfig)

更新序号为idx的渲染插件的dataConfig。

layer.updateDataConfig(0, { altitudeProperty: 'height' });

参数：

idx Number 渲染插件序号
dataConfig Object 要更新的dataConfig属性

this

updateFeatureDataConfig(idx, styleIdx, dataConfig)

更新序号为idx的Feature样式里，序号为styleIdx的渲染插件的dataConfig。

const style = {
  featureStyle: [
    {
      id: 16,
      style: [
        {
          renderPlugin: {
            dataConfig: {
              type: 'fill'
            },
            sceneConfig: {
              antialias: false
            },
            type: 'fill'
          },
          symbol: {
            polygonFill: '#f00'
          }
        }
      ]
    }
  ]
}
layer.updateFeatureDataConfig(0, 0, { foo: 1 });

参数：

idx Number featureStyle样式序号
styleIdx Number 渲染插件编号
dataConfig Object 要更新的dataConfig属性

this

identify(coordinates, options)

在图层上查询给定坐标处的数据。需要注意的是，只有绘制出来的数据才能被查询到。

layer.identify([121.23, 39.34], { tolerance: 2 })

参数：

coordinates Number[] 坐标值
options Object 设置，可能的属性： | 属性名 | 类型 | 描述 | 默认值 | | ------ | :----: | ---- | :-----------: | | tolerance | Number | 查询时的像素冗余值 | 3 |

Object[]

identifyAtPoint(containerPoint, options)

在图层上查询给定屏幕坐标处的数据

layer.identifyAtPoint([400, 300], { tolerance: 2 })

参数：

coordinates Number[] 坐标值
options Object 设置，可能的属性：

属性名	类型	描述	默认值
tolerance	Number	查询时的像素冗余值	3

Object[]

getDataSchema(zoom)

获取给定级别上的图层定义和属性定义。

需要注意的是，只有某个级别的瓦片的曾经载入过，才能正常获取，未载入过的瓦片级别的data schema是无法获取的。

const schema = layer.getDataSchema(8);

参数：

zoom Number 瓦片级别

Object[]

继承自TileLayer的方法

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

getTileSize()

获取瓦片高宽

Size

getTiles()

获取瓦片

Object

getTileUrl(x, y, z)

获取瓦片url

String

clear()

清空图层

toJSON()

获得图层的JSON对象，这个JSON对象可以通过 maptalks.Layer.fromJSDN(json) 方法还原为图层对象。

Object

getSpatialReference()

获得图层的空间参考对象。

SpatialReference

继承自Layer的方法

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

getId()

获得图层id

Number | String

setId(id)

设置图层id

this

addTo(map)

添加到地图上。

this

getMinZoom()

获取最小瓦片级别。

Number

getMaxZoom()

获取最大瓦片级别。

Number

getMap()

获取图层添加到的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

静态方法

compressStyleJSON(style)

通过合并相同定义的渲染插件，把style JSON压缩为尺寸更小的JSON对象。

const compressedStyle = GeoJSONVectorTileLayer.compressStyleJSON(style);

参数：

style Object 样式对象

Object

registerPlugin(Plugin)

注册新的渲染插件。

GeoJSONVectorTileLayer.registerPlugin(PluginClazz);

参数：

PluginClazz PainterPlugin 要注册的渲染插件类

getPlugins()

获取所有注册的渲染插件。

const pluginClasses = GeoJSONVectorTileLayer.getPlugins();

PainterPlugin[]

fromJSON(json)

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

const json = layer.toJSON();

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

GeoJSONVectorTileLayer

事件

图层事件监听示例代码：

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

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

图层事件

dataload

数据成功加载事件。

参数属性：

属性名	类型	值
type	String	"dataload"
target	GeoJSONVectorTileLayer	this
extent	Number[]	数据Extent范围

dataerror

数据加载错误事件。

参数属性：

属性名	类型	值
type	String	"dataerror"
target	GeoJSONVectorTileLayer	this
error	String	错误信息

继承自VectorTileLayer的事件

iblupdated

环境光更新事件。

参数属性：

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

canvasisdirty

图层画布产生绘制的事件。

参数属性：

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

workerready

worker准备就绪事件。

参数属性：

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

datareceived

获取到瓦片数据事件。

参数属性：

属性名	类型	值
type	String	"datareceived"
target	VectorTileLayer	this
url	String	瓦片数据地址

pluginsinited

渲染插件初始化结束事件。

参数属性：

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

setstyle

设置样式事件。

参数属性：

属性名	类型	值
type	String	"setstyle"
target	VectorTileLayer	this
style	Object[]	样式对象
computedStyle	Object[]	处理后的样式对象

updatesceneconfig

updatesceneconfig事件。

参数属性：

属性名	类型	值
type	String	"updatesceneconfig"
target	VectorTileLayer	this
index	Number	样式序号
sceneConfig	Object	scene config对象

updatefeaturesceneconfig

updatefeaturesceneconfig事件。

参数属性：

属性名	类型	值
type	String	"updatefeaturesceneconfig"
target	VectorTileLayer	this
index	Number	Feature样式序号
styleIdx	Number	Feature渲染插件序号
sceneConfig	Object	scene config对象

updatedataconfig

updatedataconfig事件。

参数属性：

属性名	类型	值
type	String	"updatedataconfig"
target	VectorTileLayer	this
index	Number	样式序号
dataConfig	Object	data config对象

updatefeaturedataconfig

updatefeaturedataconfig事件。

参数属性：

属性名	类型	值
type	String	"updatefeaturedataconfig"
target	VectorTileLayer	this
index	Number	Feature样式序号
styleIdx	Number	Feature渲染插件序号
dataConfig	Object	data config对象

updatesymbol

updatesymbol事件。

参数属性：

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

updatefeaturesymbol

updatefeaturesymbol事件。

参数属性：

属性名	类型	值
type	String	"updatefeaturesymbol"
target	VectorTileLayer	this
index	Number	Feature样式序号
featureStyleIndex	Number	Feature渲染插件序号
symbol	Object	symbol对象

继承自TileLayer的事件

tileload

瓦片载入事件。

参数属性：

属性名	类型	值
type	String	"tileload"
target	VectorTileLayer	this
tile	Object	瓦片对象
tileImage	Object	瓦片数据

tileerror

瓦片载入错误事件。

参数属性：

属性名	类型	值
type	String	"tileerror"
target	VectorTileLayer	this
error	String	错误信息
tile	Object	瓦片对象

继承自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

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

GeoJSONVectorTileLayer ​

样式 ​

构造函数 ​

成员方法 ​

继承自VectorTileLayer的方法 ​

继承自TileLayer的方法 ​

继承自Layer的方法 ​

静态方法 ​

事件 ​

图层事件 ​

继承自VectorTileLayer的事件 ​

继承自TileLayer的事件 ​

继承自Layer的事件 ​

GeoJSONVectorTileLayer

样式

构造函数

成员方法

继承自VectorTileLayer的方法

继承自TileLayer的方法

继承自Layer的方法

静态方法

事件

图层事件

继承自VectorTileLayer的事件

继承自TileLayer的事件

继承自Layer的事件