如何使用 SVG 文件写大屏地图

契机

最近公司要做一个政务大屏项目，由于在员工竞优大会上表（jing）现（chui）良（niu）好（b）的我说希望未来能做一个大屏项目，于是这个任务自然交到我头上（需求来得真快），当我拿到图的时候发现地图上有定制化的元素，就是下面图中的三条河流

如果想要使用 GeoJSON 的方式，那就必须知道三条河流的坐标系才行，可是 UI 小姐姐说需求方给的河流就是个图层，她只贴到地图上而已，并没有坐标方面的数据。

我需要根据 SVG 将地图渲染出来。并添加一些额外的元素。

于是便有了这篇文章。

纯当是一次实践记录。

选择正确的地图组件

原先我们的地图则只能使用 GeoJSON 格式来作为底图进行描绘，Echarts 从最新的第 5 版本开始支持地理坐标系（geo）和地图系列（map series）中使用 SVG 作为底图。

地理坐标系（geo）：地理坐标系组件。地理坐标系组件用于地图的绘制，支持在地理坐标系上绘制散点图，线集。
地图系列（map series）：地图，主要用于地理区域数据的可视化，配合 visualMap 组件用于展示不同区域的人口分布密度等数据。

地理坐标系跟地图系列的最大不同可能就是绘制散点图、线集的，这点在官方网站上是有写的

如果要实现点数据或者线数据的可视化，可以使用在地理坐标系组件上的散点图和线图。

当然，我们学习 Echarts 不可能干啃 API，自然需要结合生动的例子，这里就用官方的示例庖丁解牛和散点图来作为两者的区别所在，通过官方的配置项我们可以看到配置是不同的

js
1        series: [{
2            name: 'French Beef Cuts',//庖丁解牛配的是地图系列
3            type: 'map',
4            map: 'Beef_cuts_France',
5            ...
6        }]

js
1        geo: {
2            tooltip: {
3                show: true
4            },
5            map: 'iceland_svg',//散点图配的是地图坐标系
6           ...
7        },

视觉上的不同自然就是散点了，散点长这样

由于我们的项目需要加很多散点，所以我们自然要选择 geo 组件。

具名元素

什么是具名元素呢？就是有名字的 SVG 元素。

如果我们希望跟 SVG 元素做交互，则需要先标记这些元素，标记非常简单，就是给它加一个 name 属性。比如我们拿到 SVG 文件后，可以在 path 上加上名称属性name="named_rect",那么这个 path 就是具名元素。

加了名字的元素跟没有名字的元素有非常大的区别，一旦加上名字，就可以拥有高亮、淡入淡出、文字标注、提示框等交互功能，作为例子，以下放官方给的例子

html
1<svg xmlns="http://www.w3.org/2000/svg" version="1.2" fill-rule="evenodd" xml:space="preserve">
2  <path name="named_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" />
3  <path d="M 150,0 L 150,100 250,100 250,0 Z" fill="#567" />
4</svg>

左边的矩形由于加了 name，就自动拥有 hover 时高亮的效果，而右边的则没有。

而且加了 name 后的具名元素还可以在 Echarts 的 options 中配置geo.regions以做特定的配置效果，这个配置效果会跟我们起的 name 做匹配。

option = {
    geo: {
        map: 'some_svg',
        regions: [{
            name: 'element_name_1',//这里跟 svg 源文件中的 name做匹配
            itemStyle: { ... }
        },
    }
};

注意:

只有这些 SVG 元素可以被命名： rect、circle、line、ellipse、polygon、polyline、path、text、tspan、g。
支持多个元素以相同的名称命名，这样它们能被同时高亮、选中。

实战开始吧！

下面我将使用 slice.svg 作为底图，这个文件是 UI 小姐姐通过 figma 导出来给到我的。

我们的目标是使用此文件配合 Echarts 在浏览器上描绘地图，并做一些简单的交互效果来熟悉 Echarts 的配置项。

给 path 加上具名元素

拿到 SVG 文件后，我们需要使用 Chrome 打开它，使用 vscode 打开后的 SVG 是一串 XML 标签，而 Chrome 打开后会自动解析（就跟解析 HTML 一样），并且渲染出效果来。

每个 SVG 矢量文件本质上是很多定义好的线和形状来创建的图形，里面最常用的可能是 path 路径标签，而且它是最强大的一个，可以通过它创建各种线条、曲线、弧形等等。

我们在浏览器中打开 F12 开发者工具，并且选择小箭头对准渲染出来的图片，就可以看到某块区域的 path

现在已经很清楚了，整块底图都是用大量的 path 进行描绘的，而 path 的形状是通过属性 d 来定义的。

我们不关心 d 属性是怎样写出来的，现在要做的，就是在 SVG 源文件中给对应的 path 加上 name 属性。

html
1<path name="昭通市" d="M480.832 ..."

基本用法

接着我们需要在框架中使用 Echarts 了，这里选用 React 作为 UI 框架，这里是基本结构

react
1import React, { useEffect } from 'react';
2import * as echarts from 'echarts';
3import jQuery from 'jquery';
4window.$ = jQuery;
5
6export const Middle = () => {
7  //创建 map 的函数，在里面写 Echarts 的配置项
8  const createMap = id => {};
9  useEffect(() => {
10    createMap('map');
11  }, []);
12  return <div id='map' />;
13};

接着我们在createMap这个函数中使用 Echarts，这里是 SVG 作为底图的写法

js
1  const createMap = id => {
2    const myChart = echarts.init(document.getElementById(id)!);
3    //$.get()里写你的SVG 文件路径
4    $.get('/slice.svg', function (svg) {
5      //首先向 echarts 注册 SVG 字符串或解析过的 SVG DOM
6      echarts.registerMap('map', { svg: svg });
7      var option = {
8        toolTip: {},
9        //开启地理坐标系组件。地理坐标系组件用于地图的绘制，支持在地理坐标系上绘制散点图，线集。
10        geo: {
11          map: 'map', //这里写注册过的map 名字
12        },
13      };
14      myChart.setOption(option);
15    });
16  };

现在打开浏览看可以查看到效果了，不出意外的话，你可以看到这样的效果

由于我只给一个 path 添加 name，所以只有这一个元素会移动时高亮。

给地图加上文字

上面的效果是 hover 时拥有文字效果，这里有两种方式可以加文字

SVG 源文件中加 text 标签
Echarts 中配置

SVG 源文件中加就比较基础了，需要我们写 xml 标签，比如这样

xml
1<text xml:space="preserve" style="font-size:14px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:rgba(61,215,255,55%);fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" x="128.21919" y="112.48651" id="text3831" transform="matrix(0.99999776,-0.00211681,0.00211681,0.99999776,0,0)">
2<tspan sodipodi:role="line" x="550.59958" y="160.12965" id="tspan38351">
3昭通市</tspan>
4</text>

这是我在 SVG 源文件里面写的，缺点是要找 x 点和 y 点，然后写在对应的 x 属性和 y 属性中。

更简单的方法是直接用 Echarts 的配置项 option.geo 自动加上标注文字。

js
1        geo: {
2          map: 'map', //这里写注册过的map 名字
3          //文字标注的配置
4          label: {
5            show: true,//显示
6            color: 'rgba(61, 215, 255, 0.55)',//颜色
7          },
8        },

我在这里选择的方式是在源文件中写 text 标签，因为需要还原设计稿，统一的配置无法满足我的要求，具体看需求就行。

我加好 name 跟 text 的文件在这： map.svg

高亮强调 emphasis

默认的高亮无法满足我们的要求，所以我们可以通过 emphasis 来配置高亮的效果

js
1        geo: {
2         ...
3          emphasis: {
4            focus: 'none', //高亮时聚焦自己
5            itemStyle: {
6              areaColor: '#2080D7',
7              borderColor: '#2B91B7', //地图区域的颜色。
8              borderWidth: 2,
9              opacity: 1,
10              shadowColor: 'rgba(74, 188, 251, 0.4)',
11              shadowBlur: 3,
12              shadowOffsetX: 3,
13              shadowOffsetY: 3,
14            },
15            label: {
16              show: false, //高亮时文字不要出现
17            },
18          },
19        },

具体配置都是查的官方文档，geo.emphasis

现在的效果是这样的

地域分块 regions 自定义样式

如果想要统一设置样式，可以使用 geo.itemStyle 配置

js
1          //统一样式配置
2          itemStyle: {
3            areaColor: '#1C3079',
4            borderColor: '#2ab8ff',
5          },

如果需要分块定制配置，就需要使用 geo.regions 这个配置项。

js
1            //单独定制的区块设置
2            regions: [
3              {
4                name: '昭通市',
5                itemStyle: {
6                  areaColor: 'rgba(44, 76, 187, 1)',
7                },
8              },
9              {
10                name: '玉溪市',
11                itemStyle: {
12                  areaColor: 'rgba(44, 76, 187, 1)',
13                },
14              },
15              {
16                name: '怒江傈傈族自治州',
17                itemStyle: {
18                  areaColor: 'rgba(44, 76, 187, 1)',
19                },
20              },
21              {
22                name: '迪庆藏族自治区',
23                itemStyle: {
24                  areaColor: 'rgba(44, 76, 187, 1)',
25                },
26              },
27              {
28                name: '楚雄彝族自治州',
29                itemStyle: {
30                  areaColor: 'rgba(16, 34, 84, 1)',
31                },
32              },
33              {
34                name: '红河哈尼族彝族自治州',
35                itemStyle: {
36                  areaColor: 'rgba(16, 34, 84, 1)',
37                },
38              },
39              {
40                name: '丽江市',
41                itemStyle: {
42                  areaColor: 'rgba(16, 34, 84, 1)',
43                },
44              },
45            ],

目前我们分别有 geo.regions.itemStyle、geo.itemStyle、geo.emphasis.itemStyle，他们分别可以定制化地区的样式、全局统一样式和高亮时的样式，API 颗粒度的划分非常精细，只需要到对应的父级配置项查询即可。

layout 布局

如果希望整个地图能够尽量占满我们设定好的 div 的宽高，就需要在 geo 中配置以下内容，以填充 Echarts 容器。

js
1  layoutSize: '100%', //布局尺寸
2  layoutCenter: ['50%', '50%'], //布局位置

series 系列

series 是 Echarts 中最重要的属性，几乎配置任何图表都离不开它，通过 series 的 type 属性，我们可以定制诸如折线 line、柱状图 bar、饼图 pie、散点气泡图 scatter 等等特效效果。

我的项目中需要使用到 series-effectScatter（带有涟漪效果的散点图）和 series-scatter（散点气泡图），具体 API 可以通过option查看，这里我就直接贴代码

js
1const mapData = [
2  {
3    name: '古水水电站1', //数据名称，对应 option.tooltip.formatter
4    value: [190, 215], //坐标
5  },
6  {
7    name: '红色水电站8',
8    value: [366, 260],
9  },
10  {
11    name: '红色水电站9',
12    value: [436, 270],
13  },
14  {
15    name: '红色水电站10',
16    value: [470, 500],
17  },
18  {
19    name: '红色水电站11',
20    value: [520, 310],
21  },
22]

js
1      var option = {
2        //全局开启提示框的样式配置,这里如果配置，有几率下面所有散点图不会出现提示框。
3        tooltip: {
4          show: true,//开启全局提示框
5          formatter: '{b}',//格式化，选择显示数据名称
6          backgroundColor: 'rgba(7, 26, 55, 0.8)',
7          borderColor: '#3DD7FF',
8          borderWidth: 1,
9          padding: [3, 5, 3, 5],
10          textStyle: {
11            color: 'white',
12          },
13        },
14        ...
15        series: [
16          {
17            //带有涟漪特效动画的散点（气泡）图
18            type: 'effectScatter',
19            coordinateSystem: 'geo', //该系列使用的坐标系
20            tooltip: {
21              show: false,//这个系列不要提示框
22            },
23            //涟漪特效相关配置。
24            rippleEffect: {
25              brushType: 'stroke', //波纹的绘制方式 一笔一笔
26              scale: 4,
27            },
28            showEffectOn: 'render', //绘制完成后显示特效 'emphasis' 高亮（hover）的时候显示特效
29            symbol: 'circle', //涟漪特效的标记图形
30            symbolSize: [8, 5], //图形尺寸 宽 高
31            zlevel: 1, //优先级
32            //图形样式
33            itemStyle: {
34              color: 'yellow',
35            },
36            //系列中的数据内容数组。数组项通常为具体的数据项。
37            data: mapData.map(item => item.value),
38          },
39          {
40            //系列类型 散点（气泡）图。
41            type: 'scatter',
42            coordinateSystem: 'geo',
43            tooltip: {
44              show: true,//这个系列要提示框
45            },
46            symbol: 'pin',
47            emphasis: {
48              scale: true,
49            },
50            symbolSize: [30, 33],
51            symbolOffset: [0, -5],
52            zlevel: 20,
53            itemStyle: {
54              color: 'red',
55            },
56            data: mapData,
57          },
58        ],
59      };

这样效果就大概有了

获取坐标轴

上面的 mapData 中的 value，在这个项目中表示坐标轴（具体看 data 的配置，也可以是数据），但是我们并不知道坐标轴是多少，如果挨个试太浪费时间，还好 Echarts 提供给我们 API，我们可以通过监听事件来获取坐标

js
1//获取 svg 底图的坐标
2myChart.getZr().on('click', function (params) {
3  var pixelPoint = [params.offsetX, params.offsetY]
4  var dataPoint = myChart.convertFromPixel({ geoIndex: 0 }, pixelPoint)
5  // 在 SVG 上点击时，坐标会被打印。
6  // 这些坐标可以在 `series.data` 里使用。
7  console.log(dataPoint)
8})

事件

如果要对 SVG 元素进行操作，可以指定事件

js
1// 'name1' 是一个 SVG 元素的名字。
2myChart.on('click', { geoIndex: 0, name: 'name1' }, function (params) {
3  console.log(params)
4})

如果想要对 series 中诸如 type 为 scatter 的散点图绑定点击事件，则可以这样写

js
1myChart.on('click', 'series.scatter', function (params: any) {
2  console.log(params)
3})

每个项目都少不了自适应，如果想要 Echarts 的地图自适应，则需要监听 window 的 resize 事件，然后调用 Echarts 实例的 resize 方法

js
1window.addEventListener('resize', () => {
2  myChart?.resize()
3})

目前我的项目只需要用到这三个事件 API，还有更多定制化的事件，可按需查文档echarts-event

结束语

以上的记录只是项目的一个基本结构，不代表最终项目品质。基于上面的结构，我们已经能够在 SVG 地图上做出非常多样的样式效果和定制服务了。

如果觉得自己配置比较麻烦的话，可以参考这个网站makeapie，找别人写好的案例，copy 一下配置项即可。

最后推广一下本人长期维护的 github 博客

1.从学习到总结，记录前端重要知识点，涉及 Javascript 深入、HTTP 协议、数据结构和算法、浏览器原理、ES6、前端技巧等内容。

2.在 README 中有目录可对应查找相关知识点。

如果对您有帮助，欢迎 star、follow。

地址在这里

enjoy！！