Vue3 + TypeScript —— echarts中国地图绘制、散点、涟漪特效

业务需求，大屏中需要有一幅中国地图，展示地区的点，某些地区突出需要用到涟漪特效或普通散点。全文会有点啰嗦，但也是我对开发过程的感受作一个总结，希望大家也能有所收获。

一、地图准备

第一个疑问就是 地图从何而来?

我们都知道 echarts 是一个强大的图表库，能满足绝大部分的图表开发需求。绘制中国地图，无例外第一反应就是找echarts。
当前时间是 2023年11月1日，echarts版本最新版本为v5.4.3，但早在v5.0.0版本，echarts官方已经将里面绘制地图的json文件移除了，各位可以翻翻echarts的 echarts-v5.0.0 版本记录，见下图⬇。

也就是说，在v5.0.0以上的版本，已经是找不到原有的map文件夹，也无法使用到内置的地图了。于是在网上搜罗了许多文章，就发现不少文章介绍使用以往版本的内置地图，譬如v4.9.0，没经验的我也是照做。简单做了个架子，项目大哥就来看看我的开发进度，一过来就问道这副地图是怎么来的？我说是新版本echarts内置地图被移除了，用到旧版本地图。大哥立马就解释到，旧版本地图可能还是 九分线，现在国家官方的地图已经是 十分线了。我满脸疑惑，相信各位也是如此，看下图就明白了⬇。
左侧是echarts旧版本已经废除的内置地图，右侧是当前使用的地图（怎么来，后面说）。

哇去，第十分线已经是将祖国的台湾囊括进来。头一回写代码使命感十足，我也是赶紧问问大哥解决方案，不敢怠慢。大哥说地图绘制最重要的是一份json文件，也是在echarts旧版内置地图文件夹中的某个js文件可以看到一行类似这样的代码 ⬇。

echarts.registerMap( 引入的json文件 )

那么就是要找到较新版本的地图的JSON文件下载下来，在页面使用相同的注册方式即可。中国地图JSON文件下载地址

二、初始化echarts实例

相信能使用到echarts去绘制地图等相对复杂的图表的各位，都清楚这一步需要做什么，不作太详细的赘述，只给出相对重要的代码片段。

// 下载新版本的echarts后，页面中引入
import * as echarts from 'echarts';
// 刚刚下载到的json，在项目中找个地方放，在此引入
import chinaJson from '？？？/xxx.json';


// 此步是为了确定ts类型，直接用引入的参数名也可以，就是下面会报ts错误有红线很难受，还是我功夫不到位
const chinaMapJson: any = chinaJson;
// 使用新下载的JSON文件注册地图，第一个参数为地图注册名（重要），第二个参数JSON文件（重要）
echarts.registerMap('china-map', chinaMapJson);


// 用于获取ref、块节点的DOM
const chinaMap = ref<HTMLDivElement | null>(null);
// 用于接收图表的初始化实例
const chartInstance = shallowRef<echarts.ECharts>();


// 实例初始化
chartInstance.value = echarts.init(chinaMap.value);
// 配置项设置
chartInstance.value.setOption(option);

三、配置项

配置项option也是图表绘制十分重要的一环，配置项往往决定了一个图表的外观，以及能完成的业务需求。

当你完成上述步骤，可option还是空空如也的时候，你会发现，你心心念念的中国地图仍未出现，这是因为你还没有告诉echarts你想画什么。
这里先聊聊对于地图绘制来说十分重要的两个配置项 geo 和 图层 series下的map。

geo

geo: {
  id: 'chinaMap',
  map: 'china-map',  // 绘制的地图注册名
  show: true, // 是否显示
  zoom: 1.2, // 地图缩放比例
  roam: false, // 地图拖动、缩放
  // 文本标签，地区名, 控制样式，位置等等
  label: {
    fontSize: 10,
  },
  // 地区区域多边形，每个地区的小块，控制样式等等 #3383c8
  itemStyle: {
    areaColor: '#457b9d',
    borderColor: '#a0d4e7',
    borderWidth: 1,
  },
  // 高亮状态下的多边形和文本样式，鼠标悬浮在地图块上的效果
  emphasis: {
    itemStyle: {
      areaColor: '#002a4f',
      borderColor: '#4aacd9',
    },
  },
},

坐标系组件十分重要，在你后续加入图层去描述散点、描述涟漪特效位置时起到置关重要的作用。在你配置项option加入geo的相关配置，中国地图就已经可以呈现出来了。

图层 series下的map类型

既然中国地图已经呈现，也能满足散点、涟漪位置的描述需求，为什么还要介绍map类型的图层呢？先给出他们的关系。

const option: echarts.EChartsOption = {
	geo：{
	
	}，
	series：[
		{
			type: map,
		}
	]
}

可以试想一下，这样的业务场景 ➡ 点击地图中的某个地区，取得什么信息发出请求或展示什么内容。
仔细比较可以发现，geo·中并没有像图层map中的data字段，去描述较复杂的自定义数据，可见下面代码及图⬇。

// 图层类型map 的 data 自定义数据格式
const data = {
	name: '', // 地区名
	value: [] // 经纬度数组
	// 其他自定义字段
	??： ??，
	??： ??
}

// 地图点击事件监听
chartInstance.value.on('click', (params) => {
	console.log(params)
}

左图为点击geo坐标系情况下，触发回调的回调输出结果。
右图为点击map图层情况下，触发回调的回调输出结果.

很明显map图层能使用自定义字段，更灵活，满足更多业务需求。配置项option中单独放一个map图层，同样可以做到绘制地图。
这么说来那geo还有用吗？？那可以太有用了，图层的任务重点在于展示，geo的任务重点在于描述经纬坐标点，没有geo坐标系组件，你在图层中放多少个散点、涟漪都无济于事，不会在地图中呈现出来。geo和图层map同时存在时，只需要保持缩放比例zoom一致，将geo的show设为false即可。

四、散点、涟漪特效

散点、涟漪特效其实没什么好说的，就是图层series中的一种类型。就是没使用过，看配置项文档要一个个翻很麻烦。
echarts官方散点配置

{
  type: 'scatter',
  name: 'xxx',
  data: [], // 数据格式与图层map一致，需包含name，value
  coordinateSystem: 'geo', // 使用坐标系
  symbolSize: 15, // 散点标记大小
  label: {
    formatter: '{b}',  // 文本格式化
    position: 'top', // 文本出现位置
    show: true,  // 是否显示
    fontSize: 18,  // 文本字体大小
    color: '#FFF',  // 文本字体颜色
    fontWeight: 700, // 文本字体粗细
  },
  itemStyle: {
    color: '#dcbc1a',  // 散点颜色
  },
  zlevel: 2,  // 图层层级，按需要设置
},

echarts官方涟漪特效配置

{
        type: 'effectScatter',
        name: 'xxx',
        data: [], // 数据格式与图层map一致，需包含name，value
        coordinateSystem: 'geo', // 使用坐标系
        symbolSize: 12, // 涟漪大小
        showEffectOn: 'render', // 特效出现时机
        rippleEffect: { // 涟漪特效相关配置
          brushType: 'fill', // 涟漪款式，推荐这个，另一个有点丑
          color: '#b02a02', // 涟漪颜色
          scale: 5, // 波纹缩放比例
        },
        label: {
          formatter: '{b}',
          position: 'top',
          show: true,
          fontSize: 19,
          color: '#FFF',
          fontWeight: 700,
        },
        itemStyle: {
          color: '#b02a02',
        },
        zlevel: 3,
      },

五、nameMap自定义地区的名称映射

无论是地图地区文本的展示还是地图点击事件触发，返回的是对应地区名，都是从JSON文件中获取的，这就导致展示的文本或点击事件获取的地区名不符合心意。这时就需要用到nameMap，示例如下⬇

// 左侧是 JSON文件 中预设好的文本，右侧是自己想要的文本
{
	"香港特别行政区" : "中国香港",
	......
}

nameMap是在geo坐标系中和图层map中都有的配置项。下面会给出每个地区省会的坐标地点 JSON文件，这份geo坐标json文件是从 当初下载的地图JSON中一点点抽离出来的，其中河北及甘肃的省会坐标在地图文件中找不到，可能是我眼瞎了，在我整理的JSON文件中河北及甘肃的省会坐标是从高德地图坐标拾取器拿到的，所以有些不一样。如果坐标有问题，记得Call小弟一下，各位佬。

提取码：jdtc，中国地图相关JSON文件

最后，祝祖国繁荣昌盛！！

文章有问题之处还望评论斧正！