SuperMap iClient for MapLibreGL

主要介绍 SuperMap iClient for MapLibreGL 的入门用法，详细的接口参数请参考 API 页面。

准备

获取 MapLibreGL 和 SuperMap iClient for MapLibreGL

开发时需要引入 MapLibreGL 和 SuperMap iClient for MapLibreGL。其中，MapLibreGL 具体包括 CSS 文件和 JS 文件。你可以通过以下方式获取这些文件：

MapLibreGL

通过 MapLibreGL 官网下载 CSS 文件
通过 MapLibreGL 官网下载 JS 文件

SuperMap iClient for MapLibreGL

通过 SuperMap iClient JavaScript 官网下载最新版本
在 SuperMap iClient for MapLibreGL 的 GitHub 中下载 release 版本

引入

文件方式引入

以下详细介绍如何在线引入 MapLibreGL 文件，以及如何通过在线站点引入 SuperMap iClient for MapLibreGL。

新建一个 HTML 文件，在 <head> 标签中引入 MapLibreGL CSS 文件和 JS 文件，填入 UNPKG 的托管地址，如下：

      <!DOCTYPE html>
     <html>
        <head>
            <meta charset="UTF-8">
            <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet">
            <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
        </head>
     </html>

引入 iclient-maplibregl CSS 文件和 JS 文件，填入 SuperMap iClient for MapLibreGL 在线站点地址：

      <!DOCTYPE html>
      <html>
          <head>
            <meta charset="UTF-8">
            <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet" />
            <link href="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.min.css" rel="stylesheet" />
            <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
            <script type="text/javascript" src="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.js"></script>
          </head>
      </html>

npm 方式引入

使用此方式前请先检查电脑中是否已安装应用程序 Node.js，若未安装，可通过下载安装程序来安装。然后在命令行中输入以下命令安装 SuperMap iClient for MapLibreGL：

 npm install @supermap/iclient-maplibregl

引入 CSS

新建一个 HTML 文件，在 <head> 标签中引入 MapLibreGL CSS 文件和 iclient-maplibregl CSS 文件，如下：

  <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css"/>

<link href="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.min.css" rel="stylesheet" />

模块化开发

ES6

开发前需使用 npm 安装依赖，然后通过 ES6 的 import 模块加载语法引入相应的模块。

按需引入

首先，安装 @supermap/babel-plugin-import：

                              npm install @supermap/babel-plugin-import -D

然后，在.babelrc 中添加如下配置：

                                {
  "plugins": [
    ["@supermap/babel-plugin-import",
      {
      "libraryName": "@supermap/iclient-maplibregl"
      }
    ]
  ]
}

接下来，如果你只希望引入部分组件，比如 QueryByBoundsParameters, QueryService，那么需要写入以下内容：

 import maplibregl from 'maplibre-gl';
import {QueryByBoundsParameters, QueryService} from '@supermap/iclient-maplibregl';

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new QueryByBoundsParameters(...);
  new QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

全模块引入

     import maplibregl from 'maplibre-gl';
import '@supermap/iclient-maplibregl';

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
    var param = new maplibregl.supermap.QueryByBoundsParameters(...);
    new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
        map.addLayer(...);
    });
});

CommonJS

CommonJS 是基于 Node.js 环境的 JavaScript 模块化规范。开发前需使用 npm 安装依赖，然后通过 require 方法引入相应的模块。

部分模块引入

     var maplibregl = require('maplibregl') ;
var QueryByBoundsParameters = require('@supermap/iclient-maplibregl').QueryByBoundsParameters;
var QueryService = require('@supermap/iclient-maplibregl').QueryService;

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new QueryByBoundsParameters(...);
  new QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

全模块引入

     var maplibregl = require('maplibregl') ;
require('@supermap/iclient-maplibregl');

var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
var map = new maplibre.Map({
    container: 'map',
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [0, 0],
    zoom: 2
});

map.on('load', function () {
  var param = new maplibregl.supermap.QueryByBoundsParameters(...);
  new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
      map.addLayer(...);
  });
});

AMD

以下例子利用 RequireJS 库实现，将 maplibre-gl.js 和 iclient-maplibregl.js 通过 “ 获取 MapLibreGL 和 SuperMap iClient for MapLibreGL ” 下载后放在与 RequireJS 指定的入口主文件所在目录下。

全模块引入

                            require(['js/maplibre-gl.js'], function(maplibregl) {
    window.maplibregl = maplibregl;
    require(['js/iclient-maplibregl'], function() {
      var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
      var map = new maplibre.Map({
          container: 'map',
          style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
          center: [0, 0],
          zoom: 2
      });

      map.on('load', function() {
        var param = new maplibregl.supermap.QueryByBoundsParameters(...);
        new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
            map.addLayer(...);
        });
      });
    });
});

CMD

以下例子利用 SeaJS 库实现，将 maplibre-gl.js 和 iclient-maplibregl.js 通过 “ 获取 MapLibreGL 和 SuperMap iClient for MapLibreGL ” 下载后放在与 SeaJS 指定的入口主文件所在目录下。

全模块引入

                                                define(function(require, exports, module) {
    require('./maplibre-gl.js');
    require('./iclient-maplibregl.js');

    var url = "https://iserver.supermap.io/iserver/services/map-world/rest/maps/World";
    var map = new maplibre.Map({
        container: 'map',
        style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
        center: [0, 0],
        zoom: 2
    });

    map.on('load', function() {
      var param = new maplibregl.supermap.QueryByBoundsParameters(...);
      new maplibregl.supermap.QueryService(url).queryByBounds(param, function (serviceResult) {
          map.addLayer(...);
      });
    });
});

打包配置

SuperMap iClient for MapLibreGL 使用了 ES6 语法，为了兼容不支持 ES6 语法的浏览器，需要在打包的过程中进行一些配置，包括语法转换的处理。

这里的打包配置是针对于 ES6 和 CommonJS 模块开发，对于 AMD 和 CMD 模块开发的项目，不需要利用打包工具。

这里以 webpack4 为例，由于使用不同的包管理器会导致安装包的结构有所不同，所以下面分别介绍了 npm 和 cnpm 两种配置方式：

若您用 npm install 或者 cnpm install --by=npm 安装的依赖，那么您需要在 webpack.config.js 的配置文件的 module 中加入如下配置项：

 module: {
    rules: [{
    // 使用babel-loader将ES6语法转换为ES5
        test: /\.js$/,
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env']
        }
    }]
}

若您用 cnpm install 安装的依赖，那么您需要在 webpack.config.js 的配置文件的 module 中加入如下配置项：

                                                module: {
        rules: [{
            // 使用babel-loader将ES6语法转换为ES5
            test: /\.js$/,
            loader: 'babel-loader',
            options: {
              presets: ['@babel/preset-env']
            }
        }]
    }

创建一幅地图

SuperMap iServer 发布的地图

在准备章节，已经新建了一个 HTML 页面，在页面<body>标签中添加代码以创建地图，如下：

                         <!DOCTYPE HTML>
<html>
    <head>
        <meta charset="UTF-8">
        <link href="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.css" rel="stylesheet">
        <script type="text/javascript" src="https://unpkg.com/maplibre-gl@2.4.0/dist/maplibre-gl.js"></script>
        <script type="text/javascript" src="https://iclient.supermap.io/dist/maplibregl/iclient-maplibregl.js"></script>
    </head>
    <body>
        // 地图显示的div
        <div id="map" style="position:absolute;left:0px;right:0px;width:800px;height:500px;"></div>
    </body>
</html>

以嵌入 SuperMap iServer 发布的中国地图为例，在 <script> 中继续添加如下代码，初始化地图信息：

  var map = new maplibregl.Map({
    container: 'map',
    style: {
        "version": 8,
        "sources": {
            "raster-tiles": {
                "attribution": attribution,
                "type": "raster",
                "tiles": ['https://iserver.supermap.io/iserver/services/map-china400/rest/maps/China/zxyTileImage.png?z={z}&x={x}&y={y}'],
                "tileSize": 256
            }
        },
        "layers": [{
            "id": "simple-tiles",
            "type": "raster",
            "source": "raster-tiles",
            "minzoom": 0,
            "maxzoom": 22
        }]
    },
    center: [120.143, 30.236], // starting position
    zoom: 3 // starting zoom
});查看源码 »

运行效果

添加控件

通过向地图添加控件的方式，实现对图层的放大，缩小，全屏等交互操作，常用的控件包括：

控件	类名	简介
导航	maplibregl.NavigationControl	默认位于地图左上角
比例尺	maplibregl.ScaleControl	默认位于地图左下角
全屏	maplibregl.FullscreenControl	默认位于地图右上角
定位	maplibregl.GeolocateControl	默认位于地图右上角
版权	maplibregl.AttributionControl	默认位于右下角

添加控件时，首先初始化地图，然后通过 addControl() 方法将控件添加到地图上，例如：

导航控件：

 // 添加控件
map.addControl(new maplibregl.NavigationControl(), 'top-left');查看源码 »

运行效果

比例尺控件：

 map.addControl(new maplibregl.ScaleControl({}));查看源码 »

运行效果

使用矢量瓦片

矢量瓦片是将矢量数据通过不同的描述文件来组织和定义，在客户端实时解析数据并完成绘制。使用 SuperMap iServer 提供的矢量瓦片示例如下：

 var map = new maplibregl.Map({
    container: 'map', // container id
    style: 'https://iserver.supermap.io/iserver/services/map-mvt-China/rest/maps/China/tileFeature/vectorstyles.json?type=MapBox_GL&styleonly=true',
    center: [120.143, 30.236], // starting position
    zoom: 0,
    attributionControl: false
});
         查看源码 »

运行效果