1. 项目概述为什么需要处理中国地图的南海诸岛在基于 Vue 和 ECharts 开发数据可视化大屏或管理后台时中国地图是一个高频需求。无论是展示各省份的销售数据、用户分布还是疫情态势一张清晰、准确的地图都是传递信息的核心载体。然而很多开发者第一次使用 ECharts 绘制中国地图时都会遇到一个“不大不小”的问题地图右下角那个代表南海诸岛的矩形“小方块”即简图它要么不显示要么显示的位置和样式不对劲。这个“小方块”可不是一个简单的装饰。在标准的中文版中国地图中南海诸岛作为我国领土不可分割的一部分必须以附图形式在地图主区域右下角予以展示。这是制图规范也是项目合规性的基本要求。如果你交付的项目中中国地图缺失了这个部分轻则被客户或产品经理要求返工重则可能引发不必要的误解。因此处理好这个“南海诸岛简图”远不止是技术细节更是开箱即用、符合规范的交付能力的体现。我经历过几次因为忽略这个细节而连夜修改的窘境。后来发现ECharts 官方提供的 GeoJSON 数据本身是包含南海诸岛区域的但默认的系列series配置和视觉映射visualMap往往只作用于主地图导致那个“小方块”要么是空白要么颜色与主图不一致看起来像个“补丁”。所以今天我们就来彻底解决这个问题实现一个主图与南海附图数据联动、样式统一、且易于复用的 Vue ECharts 中国地图组件。2. 核心思路与方案选型要实现目标我们不能简单地使用一个china地图。核心矛盾在于我们需要将“中国大陆及沿海岛屿”与“南海诸岛附图”视为一个整体数据源下的两个不同渲染区域并对它们进行协同控制。2.1 方案对比单地图 vs. 双坐标系最初级的想法是使用两个 ECharts 实例一个画主图一个画南海附图然后通过事件同步它们。但这样做的代码耦合度高联动效果生硬且性能不佳。ECharts 提供了更优雅的解决方案在同一个实例中使用多个地理坐标系geo。单地图方案不可行直接使用echarts.registerMap(China, geoJSON)注册包含南海的完整中国地图然后在series中配置一个type: map的系列。问题在于map系列或geo组件在绘制时虽然数据包含了南海区域但默认的布局和缩放中心是针对大陆部分的南海附图会被挤到角落甚至视口之外无法以清晰的附图形式展示。双坐标系方案推荐我们注册一个包含完整地理信息含南海的 GeoJSON 数据。然后在option中配置两个geo组件。geoIndex: 0用于绘制中国大陆主图。通过map: China关联数据并通过boundingCoords或center/zoom将其视图锁定在中国大陆区域。geoIndex: 1用于绘制南海诸岛附图。同样关联map: China但通过layoutCenter和layoutSize将其定位到画布的右下角并设置一个较小的尺寸形成“附图”效果。在series中我们可以使用type: map或type: effectScatter等并通过geoIndex属性指定数据要渲染在哪个地理坐标系上。这样同一份数据可以分别在两个区域渲染实现联动。为什么选择双坐标系方案因为它完美契合了“一份数据两种视图”的需求。所有对数据的操作如高亮、数据映射、下钻只需要维护一份ECharts 会自动在两个geo视图上同步响应。这保证了数据与视图的一致性极大简化了状态管理。2.2 技术栈与资源准备Vue 3使用 Composition API (script setup) 进行开发代码更简洁。原理同样适用于 Vue 2。ECharts 5.x确保使用较新版本其对 TypeScript 支持和模块化更好。地图数据这是关键。我们需要一份标准的、包含南海诸岛九段线的China GeoJSON数据。不推荐直接使用echarts内置的china.js已过时且不推荐。推荐从权威来源获取如阿里云的 DataV.GeoAtlas。我们可以直接使用 ECharts 官方推荐的在线资源https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json这个100000_full.json就是包含国界、海岸线、南海诸岛及九段线的完整中国 GeoJSON。重要提示地图数据的合规性至关重要。务必使用来自官方或权威渠道的、符合我国公开地图内容表示规范的数据。上述阿里云 DataV 提供的数据是符合规范的常用来源。3. 核心实现步骤详解我们将创建一个名为ChinaMapWithSouthChinaSea.vue的组件。3.1 组件基础结构与地图注册首先安装依赖并初始化组件。npm install echartstemplate div refchartRef stylewidth: 100%; height: 600px;/div /template script setup import { ref, onMounted, onBeforeUnmount, watch } from vue; import * as echarts from echarts; // 注意在Vue项目中通常建议按需引入以减小打包体积 // import { init, registerMap } from echarts/core; // import { GeoComponent, MapChart } from echarts/charts; // import { CanvasRenderer } from echarts/renderers; // echarts.use([GeoComponent, MapChart, CanvasRenderer]); const chartRef ref(null); let chartInstance null; const geoJsonData ref(null); // 存储获取到的GeoJSON数据 // 1. 获取并注册地图数据 const fetchAndRegisterMap async () { try { const response await fetch(https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json); geoJsonData.value await response.json(); // 注册地图数据命名为 China echarts.registerMap(China, geoJsonData.value); initChart(); } catch (error) { console.error(Failed to fetch or register map data:, error); // 在实际项目中这里应该有更友好的错误处理比如显示一个错误占位图 } }; /script这里我们选择在组件初始化时动态获取 GeoJSON 数据。你也可以在构建时下载该 JSON 文件到public或assets目录然后通过import引入这样更稳定但失去了动态更新的灵活性。3.2 配置双Geo坐标系与地图系列initChart函数是核心它负责配置并渲染图表。const initChart () { if (!chartRef.value || !geoJsonData.value) return; chartInstance echarts.init(chartRef.value); const option { // 2. 配置两个地理坐标系 (geo) geo: [ { // 主地图坐标系 id: main, // 给geo起个id方便series引用 map: China, roam: true, // 允许缩放和平移 zoom: 1.2, // 初始缩放级别调整到合适的大小 center: [104.0, 37.5], // 初始中心点大致为中国几何中心 label: { show: true, fontSize: 10, color: #333 }, itemStyle: { areaColor: #f7f8fa, borderColor: #ccc, borderWidth: 0.5 }, // 关键通过 boundingCoords 限定主地图的显示范围确保南海区域不被显示在这里 boundingCoords: [ [73.0, 53.5], // 西南角坐标 (经度纬度) [135.0, 18.0] // 东北角坐标。这个范围大致框住了中国大陆将南海区域排除在外 ], emphasis: { // 鼠标高亮样式 itemStyle: { areaColor: #ffd166 }, label: { color: #000, fontWeight: bold } } }, { // 南海诸岛附图坐标系 id: southChinaSea, map: China, show: true, // 关键使用 layoutCenter 和 layoutSize 将附图固定在右下角 layoutCenter: [88%, 85%], // 定位到容器的 88% 宽度85% 高度处右下区域 layoutSize: 18%, // 附图大小为容器的18% // 设置附图自己的视觉样式建议与主图风格一致但可区分 itemStyle: { areaColor: #f7f8fa, borderColor: #aaa, borderWidth: 0.5 }, label: { show: true, fontSize: 8, // 附图标签可以小一点 color: #666 }, // 关键限定附图的显示区域只显示南海部分 boundingCoords: [ [105.0, 3.0], // 南海区域的西南角 [123.0, 25.0] // 南海区域的东北角 ], // 通常附图不需要漫游 roam: false, zoom: 1, silent: true, // 设置为true使附图默认不触发事件可选根据交互需求定 emphasis: { itemStyle: { areaColor: #ffd166 // 保持高亮颜色与主图一致 } } } ], // 3. 配置地图系列将数据同时绘制到两个geo上 series: [ { name: 示例数据, type: map, // 使用map系列 geoIndex: 0, // 关联第一个geo主地图 map: China, // 这里可以绑定你的业务数据例如各省份的值 data: [ { name: 广东省, value: 100 }, { name: 北京市, value: 95 }, { name: 新疆维吾尔自治区, value: 80 }, // ... 其他省份数据 ], // 视觉映射根据 data 中的 value 值映射颜色 visualMap: { type: piecewise, // 分段型 show: true, left: left, top: bottom, pieces: [ { min: 90, label: 高, color: #c23531 }, { min: 70, max: 89, label: 中, color: #dd6b66 }, { max: 69, label: 低, color: #f4e7da } ], // 关键这个visualMap会同时作用于所有关联了相同map的series。 // 因为我们只有一个series关联了geoIndex:0所以只影响主图。 // 如果希望附图也有颜色需要单独为附图配置series或使用另一个visualMap。 }, itemStyle: { borderColor: #fff }, emphasis: { itemStyle: { areaColor: #ffd166 } } }, // 为了在南海附图上也显示对应的颜色例如南海诸岛区域本身作为一个“省份”显示颜色 // 我们需要再添加一个series关联到附图的geoIndex。 // 但注意南海诸岛在GeoJSON里可能不是一个单独的省份而是多个岛屿。 // 一种常见做法是将南海区域的数据作为一个整体或按岛屿绑定。 // 这里为了简化我们假设数据中有一个名为‘南海诸岛’的区域。 { name: 南海数据, type: map, geoIndex: 1, // 关联第二个geo南海附图 map: China, data: [ // 你需要确保GeoJSON数据中有对应的区域名称例如‘三沙市’或岛屿群名称。 // 这里用‘南海诸岛’示意实际名称需查询你的GeoJSON。 { name: 三沙市, value: 60 }, // 示例三沙市是管辖南海诸岛的地级市 ], // 可以复用主图的visualMap也可以单独设置itemStyle itemStyle: { // 如果不设置会尝试使用全局或上一个visualMap可能不匹配。 // 这里直接指定一个颜色确保附图有颜色。 areaColor: #dd6b66, // 与主图‘中’等级颜色一致 borderColor: #fff }, emphasis: { itemStyle: { areaColor: #ffd166 } }, // 通常附图的series标签可以关闭避免与主图标签重叠 label: { show: false } } ], tooltip: { trigger: item, formatter: function(params) { return ${params.name}br/数值${params.value || 无数据}; } }, title: { text: 中国地图含南海诸岛附图示例, left: center } }; chartInstance.setOption(option); // 响应窗口大小变化 window.addEventListener(resize, handleResize); };3.3 交互联动与细节优化上面的配置已经实现了基本效果。但还有几个关键细节需要处理数据一致性主图与附图的data需要保持一致。例如如果“广东省”的数据更新了两个series里对应的数据项都要更新。最佳实践是维护一份统一的mapData然后在生成series配置时根据区域名称分别筛选出属于主图和附图的数组。// 假设有一份完整的数据 const allData [ { name: 广东省, value: 100 }, { name: 北京市, value: 95 }, { name: 三沙市, value: 60 }, // ... ]; // 在准备option时 const mainLandData allData.filter(item item.name ! 三沙市); // 简化逻辑实际需根据GeoJSON特征筛选 const southChinaSeaData allData.filter(item item.name 三沙市);视觉映射同步我们希望主图和附图的颜色映射规则一致。可以将visualMap配置提取到option顶层并确保series中的data都遵循同一套值域。这样ECharts 会自动应用相同的颜色映射到所有相关的系列上。visualMap: { type: piecewise, show: true, left: left, top: bottom, pieces: [ /* ... */ ], // seriesIndex: [0, 1] // 可以指定这个visualMap同时控制第0和第1个series // 但更简单的方法是只要series的data值在pieces定义的范围内就会自动映射。 }, series: [ { name: 主图, type: map, geoIndex: 0, data: mainLandData }, { name: 附图, type: map, geoIndex: 1, data: southChinaSeaData }, // 两个series的data都会受到顶层visualMap的影响 ]事件处理当用户点击主图或附图时触发的事件需要能区分来源。可以通过params.componentType和params.componentIndex来判断。onMounted(() { if (chartInstance) { chartInstance.on(click, (params) { if (params.componentType geo) { console.log(点击了 ${params.name}来自 geo 索引: ${params.componentIndex}); // componentIndex 0 是主图1 是附图 if (params.componentIndex 1) { // 点击了南海附图可以做一些特殊处理比如弹窗显示更详细的南海信息 alert(您点击了南海区域${params.name}); } } }); } });3.4 组件生命周期与性能// 处理窗口缩放 const handleResize () { chartInstance?.resize(); }; // 监听数据变化更新图表 watch(yourDataRef, (newVal) { if (chartInstance geoJsonData.value) { // 更新option中的series.data chartInstance.setOption({ series: [ /* 更新后的主图数据 */, /* 更新后的附图数据 */ ] }); } }, { deep: true }); onMounted(fetchAndRegisterMap); onBeforeUnmount(() { window.removeEventListener(resize, handleResize); chartInstance?.dispose(); chartInstance null; });4. 常见问题与避坑指南在实际开发中你可能会遇到以下问题4.1 南海附图不显示或位置不对问题附图完全看不到或者位置不在右下角。排查检查layoutCenter和layoutSize的值。[88%, 85%]意味着中心点定位在容器宽度88%、高度85%的位置。如果你的容器很大或很小可能需要调整。确认第二个geo的show属性为true。检查boundingCoords是否正确地框选了南海区域。坐标范围不对会导致附图内容为空。建议先用一个大的范围测试比如[[105, 0], [125, 25]]确保能显示出来再精确调整。技巧可以临时给第二个geo的itemStyle设置一个醒目的颜色如areaColor: red以便在页面上快速定位它。4.2 主图和附图颜色不一致问题主图省份根据数据有不同颜色但南海附图是统一的灰色或默认色。原因visualMap默认作用于所有系列但它的计算是基于所有series.data的。如果你的“南海数据”系列geoIndex: 1的data数组为空或者其value值不在visualMap定义的分段内就不会被映射上颜色。解决确保数据完整检查为附图系列 (geoIndex: 1) 提供的data数组是否包含了南海区域如“三沙市”的有效数据项且value值合理。检查区域名称匹配GeoJSON 中的区域名称properties.name必须与你data中的name属性完全一致。例如GeoJSON 里可能是“海南省”包含三沙也可能是单独的“三沙市”。使用console.log(geoJsonData.value.features.map(f f.properties))来查看所有区域名称。使用统一的 visualMap将visualMap配置在option顶层并确保主图和附图系列的数据 (series[0].data和series[1].data) 都合并在一起参与视觉映射的计算。ECharts 的顶层visualMap默认会作用于所有系列。4.3 地图拖动/缩放时附图位置错乱问题当拖动或缩放主地图时右下角的南海附图位置跑了。原因这是预期的。layoutCenter和layoutSize是相对于容器的百分比定位与地图的经纬度坐标和缩放无关。所以无论主图怎么移动附图始终固定在容器右下角。这恰恰是我们想要的效果。注意如果你希望附图也能随主图一起移动即作为地图的一部分那就不应该使用双geo方案而是需要调整单个geo的投影和视图但这很难实现标准的“附图”样式。4.4 性能优化与数据量问题GeoJSON 文件较大100000_full.json约几百KB首次加载慢。解决本地化在生产环境中强烈建议将 JSON 文件下载到项目本地如public/geojson/目录通过相对路径引用避免网络请求和跨域问题。按需加载如果应用中有多个页面需要地图可以考虑在 Vue Router 的全局前置守卫或父组件中提前加载并注册地图数据然后通过 Vuex/Pinia 等状态管理工具共享geoJsonData。简化数据对于某些不需要精确省界的展示可以使用简化版的 GeoJSON如100000.json不带_full文件会小很多。但简化版可能丢失南海诸岛的细节务必确认其包含所需元素。4.5 地图样式与交互定制需求想要更炫酷的发光边界、渐变填充色。实现ECharts 的itemStyle支持丰富的配置。例如可以使用borderColor配合shadowBlur、shadowColor实现发光效果。填充色areaColor可以使用线性渐变。itemStyle: { areaColor: { type: linear, x: 0, y: 0, x2: 0, y2: 1, colorStops: [ { offset: 0, color: #f7f8fa }, { offset: 1, color: #dbe4f2 } ] }, borderColor: #2f89cf, borderWidth: 1, shadowBlur: 10, shadowColor: rgba(47, 137, 207, 0.5) }对于交互除了click事件还可以监听geoselectchanged、geounselectall等来实现区域选择功能。5. 封装与复用建议为了在项目中高效复用建议将上述逻辑封装成一个高度可配置的 Vue 组件。!-- ChinaMap.vue -- script setup import { defineProps, computed } from vue; const props defineProps({ mapData: { type: Array, required: true }, // 统一的数据源 visualMapPieces: { type: Array, default: () [...] }, // 视觉映射配置 mainGeoConfig: { type: Object, default: () ({}) }, // 主图geo自定义配置 southChinaSeaGeoConfig: { type: Object, default: () ({}) }, // 附图geo自定义配置 // ... 其他配置项 }); // 在组件内部根据props和默认配置合并生成最终的option const finalOption computed(() { // ... 合并逻辑 return option; }); /script这样在业务页面中你只需要引入这个组件并传入数据即可template ChinaMap :map-databusinessData / /template通过以上步骤我们不仅解决了“显示南海诸岛简图”这个具体问题更构建了一个健壮的、符合规范的中国地图可视化解决方案。记住处理地图数据无小事尤其是国界领土的展示务必使用权威、合规的数据源并在最终交付前仔细核对。