SuperMap iClient for Leaflet 安装与引入方法

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

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

SuperMap iClient for Leaflet 典型地图效果示意

安装前需要准备哪些依赖与环境

动手前先确认基础依赖,否则后续引入会报错。核心是 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。

  1. 前往 GitHub Releases 下载页面 获取最新 12.1.x 完整包、精简包或历史版本,也可从 Gitee 镜像获取源码后自行构建。
  2. 解压后,在 HTML 中按顺序引入 Leaflet 的 CSS 与 JS,再引入 iclient-leaflet 的 CSS(如 iclient-leaflet.min.css)与 JS(iclient-leaflet.js)。也可直接使用公共 CDN 加载这些文件,免去本地存放。
  3. 页面中创建 L.map 实例(常显式指定 crs 为 L.CRS.EPSG4326),然后用 new L.supermap.TiledMapLayer(服务地址).addTo(map) 验证引入是否成功。
GitHub Releases 页面可直接下载各版本 SuperMap iClient 包
GitHub Releases 页面可直接下载各版本 SuperMap iClient 包(截图来源:github.com)

验收标准:浏览器控制台无 404 或未定义错误,地图能正常显示底图并叠加 SuperMap 图层。早期 9.x 文件名曾为 iclient9-leaflet.js,现已统一为 iclient-leaflet.js,旧代码需同步更新。

npm 安装与模块化引入步骤

推荐用于正式项目,便于版本管理与按需打包。先确保已安装 Node.js。

  1. 执行 npm install @supermapgis/iclient-leaflet。若需兼容 v11.1.1 及更早版本,改用旧包名 @supermap/iclient-leaflet。
  2. 在入口文件或样式中引入 CSS(可从 node_modules 复制或继续用 CDN)。
  3. 全量引入:import ‘@supermapgis/iclient-leaflet’; 之后使用 new L.supermap.TiledMapLayer(url).addTo(map)。CommonJS 则用 require 对应写法。
  4. 按需引入(推荐,体积可大幅减小):先安装 @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 中的破坏性变更。