栅格层

栅格（Raster）层由栅格图片组成，栅格图片是像素点的网格。栅格层通常用作地图的背景层。栅格图片可以从不同的供应商下载：瓦片服务或者 WMS 服务提供商。

该扩展组件支持下列类型的栅格层：

瓦片层

TileLayer 用来加载并展示地图瓦片，瓦片由 Web 服务通过类似 http://…​/{z}/{x}/{y}.png 的 URL 提供。例如， OpenStreetMap 提供的瓦片 URL 格式为：https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png。

在 XML 中以声明式的方式添加瓦片层：

<maps:layers>
    <maps:tile id="tileLayer"
               urlPattern="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
               attribution="&#169; &lt;a href=&quot;https://www.openstreetmap.org/copyright&quot;&gt;
                   OpenStreetMap&lt;/a&gt; contributors"/>
</maps:layers>

如果未设置 tileProvider 则必需设置 id 和 urlPattern。

大多数瓦片服务商都要求列出所有权，可以在 attribution 参数设置。我们的示例中，在右下角展示 ©OpenStreetMap 贡献者。

在 subDomains 参数，可以指定逗号分隔的值，用于替换 urlPattern 中 {s} 占位符所代表的值。默认值为 "a,b,c"，这是大多数瓦片服务（包括 OpenStreetMap）使用的子域名。

扩展组件自带 OpenStreetMap，因此可以这样使用：

<maps:tile id="tileLayer" tileProvider="map_OpenStreetMap"/>

另外，在界面控制器可以使用 io.jmix.mapsui.component.layer.TileLayer 类处理瓦片层。

@Autowired
private GeoMap map;

@Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    TileLayer tileLayer = new TileLayer("tileLayer");
    tileLayer.setUrl("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png");
    tileLayer.setAttributionString("&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors");
    map.addLayer(tileLayer);
}

创建提供瓦片的 bean

将 URL 和属性字符串写在 XML 中很容易混淆，因此，可以创建 Spring bean 并使用 tileProvider 属性：

  1. 将瓦片服务商的设置移至实现了 io.jmix.mapsui.component.layer.TileProvider 接口的 bean 内：

    @Component(CartoTileProvider.NAME)
public class CartoTileProvider implements TileProvider {
    public static final String NAME = "sample_CartoTileProvider";

    private static final String URL_PATTERN = "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png";
    private static final String ATTRIBUTION = "&copy; <a href=\"http://www.openstreetmap.org/copyright\">OpenStreetMap</a> &copy;" +
            " <a href=\"https://carto.com/attributions\">CARTO</a>";

    @Override
    public String getUrlPattern() {
        return URL_PATTERN;
    }

    @Override
    public String getAttributionString() {
        return ATTRIBUTION;
    }
}

  2. 在 tile 元素中，指定 tileProvider 属性为 bean 的名称。

    <maps:tile id="tileLayer" tileProvider="sample_CartoTileProvider"/>

WMS 层

WMSTileLayer 支持使用各种 WMS 服务 作为地图提供商，在 XML 中声明：

<maps:layers>
    <maps:wms id="wmsLayer"
              url="http://ows.terrestris.de/osm/service?"
              layers="OSM-WMS"
              format="image/png"/>
</maps:layers>

id、url 和 layers 是必需参数，其余参数有默认值，但也可以重新定义。

另外，在界面控制器可以使用 io.jmix.mapsui.component.layer.WMSTileLayer 类处理 WMS 层：

@Autowired
private GeoMap map;

@Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    WMSTileLayer wmsTileLayer = new WMSTileLayer("wmsLayer");
    wmsTileLayer.setUrl("http://ows.terrestris.de/osm/service?");
    wmsTileLayer.setLayers("OSM-WMS");
    wmsTileLayer.setFormat("image/png");
    map.addLayer(wmsTileLayer);
}

图片层

ImageLayer 用于在地图的特定边界范围展示图片。在 XML 中声明：

<maps:layers>
    <maps:image id="imageLayer"
                image="url:https://legacy.lib.utexas.edu/maps/historical/newark_nj_1922.jpg"
                opacity="0.5"
                topLeftX="-116.982422"
                topLeftY="48.899394"
                bottomRightX="-104.326172"
                bottomRightY="42.656586"/>
</maps:layers>

  • image 参数设置图片路径。路径必须以下列前缀开头，用于定义图片源：

    • url: — 图片从给定的 URL 加载。

    • file: — 图片由文件系统提供。

      image="file:D:/myImage.png"

    • classpath: — 图片在 classpath 中，例如，com/company/demo/web/myImage.png：

      image="classpath:/com/company/demo/web/myImage.png"

    • theme: — 图片位于当前主题的目录中，例如，web/themes/hover/awesomeFolder/myImage.png：

      image="theme:awesomeFolder/myImage.png"

    也可以使用 geoImageDelegate 编程式加载图片：

    @Install(to = "map.imageLayer", subject = "geoImageDelegate")
private GeoImage mapImageLayerGeoImageDelegate(ImageLayer imageLayer) {
    String url = "https://legacy.lib.utexas.edu/maps/historical/newark_nj_1922.jpg";
    return GeoImage.fromUrl(url);
}

  • topLeft 参数定义图片的西北点位置。

  • bottomRight 定义图片的东南点位置。

如果在 ImageLayer 中使用 SVG 图片，确保 SVG 文档中包含 width/height 或 viewBox 属性，以便支持 SVG 图片在地图中能正确地进行缩放。