SuperMap iClient for Leaflet 初始化地图实例
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。坐标系必须手动匹配服务,否则容易不出图或错位。

如何引入库与环境准备
要解决的问题是:页面能正确加载 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 报错。
- 准备 HTML 容器:写一个 id 为 map 的 div,并用 CSS 设置宽高(如 100% 高度)。
- 引入依赖:按上一节加载 Leaflet CSS/JS 与 iclient-leaflet CSS/JS,顺序不能反。
- 创建地图实例:调用 L.map(‘map’, { crs: L.CRS.EPSG4326, center: [0, 0], maxZoom: 18, zoom: 1 })。crs 必须与服务一致,常用 EPSG4326 或 EPSG3857。
- 添加瓦片图层:定义服务地址(示例常用 https://iserver.supermap.io/iserver/services/map-world/rest/maps/World),执行 new L.supermap.TiledMapLayer(url).addTo(map)。旧写法 L.supermap.tiledMapLayer 已弃用。
- 可选增强:设置 transparent、cacheEnabled、format(png/webp)、bufferTiles、tileCache 等,减少空白瓦片。
源码结构与扩展点可参考iClient Leaflet 源码目录。完成以上步骤后,刷新页面应能看到世界地图;缩放级别变化时瓦片正常请求。

坐标系与图层参数怎么选
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,减少版本差异带来的问题。