用 iClient 加载 SuperMap 地图服务图层

WebGIS
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

用 SuperMap iClient for Leaflet 加载 SuperMap 地图服务图层,核心做法是创建 Leaflet 地图并指定与服务匹配的 CRS,再实例化 L.supermap.TiledMapLayer(瓦片方式,走 TileImage 接口)或 ImageMapLayer(动态 Image 出图),把 iServer / iEdge 等发布的 REST 地图服务 URL 传进去并 addTo(map)。最常见写法是 new L.supermap.TiledMapLayer(url).addTo(map),也可叠加多个图层并设置 transparent、opacity 等。截至 2026 年 10 月,推荐使用 iClient JavaScript 12.1.x(最新约 12.1.3),配合 Leaflet 1.0.3~1.9.4。

用 iClient for Leaflet 加载 SuperMap 地图服务后的效果示意

基本加载步骤怎么写

面向会动手的 GIS 开发者,先解决“把服务铺到地图上”这件事。假设你已通过 npm 安装 @supermapgis/iclient-leaflet(旧包名是 @supermap/iclient-leaflet)或用 script 引入了 leaflet.js + iclient-leaflet.js,并准备好 Leaflet CSS。按下面顺序做即可验证。

  1. 准备一个全屏或固定高度的 div 容器(例如 id=”map”),并引入 Leaflet 与 iClient 的 JS/CSS。
  2. 创建地图实例,必须显式指定 CRS(常见 L.CRS.EPSG4326 或 L.CRS.EPSG3857),同时设置 center、zoom、maxZoom。center 一般用经纬度。
  3. 准备 REST 地图服务地址,官方示例常用 https://iserver.supermap.io/iserver/services/map-world/rest/maps/World。你自己的服务格式通常是 …/iserver/services/map-xxx/rest/maps/地图名。
  4. 实例化图层并加入地图:new L.supermap.TiledMapLayer(url, options).addTo(map)。旧写法 L.supermap.tiledMapLayer(url) 也可用。需要动态出图时改用 new L.supermap.ImageMapLayer(url)。
  5. 打开浏览器控制台看网络请求是否返回瓦片/图片,地图是否出现对应范围。缩放、平移验收层级是否连贯。

完整可运行示例可直接参考 GitHub 上的 Leaflet 示例目录(如 01_tiledMapLayer4326.html、01_tiledMapLayer3857.html、01_overlayTiledMapLayer.html)。版本与变更说明见 iClient-JavaScript Releases。

SuperMap iClient for Leaflet 官方示例代码目录页面
SuperMap iClient for Leaflet 官方示例代码目录页面(截图来源:github.com)

TiledMapLayer 和 ImageMapLayer 怎么选

两者都用于加载 SuperMap REST 地图服务,但出图方式和性能场景不同。

  • TiledMapLayer:继承 L.TileLayer,按瓦片请求,适合已缓存或适合切片的底图、大范围浏览。默认走 TileImage,可开 cacheEnabled、bufferTiles、tileCache 等提升流畅度。
  • ImageMapLayer:继承 L.Layer,整幅动态出图,适合临时专题、频繁改图层可见性或需要实时过滤的场景。请求参数更灵活,但对服务端压力通常更大。

日常底图优先 TiledMapLayer;需要按属性过滤、临时图层或动态投影出图时再考虑 ImageMapLayer。叠加时给上层设 transparent: true 并控制 opacity,必要时用 bringToFront / bringToBack 调整顺序。服务端切片与缓存策略也会影响体感,发布与性能相关实践可对照本站 SuperMap 发布三维服务与切片缓存性能优化 中的缓存思路(二维 REST 地图服务同样受益于合理切片)。

对比项 TiledMapLayer ImageMapLayer
继承 L.TileLayer L.Layer
请求方式 瓦片 TileImage 动态 Image
典型用途 底图、缓存瓦片 专题、临时图层、过滤
常用选项 cacheEnabled、bufferTiles、tileCache、overflowTiles layersID、displayFilters、prjCoordSys

坐标系不匹配时怎么配 CRS

iClient for Leaflet 不会自动读取服务 CRS,地图 crs 必须与服务一致,否则常见白屏、偏移或不出图。默认方便使用 EPSG:4326、EPSG:3857;平面坐标可用 L.CRS.NonEarthCRS;其他投影(如部分国内常用坐标系)需用 Proj4js 定义后配合 L.supermap.Proj.CRS(或 L.Proj.CRS)设置 origin、bounds、resolutions / scaleDenominators。

  • 服务是经纬度:map 用 crs: L.CRS.EPSG4326,center 用 [纬度, 经度]。
  • 服务是 Web 墨卡托:用 L.CRS.EPSG3857。
  • 自定义投影:先 defs 投影字符串,再 new L.supermap.Proj.CRS(…),把 resolutions 或比例尺分母配齐,避免缩放到服务没有的层级出现空白。
  • 查询/分析结果若返回投影坐标,交互前用 project / unproject 或 L.Util.transform 转到 Leaflet 使用的经纬度。

数据入库或服务发布前坐标乱、参数设错,也会导致前端怎么调都偏。这类源头问题可参考本站 SuperMap 导入数据乱码与坐标转换参数设置,先保证服务本身 CRS 正确再写前端。

常用参数与验收注意点

构造图层时第二个参数是 options。下面这些在生产里最常改(以官方 API 为准,版本差异以 12.1.x 文档为准):

参数 作用简述 注意
transparent 背景透明,便于叠加 上层专题图几乎必开
opacity 整体透明度 与 transparent 配合
layersID 指定子图层或临时图层 动态专题常用
cacheEnabled 是否使用服务端缓存 有切片时打开更稳
format png / webp / jpg 等 webp 体积更小,需服务支持
prjCoordSys 动态投影 服务开启对应能力时用
displayFilters 属性过滤 12.x 增强,减少无关要素
clipRegion / clipRegionEnabled 裁剪显示范围 节点过多易导致请求体过长
bufferTiles / tileCache 预加载与本地瓦片缓存 12.1.x 优化项,减轻白屏

验收标准建议写进自测清单:① 初始视图中心与服务范围一致;② 缩放至服务声明的最大/最小级别仍有瓦片;③ 叠加层透明正确、无压盖错乱;④ 控制台无跨域/401,必要时配 token 或 tileProxy;⑤ 切换 layersID 或 displayFilters 后出图符合预期。

常见问题

为什么地图白屏或位置完全不对?

绝大多数是 CRS 与服务不一致,或 center/zoom 落在服务无数据范围外。先确认服务坐标系,再改 map 的 crs 与 resolutions;同时打开网络面板看瓦片 URL 是否 200 且有图。

clipRegion 节点很多时请求失败怎么办?

GET 请求体过长会被拦截。可重写 TileLayer 相关取瓦片方法,改为 POST(URI 带 _method=GET,参数放 body),再保留原有裁剪逻辑。

缩放到较高级别就不出图?

Leaflet 默认 maxZoom 往往是 18,而服务比例尺可能更细或更粗。把 maxZoom、resolutions 与服务对齐,并检查是否开启了合适的缓存与 bufferTiles。

多个图层叠加后顺序或透明不对?

给需要透视的图层设 transparent: true 和合适的 opacity,必要时调用 bringToFront / bringToBack,或显式管理 zIndex。确认服务端子图层本身也允许透明出图。

总结:用 iClient for Leaflet 加载 SuperMap 地图服务,抓住“CRS 对齐 + TiledMapLayer/ImageMapLayer 选对 + 关键 options”三件事就能稳定出图。建议先跑通官方 World 服务示例,再换成自己的 REST 地址,并把坐标系与切片配置作为上线前必查项;需要对照示例源码或确认 12.1.x 变更时,直接打开上文的 GitHub examples 与 Releases 页面即可。