OpenLayers 与 Leaflet 加载超图（SuperMap iServer）REST 地图图层——原理 + 完整实现

摘要本文详解 SuperMap iServer REST 地图服务的加载原理并分别给出OpenLayers配合 iClient for OpenLayers​ 和Leaflet配合 iClient for Leaflet​ 的完整可运行示例附带坐标系匹配、跨域等常见坑位说明。一、SuperMap iServer REST 地图服务简述SuperMap iServer 发布地图后会生成一个 REST 风格的服务地址格式通常为http://ip:8090/iserver/services/地图服务名/rest/maps/地图名称例如超图官方示例https://iserver.supermap.io/iserver/services/map-world/rest/maps/World该接口支持返回地图元信息JSON以及按缩放级别请求栅格瓦片ugcImage / tileImage。前端 GIS 库OpenLayers / Leaflet并不直接原生理解 SuperMap REST 瓦片组织方式推荐使用超图官方封装的 iClient 扩展包iClient for OpenLayers / iClient for Leaflet它们内部完成了请求地图元信息获取 bounds、resolutions、tileSize按 SuperMap REST 瓦片 URL 模板拼装请求坐标系EPSG:4326 / EPSG:3857 / EPSG:4490适配与重投影二、OpenLayers 加载 SuperMap iServer REST 图层2.1 引入资源!-- OpenLayers -- link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/olv7.4.0/ol.css / script srchttps://cdn.jsdelivr.net/npm/olv7.4.0/dist/ol.js/script !-- SuperMap iClient for OpenLayers -- script srchttps://iclient.supermap.io/dist/ol/iclient-ol.min.js/script 若使用 Vue / React可通过npm install supermap/iclient-openlayers引入TileSuperMapRest。2.2 完整示例代码EPSG:4326div idmap stylewidth:100%;height:500px/div script var url https://iserver.supermap.io/iserver/services/map-world/rest/maps/World; var map new ol.Map({ target: map, view: new ol.View({ center: [0, 0], zoom: 2, projection: EPSG:4326 }) }); var layer new ol.layer.Tile({ source: new ol.source.TileSuperMapRest({ url: url, wrapX: true }), projection: EPSG:4326 }); map.addLayer(layer); /script2.3 EPSG:3857 场景常见 Web 墨卡托var layer new ol.layer.Tile({ source: new ol.source.TileSuperMapRest({ url: https://iserver.supermap.io/iserver/services/map-china400/rest/maps/China, wrapX: true }) }); var map new ol.Map({ target: map, layers: [layer], view: new ol.View({ center: ol.proj.fromLonLat([116.4, 39.9]), zoom: 5, projection: EPSG:3857 }) });⚠️ 若服务本身是 EPSG:4326 而 View 用 EPSG:3857OpenLayers 会自动做 raster reprojection但建议服务投影与 View 投影一致以获得最佳性能和清晰度。三、Leaflet 加载 SuperMap iServer REST 图层3.1 引入资源link relstylesheet hrefhttps://unpkg.com/leaflet1.9.4/dist/leaflet.css / script srchttps://unpkg.com/leaflet1.9.4/dist/leaflet.js/script !-- SuperMap iClient for Leaflet -- script srchttps://iclient.supermap.io/dist/leaflet/iclient-leaflet.min.js/scriptnpm 方式npm install supermap/iclient-leaflet然后import { tiledMapLayer } from supermap/iclient-leaflet。3.2 完整示例代码EPSG:4326div idmap stylewidth:100%;height:500px/div script var url https://iserver.supermap.io/iserver/services/map-world/rest/maps/World; var map L.map(map, { crs: L.CRS.EPSG4326, center: [0, 0], zoom: 1, maxZoom: 18 }); L.supermap.tiledMapLayer(url, { noWrap: false // 允许横向循环 }).addTo(map); /script3.3 说明L.CRS.EPSG4326Leaflet 默认是EPSG:3857加载超图 4326 服务必须显式指定 CRS否则瓦片位置偏移。noWrap: false全球数据建议开启横向平铺。四、关键原理解析要点说明REST 瓦片请求​iClient 先 GET 地图元信息 JSON → 解析bounds、resolutions、tileWidth/Height→ 按 SuperMap REST 瓦片 URL/maps/xxx/image.png?...xyscale请求栅格坐标系适配​源投影取自服务元信息View/Map 投影由前端指定OpenLayers 可做自动 reprojectLeaflet 需手动配crswrapX​全球经纬度服务建议wrapX:trueOL或noWrap:falseLeaflet防止边缘缺失跨域(CORS)​iServer 需在「服务管理器 → 允许跨域」开启否则浏览器拦截瓦片请求分辨率数组​若用原生 OLTileImage/XYZ加载不推荐必须手工填入 iServer 的 resolution 数组否则缩放级别错位五、常见问题排查地图空白 / 404检查 REST URL 是否以/rest/maps/地图名结尾不要少级或多加后缀。瓦片模糊或层级不对EPSG:4326 服务被放到 EPSG:3857 View 中触发重投影或 resolution 数组不匹配。CORS 报错iServer → 服务属性 → 跨域设置 → 允许 Origin*开发环境。Leaflet 偏移忘记设crs: L.CRS.EPSG4326。六、小结✅推荐做法使用supermap/iclient-openlayers的TileSuperMapRest和supermap/iclient-leaflet的tiledMapLayer省去手动拼瓦片模板和 resolution。✅ 注意坐标系一致Leaflet 必须显式声明 CRS。✅ iServer 开启 CORS保证瓦片正常拉取。如有 iServer WMTS / 矢量瓦片(MVT) / 动态图层(UTFGrid) 加载需求可在评论区交流