入门必读：MapGIS Client for JS使用指南

前言

随着二三维一体化开发需求的持续增长，越来越多的WebGIS应用需要支持二维地图与三维地球的无缝切换。但是当前主流的开源地图引擎（如 Leaflet、Mapbox、OpenLayers、Cesium）在接口设计、视图控制、图层模型等方面存在较大差异，导致开发者在多个引擎之间切换时需编写大量重复代码，开发效率与维护成本显著增加。
为了解决上述痛点，MapGIS Client for JavaScript 提供了一套统一的开发接口，覆盖视图管理、图层管理、地图可视化、地图编辑、GIS 服务器对接、几何要素定义以及客户端空间计算等webgis应用常用接口。通过这套接口，可以最大程度提升二三维地图引擎之间的代码通用与逻辑复用率，显著提升开发效率和系统一致性。
此外，为了兼容主流开源引擎生态，并降低开发者的学习与迁移成本，MapGIS Client for JavaScript 还提供了混合开发模式。开发者可以在保留对底层开源引擎的灵活控制的同时，使用 MapGIS Client 提供的高级能力，实现更快速、更统一的地图应用开发体验。
以下面加载天地图 WMTS 服务为例，可以直观体现出各地图引擎在接口设计、使用门槛上的差异。虽然 WMTS 是一种标准服务，但由于各引擎对其支持方式不同，导致开发者在接入过程中往往需要预先了解很多底层细节，使用体验并不一致。

• leaflet

L.tileLayer('https://t{s}.tianditu.gov.cn/vec_w/wmts?tk=abcdefg&service=WMTS&request=GetTile&version=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILECOL={x}&TILEROW={y}&TILEMATRIX={z}', {
  subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
  tileSize: 256,
  maxZoom: 18
}).addTo(map);

Leaflet 虽然支持通过 URL 模板加载 WMTS 服务，但开发者需要请求 GetCapabilities 文档，手动解析图层名称、投影坐标系、瓦片集等参数然后拼接 URL。对于不了解 OGC 标准基础的开发者，这一过程并不直观且容易出错。

• mapbox

map.addSource('tdt', {
  type: 'raster',
  tiles: [
    'https://t0.tianditu.gov.cn/vec_w/wmts?tk=abcdefg&service=WMTS&request=GetTile&version=1.0.0&LAYER=vec&STYLE=default&TILEMATRIXSET=w&FORMAT=tiles&TILECOL={x}&TILEROW={y}&TILEMATRIX={z}'
  ],
  tileSize: 256
});
map.addLayer({
  id: 'tdt-layer',
  type: 'raster',
  source: 'tdt'
});

Mapbox 的 WMTS 支持则更为复杂。由于其渲染引擎采用专有的样式规范，不原生支持 WMTS 协议，因此需要开发者将 WMTS 服务转化为类似 XYZ 服务的形式，通过拼接 URL 并手动配置 addSource 和 addLayer。这一过程中，不仅需要了解 WMTS 切片规则和坐标系，还要理解 Mapbox 特有的图层模型和样式配置方式。

• cesium

const viewer = new Cesium.Viewer('cesiumContainer', {
  imageryProvider: new Cesium.WebMapTileServiceImageryProvider({
    url: 'https://t0.tianditu.gov.cn/vec_w/wmts?tk=abcdefg',
    layer: 'vec',
    style: 'default',
    format: 'tiles',
    tileMatrixSetID: 'w',
    tilingScheme: new Cesium.WebMercatorTilingScheme(),
    maximumLevel: 18
  }),
  baseLayerPicker: false
});

Cesium 则严格遵循和支持WMTS标准规范，提供了 WebMapTileServiceImageryProvider 类来加载 WMTS 服务，但它对参数的要求极为严格。需要开发者准确指定图层名称、样式、投影、瓦片集等多个参数，且这些参数之间有较强的耦合关系。

因此，尽管 WMTS 是一种标准服务，各地图引擎的实现方式却存在较大差异。对于新手开发者而言，不仅要理解底层协议和服务配置，还要适应不同引擎的接口设计和图层管理模式。这些差异使得服务接入的难度增大，降低了开发效率，也增加了出错的风险。

兼容原理

MapGIS Client for JavaScript 通过common+plugin的分层架构实现了“一套接口，兼容多种地图引擎”。

• common层提供与地图引擎无关的接口和功能，包含基础对象、地图符号、服务库、图层、地图（场景）、地图（场景）视图、空间分析、草图编辑、行业标绘等模块。可独立使用，也可以和 MapGIS Client for JavaScript 产品中地图引擎库、引擎插件库组合使用。
  

• plugin层则是common层与对应的地图引擎之间的“翻译”，通过plugin解析common层的参数，并调用具体地图引擎的对应接口，实现不同地图引擎的接口统一。
  

下载安装

MapGIS Client for Javascript提供了ES5和ES6两种版本。

ES5版本的开发包可以在司马云-开发世界中下载。

• mapgis-client-for-javascript-all-vxxx.rar表示该包中还包含了示例站点，适合需要内网开发、部署示例站点的用户。体积较大，下载慢。
• mapgis-client-for-javascript-dist-vxxx.rar，仅包含开发包及其依赖，不含示例站点，下载速度更快，推荐使用。

ES6版本的开发包可以使用npm、pnpm 等包管理器从npm仓库下载（推荐）。

plugin库会依赖common库，因此会自动下载common。

npm install @mapgis/cesium
npm install @mapgis/webclient-cesium-plugin

npm install @mapgis/leaflet
npm install @mapgis/webclient-leaflet-plugin

npm install @mapgis/mapboxgl
npm install @mapgis/webclient-mapboxgl-plugin

拉取的库中也有ES5版本的库。

开发模式

MapGIS Client for JavaScript支持common层接口的开发和混合开发两种模式，因此示例也分为两种，使用common层接口（从下图①中菜单进入）的示例和混合开发模式从下图②中菜单进入的示例。

common层接口开发

common层接口开发模式，适合对开源的地图引擎接口不熟悉，或有二三维一体化需求的开发者。可以在不同地图引擎上获得一致的开发体验。

     // 初始二维地图
      function initView() {
        // 初始化图层管理容器
        map = new Map()
        // 初始化地图视图对象
        view = createView('mapgis-viewer', map)
      }
      // 添加瓦片图层
      function addLayer() {
        // 创建瓦片图层
        layer = new WMTSLayer({
          // 服务基地址
          url: 'http://webclient.smaryun.com:8089/igs/rest/services/Tile/HuBei_4326/WMTSServer',
          // 图层透明度
        })
        // 添加图层
        map.add(layer)
      }

混合开发模式

混合开发模式，适合对开源的地图引擎接口比较熟悉，没有二三维一体化需求的开发者。
本质上是使用common层解析图层所需的参数并构造对应的图层对象。

      // 添加图层
      function addLayer(url, center, zoom) {
        center = center || [31.147781205532336,112.21905099757561]
        zoom = zoom || 6
        // 构造一个IGS瓦片图层对象
        const layer = new WMTSLayer({
          // 服务基地址
          url: url
        })
        // 加载元数据
        layer.load().then(function () {
          // 构造Leaflet地图视图的初始化参数
          const crs = initializeCRS(layer)
          const mapViewOptions = {
            // 地图视图参考系
            crs: crs,
            // 初始化中心点
            center: center,
            // 初始化级数
            zoom: zoom
          }
          // 构造Leaflet地图视图对象
          map = L.map('mapgis-viewer', mapViewOptions)
          // 构造Leaflet瓦片图层的初始化参数
          const layerOptions = initializeOptions(layer)
          // 添加Leaflet瓦片图层到地图视图中
          new WebMapTileServiceLayer(layer.url, layerOptions).addTo(map)
        })
      }

文档查看

进入MapGIS Client for JavaScript可以进入示例站点。
MapGIS Client for JavaScript支持common层接口的开发和混合开发两种模式，因此示例也分为两种，使用common层接口（从下图①中菜单进入）的示例和混合开发模式从下图②中菜单进入的示例。

MapGIS Client for JavaScript分为common层、plugin层、引擎层，因此文档也分为三部分。如下图分别是common层、引擎层的文档、plugin层。

1、应该查看哪些文档？

绝大多数情况下应该查看common层的文档，因为无论使用哪种引擎、不哪种开发模式，common层的接口是通用的。common层涉及如下的模块：

模块名	模块说明
几何模块(Geometry)	定义了几何的多种类型，包含点、线、区、多点、多线、多区、圆、矩形等常用基础几何结构，空间参考系
符号模块(Symbol)	定义了地图渲染所需的符号
要素模块(Feature)	定义了要素、要素集
渲染器模块(Renderer)	定义了图层的渲染器
服务模块(Service)	提供GIS服务接口的封装，方便GIS服务接口的调用
图层模块(Layer)	定义了图层相关的API，方便GIS服务的接入
地图模块(Map)	提供图层管理功能
视图模块(View)	提供地图视图、场景视图接口的定义
草图编辑模块(SketchEditor)	草图编辑模块，提供点、线、区等几何的绘制和编辑功能，用于实现要素的采集和量算

如定义视图、图层相关（管理、添加、移除、监听、修改图层状态等）、调用IGServer的服务、修改矢量图层的样式、绘制功能等，都需要查看common层的文档。

如果要使用地图引擎的原生的接口，则查看引擎层的文档。如cesium、leaflet、mapbox等引擎的文档。

2、有些参数查不到怎么办？

common层使用的面向对象设计，很多类都继承自基类，因此有些参数可以参考基类的文档。如各种类型的图层都继承自Layer类，因此可以参考Layer类的文档。
还有些参数可能位于plugin层，如popup，可以参考plugin的文档。

3、不同地图引擎的参数不一致，统一使用MapView类初始化地图视图，怎么传引擎特有的参数？

可以通过MapView类的extensionOptions属性传入引擎特有的参数。如leaflet的MapView类初始化时，可以通过extensionOptions属性传入doubleClickZoom、zoomControl参数，用于设置地图视图的双击事件缩放事件和缩放控件显示。

4、使用common层接口开发时，如何获取原生的地图视图对象？

各类地图引擎都有丰富的第三方插件生态，很多插件都需要传入地图引擎的实例化的视图对象，使用common层开始时，二维统一使用MapView类，三维统一使用SceneView类，可以通过MapView类和SceneView的getInnerView方法获取原生的地图视图对象，在leaflet引擎上返回leafelt map,在cesium引擎上返回cesium viewer。

          //初始化球体
      function initViewer() {
        //初始化图层管理容器
        map = new zondy.Map()
        //初始化地图视图对象
        sceneView = new zondy.cesium.SceneView({
          //视图id
          viewId: 'mapgis-3d-viewer',
          //图层管理容器
          map: map
        })
        //获取视图对象
        viewer = sceneView.getInnerView()
      }