1、获取 MapGIS Client for JavaScript（MapLibreGL）开发包

MapGIS Client for JavaScript（MapLibreGL）是 WebClient 面向开源 MapLibreGL 引擎的二维地图插件包，承接 @mapgis/webclient-common 的地图、图层、几何、符号和工具等通用接口，并完成 MapLibreGL 场景下的引擎适配。

该包提供 MapLibreGL 引擎下的核心能力扩展，覆盖矢量瓦片、栅格瓦片、地图视图、自定义栅格能力和 Common 抽象桥接等 WebGIS 应用能力。

• 示例站点：http://webclient.smaryun.com

1.1、获取方式

1.1.1、npm 安装

推荐在现代工程中直接通过 npm 引入：

npm install @mapgis/webclient-common @mapgis/webclient-maplibregl-plugin maplibre-gl

@mapgis/webclient-maplibregl-plugin 提供 WebClient 插件能力，maplibre-gl 提供 MapLibreGL 引擎运行时。

1.1.2、静态资源引入

如果项目暂时不接入构建链，可以直接使用发布包中的静态资源：

如果需要通过 CDN 格式开发包或离线示例站点集成，可前往：http://smaryun.com/dev/download_detail.html#/download828。

• dist/esm/webclient-maplibregl-plugin.js
• dist/umd/webclient-maplibregl-plugin.min.js
• MapLibreGL 引擎的 maplibre-gl.js 和 maplibre-gl.css

常见做法是将 MapLibreGL 引擎文件和 webclient-maplibregl-plugin.min.js 拷贝到项目静态资源目录，再通过 <script> 和 <link> 加载。

1.2、能力范围

• view：二维地图视图、图层视图和视图交互
• layer：矢量瓦片、栅格瓦片、地图服务、WMS 和 WMTS 图层
• style：MapGIS 样式、MapLibreGL 样式和矢量瓦片样式适配
• crs：通用空间参考、瓦片坐标和投影能力桥接
• editor：绘制、草图编辑和基础图形交互编辑
• adapter：MapLibreGL 引擎对象与 WebClient 通用模型桥接

2、引入方式

2.1、ESM 引入

现代工程建议使用 ESM 方式按需引入：

import 'maplibre-gl/dist/maplibre-gl.css'
import { Map as ZondyMap } from '@mapgis/webclient-common'
import { MapView, VectorTileLayer } from '@mapgis/webclient-maplibregl-plugin'

这种方式便于 tree-shaking，也更适合后续做国际化拆分和模块化维护。

2.2、全局引入

如果使用传统页面或旧工程，可直接挂载全局对象：

<link rel="stylesheet" href="/static/maplibregl/maplibre-gl.css" />
<script src="/static/maplibregl/maplibre-gl.js"></script>
<script src="/static/libs/zondyclient/webclient-common.min.js"></script>
<script src="/static/libs/zondyclient/webclient-maplibregl-plugin.min.js"></script>
<script>
  const { Map: ZondyMap } = window.MapGISWebClientCommon
  const { MapView } = window.MapGISWebClientMapLibreGLPlugin
  const legacyNamespace = window.zondy
  const compatNamespace = window.Zondy
</script>

全局对象同时保留新命名空间和 window.zondy、window.Zondy 兼容入口，便于旧代码迁移。

3、快速开始

下面示例展示二维矢量地图视图的最小初始化方式。实际项目中，请将容器尺寸设置为可见区域高度。

3.1、创建地图视图

import { Map as ZondyMap } from '@mapgis/webclient-common'
import { MapView } from '@mapgis/webclient-maplibregl-plugin'

const zondyMap = new ZondyMap()
const mapView = new MapView({
  viewId: 'map-container',
  map: zondyMap,
  center: [114.3, 30.6],
  zoom: 8
})

3.2、加载矢量瓦片图层

import { Map as ZondyMap } from '@mapgis/webclient-common'
import { VectorTileLayer } from '@mapgis/webclient-maplibregl-plugin'

const zondyMap = new ZondyMap()
const vectorLayer = new VectorTileLayer({
  url: 'http://server/igs/rest/services/vector/VectorTileServer'
})

zondyMap.add(vectorLayer)

3.3、全局方式

<div id="map-container"></div>
<script>
  const zondyMap = new zondy.Map()
  const mapView = new zondy.maplibregl.MapView({
    viewId: 'map-container',
    map: zondyMap,
    center: [114.3, 30.6],
    zoom: 8
  })
</script>

4、@mapgis/webclient-maplibregl-plugin 版本说明

v17.10.6

1. 修复

• 示例站点中，MapBoxGL和MaplibreGL引擎的ECharts/MapV示例示中WMTS图层未加载

v17.10.4

1. 修复

• 修复线符号 solid/none 样式切换失效以及同 id 图形缓存问题

v17.10.0

1. 新增

• 首次发布：基于开源MapLibre-gl的能力，完成webclient-common层视图、图层、草图编辑接口在MapLibre-gl引擎上的适配。