如何使用Esri JS API 4.x加载GeoServer指定WMS图层？

背景 #

此前使用Esri JS API 3.x可正常加载GeoServer的WMS图层，代码如下：

require(["esri/layers/WMSLayer","esri/layers/WMSLayerInfo"],function(WMSLayer,WMSLayerInfo){
    var wmsinfo = new WMSLayerInfo();

    var resourceInfo = {
        extent: Map.extent,
        layerInfos: [wmsinfo],
        spatialReference: {
          wkid: 4326
        }
    };
    var name = "HTM:name_of_layer_on_geoserver.tif";
    var url = "www.geoserver.local:8080/geoserver/HTM/wms?";
    layer = new WMSLayer(url, {
        id: "tempid",
        
        spatialReference: new SpatialReference({ wkid: 3857 }),
        resourceInfo: resourceInfo,
        visibleLayers: name,
        customLayerParameters: {CRS: 'EPSG:3857'}
    });

    Map.addLayer(layer);
});

4.x代码转换尝试 #

升级到4.x后，尝试转换代码但遇到问题，当前代码如下：

require(["esri/layers/WMSLayer"],function(WMSLayer){
    //var wmsinfo = new WMSLayerInfo(); //<-this is deprecated, what would be the equivalent.

    var resourceInfo = {
        extent: View.extent,
        layerInfos: [],
        spatialReference: {
          wkid: 4326
        }
    };
    var name = "HTM:name_of_layer_on_geoserver.tif";
    var url = "www.geoserver.local:8080/geoserver/HTM/wms?";
    //moved url to properties, instead of inline argument 
    layer = new WMSLayer({
        id: "tempid",
        url:url,
        spatialReference: new SpatialReference({ wkid: 3857 }),
        resourceInfo: resourceInfo, //this doesnt seem to be available
        visibleLayers: name,   
        customLayerParameters: {CRS: 'EPSG:3857'}
    });
        layer.load().then(()=>{
      Map.addLayer(layer);
        });
});

遇到的问题 #

• 3.x中的WMSLayerInfo类已废弃，找不到替代方案
• 尝试将visibleLayers替换为sublayer无效
• 直接添加图层到Map出现白屏，调用load()则卡在GetCapabilities请求
• 缺少仅加载单个WMS图层而非服务器全部图层的参考示例

解决方案及正确代码示例 #

关键调整点 #

1. 移除废弃的resourceInfo配置：4.x的WMSLayer会自动通过GetCapabilities获取服务元数据，无需手动配置
2. 修正URL格式：确保URL包含协议（http:///https://），且末尾不需要加?
3. 保留visibleLayers指定单个图层：4.x依然支持该属性，值可以是单个字符串或图层名称数组
4. 无需手动调用load()：添加图层到地图后会自动触发加载流程
5. 移除手动指定的spatialReference：图层会自动适配地图的空间参考

正确代码 #

require(["esri/layers/WMSLayer", "esri/Map", "esri/views/MapView"], function(WMSLayer, Map, MapView) {
  // 初始化地图和视图
  const map = new Map({
    basemap: "gray-vector"
  });

  const view = new MapView({
    container: "viewDiv",
    map: map,
    center: [116, 39], // 替换为你的地图中心坐标
    zoom: 10
  });

  // 配置WMS图层参数
  const layerName = "HTM:name_of_layer_on_geoserver.tif";
  const wmsUrl = "http://www.geoserver.local:8080/geoserver/HTM/wms";

  const wmsLayer = new WMSLayer({
    id: "tempid",
    url: wmsUrl,
    visibleLayers: [layerName], // 单个图层用数组或直接传字符串均可
    customLayerParameters: {
      CRS: "EPSG:3857"
    }
  });

  // 直接添加到地图即可自动加载
  map.add(wmsLayer);
});

额外排查点 #

如果仍出现GetCapabilities请求卡住的情况，检查以下内容：

• GeoServer服务是否可正常访问，确认URL的协议、域名、端口无误
• 浏览器跨域问题：GeoServer是否配置了CORS，或是否需要使用代理服务
• 图层名称是否完全匹配：需和GeoServer中发布的图层名称一致，包括工作空间前缀

内容的提问来源于stack exchange，提问作者Angelo