用 iClient 加载 SuperMap 地图服务图层
用 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。

基本加载步骤怎么写
面向会动手的 GIS 开发者,先解决“把服务铺到地图上”这件事。假设你已通过 npm 安装 @supermapgis/iclient-leaflet(旧包名是 @supermap/iclient-leaflet)或用 script 引入了 leaflet.js + iclient-leaflet.js,并准备好 Leaflet CSS。按下面顺序做即可验证。
- 准备一个全屏或固定高度的 div 容器(例如 id=”map”),并引入 Leaflet 与 iClient 的 JS/CSS。
- 创建地图实例,必须显式指定 CRS(常见 L.CRS.EPSG4326 或 L.CRS.EPSG3857),同时设置 center、zoom、maxZoom。center 一般用经纬度。
- 准备 REST 地图服务地址,官方示例常用 https://iserver.supermap.io/iserver/services/map-world/rest/maps/World。你自己的服务格式通常是 …/iserver/services/map-xxx/rest/maps/地图名。
- 实例化图层并加入地图:new L.supermap.TiledMapLayer(url, options).addTo(map)。旧写法 L.supermap.tiledMapLayer(url) 也可用。需要动态出图时改用 new L.supermap.ImageMapLayer(url)。
- 打开浏览器控制台看网络请求是否返回瓦片/图片,地图是否出现对应范围。缩放、平移验收层级是否连贯。
完整可运行示例可直接参考 GitHub 上的 Leaflet 示例目录(如 01_tiledMapLayer4326.html、01_tiledMapLayer3857.html、01_overlayTiledMapLayer.html)。版本与变更说明见 iClient-JavaScript Releases。

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 页面即可。