SuperMap iClient for Leaflet 安装与引入方法
SuperMap iClient for Leaflet 的安装与引入主要通过文件方式(本地下载或 CDN)和 npm 模块化两种途径完成。截至 2026 年 11 月,推荐使用最新包 @supermapgis/iclient-leaflet(版本 12.1.3),并搭配 Leaflet v1.0.3 至 v1.9.4。引入时必须同时加载对应的 CSS 文件,之后即可通过 L.supermap 命名空间叠加瓦片图层等功能。项目是否使用构建工具决定了优先选择哪种方式。

安装前需要准备哪些依赖与环境
动手前先确认基础依赖,否则后续引入会报错。核心是 Leaflet 本身,iClient 只是其扩展库。npm 方式还需 Node.js 环境。浏览器兼容范围较广,但部分高级功能对 IE 有更高要求。
| 项目 | 要求说明 |
|---|---|
| Leaflet 版本 | 必须兼容 v1.0.3 ~ v1.9.4,文档示例常用 1.9.4 |
| npm 包名 | v11.2.0 起为 @supermapgis/iclient-leaflet;更早版本用 @supermap/iclient-leaflet |
| 桌面浏览器 | Chrome 26+、Firefox 23+、IE 7+、Opera 12+、Safari 5+ 等 |
| 移动浏览器 | Chrome Mobile 47+、iOS Safari 7+、Android 2.2+ 等 |
| 许可 | Apache License 2.0 |
若项目同时涉及桌面端数据发布或服务准备,可先查阅SuperMap iDesktop怎么下?试用许可如何申请?。加载服务数据时若出现乱码或坐标问题,也建议同步参考SuperMap导入数据乱码?坐标转换参数怎么设?。
文件方式(本地或 CDN)如何引入
适合快速验证或无构建工具的纯静态页面。完整包含 SDK 与示例,精简包仅 SDK。
- 前往 GitHub Releases 下载页面 获取最新 12.1.x 完整包、精简包或历史版本,也可从 Gitee 镜像获取源码后自行构建。
- 解压后,在 HTML 中按顺序引入 Leaflet 的 CSS 与 JS,再引入 iclient-leaflet 的 CSS(如 iclient-leaflet.min.css)与 JS(iclient-leaflet.js)。也可直接使用公共 CDN 加载这些文件,免去本地存放。
- 页面中创建 L.map 实例(常显式指定 crs 为 L.CRS.EPSG4326),然后用 new L.supermap.TiledMapLayer(服务地址).addTo(map) 验证引入是否成功。

验收标准:浏览器控制台无 404 或未定义错误,地图能正常显示底图并叠加 SuperMap 图层。早期 9.x 文件名曾为 iclient9-leaflet.js,现已统一为 iclient-leaflet.js,旧代码需同步更新。
npm 安装与模块化引入步骤
推荐用于正式项目,便于版本管理与按需打包。先确保已安装 Node.js。
- 执行 npm install @supermapgis/iclient-leaflet。若需兼容 v11.1.1 及更早版本,改用旧包名 @supermap/iclient-leaflet。
- 在入口文件或样式中引入 CSS(可从 node_modules 复制或继续用 CDN)。
- 全量引入:import ‘@supermapgis/iclient-leaflet’; 之后使用 new L.supermap.TiledMapLayer(url).addTo(map)。CommonJS 则用 require 对应写法。
- 按需引入(推荐,体积可大幅减小):先安装 @supermapgis/babel-plugin-import,配置 .babelrc,再写 import { TiledMapLayer } from ‘@supermapgis/iclient-leaflet’; 直接 new TiledMapLayer(url)。注意旧写法 import { SuperMap } 已逐步弃用。
AMD(RequireJS)或 CMD(SeaJS)场景下,直接全量引用本地下载的 JS 文件即可,无需额外打包工具。涉及 BIM 或 Revit 模型导出到 SuperMap 时,插件参数设置可参考SuperMap加载Revit?插件导出怎么设置?。
打包配置、兼容性与体积优化注意点
ES6/CommonJS 项目需用 babel-loader 将语法转成 ES5,webpack 中 presets 设为 [‘@babel/preset-env’]。AMD/CMD 无需此步。
- IE8 兼容:Leaflet 建议锁定 1.0.3(更高版本支持不完整)。在 leaflet 脚本前用条件注释引入 es5-shim.js 与 es5-sham.js。
- 体积优化:全量引入较大,务必配合 babel-plugin-import 做按需加载,官方实测最高可减小约 90%。
- 包名变更与历史:自 11i(2024)v11.2.0 起包名调整,变更细节见 CHANGELOG 变更记录。新版本还增加了 bufferTiles、setRequestHeaders 等参数缓解瓦片空白与跨域问题。
- 其他:部分可视化扩展(ECharts、MapV、Turf)对 IE 版本要求更高,按需单独引入三方库。
配置完成后,以“地图正常初始化 + 图层无报错叠加”作为基本验收标准。
常见问题
npm 安装提示找不到包名怎么办?
检查是否误用了旧包名。v11.2.0 及以后必须用 @supermapgis/iclient-leaflet,更早版本才用 @supermap/iclient-leaflet,否则安装会失败。
页面在 IE8 下报错或空白怎么处理?
改用 Leaflet 1.0.3,并在 leaflet 脚本前通过条件注释加载 es5-shim.js 与 es5-sham.js。同时确认 iClient CSS 也已引入。
打包后体积过大如何缩小?
安装并配置 @supermapgis/babel-plugin-import,改为按需 import 具体类(如 TiledMapLayer),避免全量引入,体积通常可减少约 90%。
引入后提示 L.supermap 未定义?
确认已执行全量 import 或正确按需导入,并且 CSS 文件同步加载。刷新缓存后重试,检查控制台是否有路径 404。
文件方式适合快速原型验证,npm 模块化更利于长期维护与体积控制。建议先完成一个最简地图加载作为验收,再逐步叠加业务图层;版本更新请以 GitHub Releases 为准,并同步查看 CHANGELOG 中的破坏性变更。