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

MapGIS Client for JavaScript（common）是 WebClient 的基础能力包，他提供与地图引擎无关的接口和功能，采用面向对象设计理念，遵循 ES6 标准，包含基础对象、地图符号、服务库、图层、地图（场景）、地图（场景）视图、空间分析、草图编辑、行业标绘等模块。可独立使用，也可以和 MapGIS Client for JavaScript 产品中地图引擎库、引擎插件库组合使用，可以最大限度的实现代码在不同在图引擎上的复用，快速实现二三维一体化应用的开发。

- 示例站点：[http://webclient.smaryun.com](http://webclient.smaryun.com)

## 1.1、获取方式

### 1.1.1、npm 安装

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

```typescript
npm install @mapgis/webclient-common
```

适用于 Vite、Webpack、Rollup 等构建环境。

### 1.1.2、静态资源引入

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

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

- `dist/esm/webclient-common.js`
- `dist/umd/webclient-common.min.js`
- `dist/webclient-common-resource`

常见做法是将 `dist/umd/webclient-common.min.js` 和资源目录拷贝到项目静态资源目录，再通过 `<script>` 加载。

## 1.2、能力范围

- `service`：请求、拦截器、地图服务、要素服务、场景服务、专题图服务
- `layer`：图层、子图层、影像、矢量、场景和栅格图层
- `geometry`：几何、空间参考、投影和几何运算
- `view`：二维 / 三维视图和图层视图
- `symbol`：符号、3D 符号和材质
- `tool`：视图工具、剖切工具和编辑工具
- `util`：通用工具方法、Worker 和 GDAL 相关能力
- `enum`：枚举和常量

# 2、引入方式

## 2.1、ESM 引入

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

```typescript
import { Map as ZondyMap, IGSMapImageLayer, GeometryEngine, Point } from '@mapgis/webclient-common'
```

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

## 2.2、全局引入

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

```html
<script src="/static/libs/zondyclient/webclient-common.min.js"></script>
<script>
  const legacyNamespace = window.zondy
  const compatNamespace = window.Zondy
</script>
```

全局对象保留 `window.zondy` 和 `window.Zondy` 兼容入口，便于旧代码兼容。

# 3、快速开始

下面示例只展示 common 包本身的数据模型和通用能力调用方式。实际项目中的视图对象由 Cesium、Leaflet、MapboxGL 或 MapLibreGL 等具体引擎插件创建。

## 3.1、创建并添加图层

```typescript
import { Map as ZondyMap, IGSMapImageLayer } from '@mapgis/webclient-common'

const zondyMap = new ZondyMap()
const mapImageLayer = new IGSMapImageLayer({
  url: 'http://server/igs/rest/services/map/MapServer'
})

zondyMap.add(mapImageLayer)
```

## 3.2、计算两点距离

```typescript
import { GeometryEngine, Point } from '@mapgis/webclient-common'

const startPoint = new Point({
  coordinates: [114.3, 30.6],
  spatialReference: { wkid: 4326 }
})

const endPoint = new Point({
  coordinates: [114.4, 30.7],
  spatialReference: { wkid: 4326 }
})

const distance = GeometryEngine.distance(startPoint, endPoint, 'meters')
```

## 3.3、全局方式

```html
<script>
  const zondyMap = new zondy.Map()
  const mapImageLayer = new zondy.layer.IGSMapImageLayer({
    url: 'http://server/igs/rest/services/map/MapServer'
  })

  zondyMap.add(mapImageLayer)
</script>
```

# 4、@mapgis/webclient-common 版本说明

## v17.10.5

1. 修复

- 修复组图层视图并发添加时误删图层视图问题

## v17.10.4

1. 修复

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

## v17.10.2

1. 修复

- 统一WMTS/WMS图层标题取值逻辑，与tileserver服务名称保持一致

## v17.10.0

1. 新增

- 丰富和完善了三维符号体系
- 草图编辑器支持三维编辑：支持撤销 回退；支持基于线、区生成的三维体如:墙、管线、棱柱；支持球、棱柱、棱锥、圆柱、模型等三维几何体；支持三维平移、缩放、旋转编辑
- common 层为 ImageryLayer、MapImageLayer、TileLayer、WMSLayer、WMTSLayer、VectorTileLayer、IGSSceneMapRefSubLayer补充 elevationInfo 高程参数，支持通过图层配置统一设置高程模式。
- popup弹窗支持自动调整展示方位
- 栅格体元支持通过具体数值设置颜色条
- 新增服务接口：1.获取图幅号列表 2.根据经纬度坐标获取图幅号 3.根据图幅号获取图幅信息
- 支持设置令牌携带位置

2. 优化

- IGSMapImageLayer和IGSFeatureLayer支持获取属性结构
- ArcGIS REST地图服务export接口imageSR参数支持传入wkt

3. 修复

- 修复已知问题

## v17.8.10

1. 修复

- 修复 WFSLayer 不支持 hitTest 拾取的问题
- 修复拦截器解码报错的问题

## v17.8.9

1. 修复

- 修复 URL 请求参数为按规范编码，导致服务器端解析参数失败的问题

## v17.8.8

1. 修复

- 修复 URL 域名含有短划线（-）的地图服务无法加载的问题

## v17.8.7

1. 修复

- 修复已知问题

## v17.8.6

1. 修复

- 修复已知问题

## v17.8.5

1. 修复

- 图层上的 capabilities 属性设置为不可枚举状态

## v17.8.4

1. 修复

- 修复部分图层中动态设置 tokenAttachType 属性失效的问题

## v17.8.3

1. 修复

- 修复加载 mbtiles 存储类型发布的矢量瓦片服务报错的问题

## v17.8.2

1. 修复

- 修复已知问题

## v17.8.1

1. 修复

- 修复 WMTS 图层克隆报错的问题

## v17.8.0

1. 新增

- 场景下支持图标和图标上动态 Tip 的避让
- 提供视图卷帘工具（当前仅 Leaflet 引擎中的 MapView 支持）
- 支持 GeoServer 平台发布的 WMS、WMTS、WFS 服务
- GeoJson 接入能力增强，支持加载 MapGIS Desktop 上导出的 GeoJson (ESRI WKT)

2. 修复

- 统一部分符号属性在不同引擎上的效果差异
- 优化服务请求失败的状态信息

## v17.6.25

1. 修复

- 修复已知问题

## v17.6.24

1. 修复

- 优化 gdal 库初始化加载问题

## v17.6.23

1. 修复

- 修复已知问题

## v17.6.22

1. 新增

- 草图编辑器中增加选中顶点的事件

## v17.6.20

1. 新增

- 草图编辑器增加 editOption 配置编辑模式
- BaseView 中增加 innerView-created 引擎视图创建完毕事件

## v17.6.19

1. 修复

- 解决图层视图还未加载完毕时移除图层失败的问题

## v17.6.16

1. 新增

- BaseView 中的 goto 接口增加 goToLayerMode 参数，支持模式'extent'按数据范围跳转、'fix-level'按范围并调整到到整数级跳转
- 提供 BaseSwipeTool 接口支持对视图进行卷帘

## v17.6.15

1. 新增

- 支持加载 GeoServer 平台发布的 WMS/WMTS/WFS 服务
- IGS地图服务支持设置快显出图模式

2. 修复

- 修复部分要素图层查询要素报错的问题
- 修复地图服务图层 post 请求方式动态添加删除图层时报错的问题
- 修复 GeometryEngine 获取质心空间参考系错误的问题
- 修复 WMS 服务加载 IGS2.0 服务时，仍使用 IGS1.0 格式服务地址的问题

## v17.6.14

1. 新增

- 支持 ogc wkt2.0 标准的投影变换

## v17.6.13

1. 新增

- MapView 支持传入 innerView 引擎地图对象构造地图视图

## v17.6.12

1. 新增

- MapView、SceneView 默认视角调整为中国区域，增加初始时是否跳转定位的参数控制

2. 修复

- 优化 MapView、SceneView 中 goTo 跳转方法的效果；goTo 时间间隔不传时，默认为地图引擎的动画效果

## v17.6.11

1. 修复

- 修复 IGS 地图服务动态投影显示位置异常的问题
- 修复 WFS 图层渲染多区多边形异常的问题
- 修复测量工具中空间测量距离异常的问题

## v17.6.10

1. 修复

- 修复 FetchServer 中 Error.isError 语法兼容性的问题

## v17.6.9

1. 修复

- 修复 GeoJSONLayer 加载异常的问题

## v17.6.8

1. 新增

- GeoJson接入能力增强，支持加载 MapGIS Desktop 上导出的 GeoJson (esri wkt)

2. 修复

- 优化服务请求失败的状态信息

## v17.6.7

1. 修复

- 修复 IGS 栅格瓦片叠加无法预览的问题

## v17.6.6

1. 修复

- 修复三维最大最小比例尺异常的问题
- 修复 WebTileLayer 无法识别自动加载天地图 WMST 服务地址

## v17.6.5

1. 新增

- GeoJSON 图层能力增强，支持解析 crs 为 name 类型
- 增加支持 https、ftp、gopher、file 的 URL 服务协议

## v17.6.3

1. 修复

- 地图服务图层、矢量瓦片图层、瓦片图层加载 IGS1.0 版本服务时，空间参考系调整为可选填的参数
- 优化图层load机制，load失败按 UnknowLayer 图层方案处理

## v17.6.2

1. 修复

- 修复地图服务子图层设置renderer后无法恢复默认状态的问题
- 修复FeatureServer的queryFeaturesInLayers查询报错的问题

## v17.6.1

1. 修复

- 修复加载二维点矢量数据发布的地图服务边缘缺失符号的问题
- 修复一些场景中GraphicsLayer中要素无法更新的问题
- 修复wmts服务代理后无法加载错误的问题

## v17.6.0

1. 新增

- 服务接口支持请求头 Header 传 Token
- 支持加载 IGSImageServer 影像服务
- 支持接入 IGS 加密瓦片服务
- 地图服务（IGSMap地图服务、ArcGIS地图服务、WMS服务）支持全屏一张图加载方式

2. 修复

- IGSSceneLayer、ISSceneLayer子图层功能增强
- 草图编辑工具接口的优化并增强，支持动态设置几何图层、提示文字、高程模式
- SimpleLineSymbol、SimpleFillSymbol、TextSymbol等符号效果的优化和增强
- 枚举类型的规范化

## v17.4.7

1. 新增

- 要素缓冲区分析分析接口增加resultName参数

2. 修复

- 优化要素与图层叠加分析工作流接口说明
- 修复GraphicsLayer的removeMany接口失效问题
- 修复草图编辑工具中草图选中事件无法监听的问题

## v17.4.6

1. 修复

- 修复M3D图层根据图层id获取innerLayer异常的问题
- 修复ArcGIS地图服务未加载全部子图层的问题
- 优化WMTS服务加载逻辑

## v17.4.5

1. 修复

- 修复草图编辑中文字、绘制区绘制异常的问题

## v17.4.4

1. 修复

- 修复已知问题

## v17.4.3

1. 新增

- IGS要素图层增加时间维度、网格过滤功能

2. 修复

- 修复要素服务多图层查询异常问题

## v17.4.2

1. 修复

- 修复要素服务中参数解析错误的问题
- 增强要素对象的兼容性

## v17.4.1

1. 修复

- 修复API文档中部分接口文档缺失的问题
- 修复已知问题

## v17.4.0

1. 新增

- IGS要素图层支持传入FeatureServer中的查询参数
- 分段专题图支持归一化配置
- 新增IS场景图层，支持加载S3M数据

2. 修复

- 修复要素服务图层无法使用gdb地址的问题
- 优化矢量瓦片的子图层显隐逻辑

## v17.2.8

1. 修复

- 修复要素图层样式无法修改问题
- 修复要素图层无法使用gdbp数据问题

## v17.2.7

1. 修复

- 修复图层服务数据范围异常时的地图加载问题

## v17.2.6

1. 修复

- 修复图层服务数据范围异常时的地图加载问题

## v17.2.5

1. 修复

- 修复已知问题

## v17.2.4

1. 修复

- 优化矢量瓦片的子图层显隐逻辑

## v17.2.3

1. 修复

- extentOptions属性调整为extensionOptions
- 优化接口版权信息属性

## v17.2.2

1. 修复

- 修复已知问题

## v17.2.1

1. 修复

- 优化命名空间结构
- 修复已知问题

## v17.2.0

1. 新增

- 矢量瓦片图层支持单独加载矢量瓦片服务中的子图层
- ArcGIS地图服务支持出一张图模式

2. 修复

- 优化投影变化功能使其支持自定义WKID投影

## v17.0.0

1. 新增

- 多引擎新增支持接入ArcGIS矢量瓦片服务
- 多引擎支持接入标准互联网瓦片服务
- 地图服务支持服务器端空间过滤显示
- 草图编辑支持手绘线、区，支持扩展三角形、椭圆类型
- 符号体系增加对三维符号和动态注记的支持

2. 修复

- 优化Echart图层效果，解决偏移问题

## v16.8.0

1. 新增

- 矢量瓦图层和栅格瓦片图层支持空间裁剪
- 增加支持 ArcGISVectorTileLayer 加载
- 增加Basemap地图底图功能
- 丰富完善草图编辑相关功能
- 符号体系增强，Render接口的增强

## v16.6.0

1. 新增

- 新增 Symbol 模块、SketchEditor 模块
- 增加 GeometryEngine 类。
- 丰富完善 MapView 上接口
- 维护更新，修复若干 Bug

## v16.4.0

1. 新增

- 首次发行，提供 Geometry 模块、Feature 模块、Service 模块、Layer 模块、Map 模块、View 模块