SuperMap iClient for Leaflet 初始化地图实例

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

SuperMap iClient for Leaflet 初始化地图实例,核心做法是先用 L.map() 创建地图对象并指定容器、crs、center、zoom 等参数,再用 new L.supermap.TiledMapLayer(url).addTo(map) 加载 iServer REST 瓦片服务。引入 Leaflet 与 iClient 的 CSS/JS 后,几行代码即可完成底图显示。截至 2026 年 11 月,推荐配合 Leaflet 1.9.4 使用 @supermapgis/iclient-leaflet 12.1.3。坐标系必须手动匹配服务,否则容易不出图或错位。

初始化完成后的 SuperMap iClient for Leaflet 世界地图示意

如何引入库与环境准备

要解决的问题是:页面能正确加载 Leaflet 基础能力和 iClient 扩展图层。常用两种方式,按项目规模选择。

  • CDN 引入:先引入 Leaflet 1.9.4 的 CSS/JS,再引入 iclient-leaflet 的 CSS/JS。官方示例常用此方式,适合快速验证。
  • npm 引入:执行 npm install @supermapgis/iclient-leaflet(自 11i(2024) v11.2.0 起包名已迁移,旧包 @supermap/iclient-leaflet 不再推荐)。ES6 可按需 import {TiledMapLayer},或全量引入。需配合 babel 处理 ES6。
  • 本地文件:从官方下载页或 GitHub Releases 获取完整包,拷贝 dist 下的 iclient-leaflet.min.css 与 iclient-leaflet.js。

浏览器方面,Desktop 支持 Chrome 26+、Firefox 23+、Safari 5+ 等;IE 建议配合较旧 Leaflet 1.0.3 并加 es5-shim。地图容器 div 必须设置明确宽高,否则空白。若服务端跨域,iServer 默认允许任意域,也可配置白名单。发布 REST 地图服务前,可先用桌面端准备数据,详见SuperMap iDesktop 下载与试用许可申请。

版本核对可直接查看GitHub Releases 最新发布记录,当前 12.1.3 对应 SuperMap iClient JavaScript 2026 系列。

初始化地图实例的完整步骤

按下面顺序执行,可复现官方世界地图示例,验收标准是:页面出现可缩放平移的瓦片地图,控制台无 404 或 CRS 报错。

  1. 准备 HTML 容器:写一个 id 为 map 的 div,并用 CSS 设置宽高(如 100% 高度)。
  2. 引入依赖:按上一节加载 Leaflet CSS/JS 与 iclient-leaflet CSS/JS,顺序不能反。
  3. 创建地图实例:调用 L.map(‘map’, { crs: L.CRS.EPSG4326, center: [0, 0], maxZoom: 18, zoom: 1 })。crs 必须与服务一致,常用 EPSG4326 或 EPSG3857。
  4. 添加瓦片图层:定义服务地址(示例常用 https://iserver.supermap.io/iserver/services/map-world/rest/maps/World),执行 new L.supermap.TiledMapLayer(url).addTo(map)。旧写法 L.supermap.tiledMapLayer 已弃用。
  5. 可选增强:设置 transparent、cacheEnabled、format(png/webp)、bufferTiles、tileCache 等,减少空白瓦片。

源码结构与扩展点可参考iClient Leaflet 源码目录。完成以上步骤后,刷新页面应能看到世界地图;缩放级别变化时瓦片正常请求。

GitHub 上 SuperMap iClient for Leaflet 源码目录页面截图
GitHub 上 SuperMap iClient for Leaflet 源码目录页面截图(截图来源:github.com)

坐标系与图层参数怎么选

iClient for Leaflet 不会自动读取服务坐标系(与 Classic 不同),必须手动指定,否则地图错位或空白。默认支持 EPSG:4326、EPSG:3857;其他投影需引入 Proj4js,用 L.supermap.Proj.CRS 自定义,并设置 bounds、origin、scales。

配置项 常见取值 说明
crs L.CRS.EPSG4326 / EPSG3857 / 自定义 Proj.CRS 必须与 iServer 服务投影一致
center / zoom [0,0] / 1 或业务范围中心 初始化视野
transparent true(默认) 背景透明
cacheEnabled true(默认) 启用服务端缓存
format png / webp 瓦片格式,webp 体积更小
bufferTiles / tileCache / overflowTiles 按需开启 减少边缘空白瓦片

第三方底图可用 L.supermap.tiandituTileLayer 等封装。数据坐标本身有问题时,先做转换再发布服务,可参考SuperMap 导入数据乱码与坐标转换参数设置。BIM 模型进 SuperMap 的流程也可对照SuperMap 加载 Revit 插件导出设置,保证发布的服务坐标系干净。

常见出错与验收标准

初始化失败多半出在 CRS、引入顺序或跨域。按下列检查可快速定位。

  • 地图空白:先看控制台是否报 CRS 未定义或瓦片 404;确认 map 的 crs 与服务一致,并检查 div 宽高。
  • 瓦片错位:非默认投影未用 Proj4js.defs 定义,或 origin/scales 写错。
  • 引入失败:CDN 地址过期或 npm 包名仍用旧的 @supermap/iclient-leaflet;确认版本 ≥12.x 且 Leaflet 在 1.0.3~1.9.4 范围。
  • 跨域:浏览器报 CORS,检查 iServer 安全配置或反向代理。

验收标准:页面加载后出现完整瓦片、鼠标滚轮缩放流畅、F12 网络面板可见正常瓦片请求、无红色报错。自定义请求头可用 L.supermap.setRequestHeaders 统一处理鉴权。

常见问题

为什么设置了中心点还是看不到地图?

多数情况是 crs 与服务不匹配,或图层未成功 addTo。先改用官方 World 服务验证,再核对自身服务的投影信息。

npm 安装后找不到 L.supermap?

确认安装的是 @supermapgis/iclient-leaflet,并正确 import;全量引入后 L.supermap 才会挂载。打包时注意 babel 配置。

如何支持非 4326/3857 投影?

引入 Proj4js,用 defs 定义 EPSG 代码,再创建 L.supermap.Proj.CRS 并赋给 map 的 crs 选项,同时设置合理的 bounds 与 scales。

TiledMapLayer 旧写法还能用吗?

L.supermap.tiledMapLayer 已弃用,推荐统一改为 new L.supermap.TiledMapLayer(url)。功能等价,但新写法更符合当前 API。

初始化的关键是“先匹配 CRS,再加载 TiledMapLayer”。建议先用官方 World 服务跑通完整流程,确认环境无误后再替换为自己的 iServer 地址;同时固定 Leaflet 1.9.4 与 iclient-leaflet 12.1.3,减少版本差异带来的问题。