企业官网建设流程全解析

很多时候，数据可视化项目的第一个需求，往往就是一句“做个地图，把各省的项目分布标出来”。听起来简单，不就是显示省份地图、填个颜色嘛。真正动手才会发现，光是把一张准确的省份地图顺利放到页面里，就能排掉一整天的雷。

这篇东西，就是把我自己踩过的坑、试错后的做法、以及复盘结论一并整理出来。核心围绕“项目分布地图”里的基础环节——显示省份地图，从需求拆解、技术选型、数据准备，到编码实现、排查问题，尽量讲透。如果你正准备做一个类似的项目分布可视化页面，或者你只是想搞明白“地图组件到底怎么接数据”，这篇文章应该能让你少走不少弯路。

1. 需求拆解：你要的究竟是“一张地图”还是“一个分析工具”

1.1 “显示省份地图”背后真正的诉求

先说个最常见的误区。很多开发者在听到“显示省份地图”时，第一反应是“找地图组件、接GeoJSON、把地图画出来”，然后把所有精力都花在了“画”这件事上。

但实际项目中，“显示省份地图”从来不是终点，它只是通往最终目标的起点。我接到过的真实需求，往往是这样描述的：

• “我想看到哪些省项目多、哪些省项目少。”
• “领导要看一眼全国分布，颜色深的就是重点项目地区。”
• “点某个省，想看到这个省下面的城市分布。”

把这些话翻译一下，本质上是：需要一张以省份为粒度的数据承载地图，用颜色深浅表达数值大小，并且能够支持后续下钻和联动。如果你仅仅画了一张没有数据绑定、不能交互的静态地图，那就没有解决任何实际问题。

所以在动手写代码之前，第一件事应该是和需求方对齐：地图上展示的指标是什么？粒度量是省级还是市级？是否需要点击交互？数据更新频率如何？别小看这几个问题，它们直接决定了你后面的技术方案。

1.2 项目分布地图的典型应用场景

我做过和接触过的项目分布类可视化，大致逃不出下面三类：

第一类是数量分布场景。每个省份对应一个数字，比如项目数量、客户数量、设备数量。这种场景下地图的用法很简单，用颜色深浅表达数量高低，再配一个悬浮提示框展示具体数值。

第二类是规模分布场景。数字本身代表的是项目金额、投资规模、合同额等连续型数值。这类数据通常跨度很大，有的省是几千万，有的省是几十个亿。这时如果你用线性映射的颜色，小值区域会全部糊成同一个颜色，必须做分段处理或者取对数。

第三类是状态分布场景。每个省份对应的是一个状态分类，比如已签约、实施中、已完成、未开展。这种场景就不能用连续色带，通常用离散色块或者打点标记，并且往往需要图例明确说明每个颜色的含义。

搞清楚这三种场景，你才能决定地图上用哪种视觉编码方式。可视化领域有一句话叫“形态即信息”，Color用在连续数据上表达程度，用在离散数据上表达类别，用反了，图表再炫，信息传达也是失败的。

1.3 省级粒度为什么是一个“刚刚好”的粒度

项目分布地图有一个好处，就是省级这个粒度非常合适。

粒度太细，比如到区县一级，会带来两个麻烦：一是区域数量庞大，渲染性能压力成倍增长；二是很多数据在区县级别根本没有统计意义，数据稀疏会让地图上大片区域都是空白。粒度太粗，比如只分为“华东、华南、西南”几个大区，信息损失太大，做出来的地图跟饼图区别不大，体现不出空间的纵深。

省份这个粒度，数据基本都有统计口径，边界信息又是现成的基础地理底图，渲染开销可控，交互语义也清晰。对于大多数“项目分布”类需求，省份地图就是性价比最高的展示形态。明确这一点之后，后续的所有设计决策都顺理成章了。

2. 技术选型解析：地图组件那么多，为什么最终选了这套方案

2.1 主流地图渲染方案横向对比

说到前端画地图，可选方案其实不少，但各有各的使用边界。我把常用的方案整理了一下，方便大家对比：

这里面的取舍很有意思。D3.js 足够强大，但如果你只是需要展示“按省份填色”的数据地图，用D3的投入产出比是很低的——你需要自己处理投影、缩放、tooltip、图例，所有这些ECharts都内置好了。

Leaflet 在GIS领域很强，但它是偏“地图应用”的框架，主打的是瓦片底图、标记点、轨迹，而不是“按行政区域统计填色”。当然你也可以把GeoJSON图层叠上去，但整个交互体验需要自己调。

2.2 为什么我选择 ECharts + GeoJSON 的组合

我不卖关子，直接说我最终选定的方案：ECharts 5.x + 标准GeoJSON省份数据。

选择ECharts，核心原因有三个。

第一，数据驱动是它的原生模型。ECharts里的系列配置项是围绕数据设计的，你把data: [{name: '广东省', value: 23}]喂给map系列，它自动完成从数值到颜色的映射、tooltip展示、图例生成。这跟“数据可视化”这个业务场景的诉求是天然对齐的。

第二，交互能力开箱即用。地图缩放（roam）、区域高亮、悬浮显示tooltip、点击事件、下钻联动，这些能力ECharts都是现成的，配置一个option就能开启。对一个业务项目来说，用最小成本实现最完整的功能，永远是第一原则。

第三，GeoJSON数据可以离线维护。ECharts 5之前版本内置的地图数据，在新版本中被移除了，需要单独准备GeoJSON文件。这其实是一个好事，因为行政边界数据本身是会发生变更的，离线维护一个标准的数据文件，你才能控制地图数据的质量和更新节奏。

2.3 GeoJSON数据准备：从哪里获取，如何检查质量

方案定了之后，最先要解决的是数据。这里的坑特别多，我特意多说几句。

GeoJSON是一种基于JSON的地理数据格式，用FeatureCollection和Feature来表达点、线、面。省份地图实际用的是MultiPolygon类型，每个省份是一块或者多块封闭区域。要画全国省份地图，需要一份包含所有省级行政边界的GeoJSON文件。

获取渠道上，选择项目所在地网络环境内可稳定访问的开源地址即可。常见的做法是从GitHub上一些开源地理数据仓库拉取，或者使用一些数据可视化平台提供的开放行政区划数据接口。这里给大家一个提醒：不要用来历不明的二手GeoJSON。我见过有人从某个技术博客复制了一段地图数据，结果新疆和西藏的边界少了一块，地图上出现一个大豁口，排查了半天才发现是数据问题。

拿到GeoJSON之后，建议先做三件检查：

第一，检查属性字段。确认每个Feature的properties里有name字段，且字段值是省份全称，比如“广东省”，而不是“广东”。因为后面我们做数据匹配时，就是用这个字段来对应。

第二，检查边界完整性。在页面上先渲染一次，肉眼观察是否有缺失区域、撕裂边缘。这一步很重要，因为数据文件里任何一个坐标点损坏，都可能导致某个省份渲染异常。

第三，检查文件大小。全国省份级别的GeoJSON，一般会从几百KB到几MB不等。如果文件过大，要考虑降精度。GeoJSON的坐标精度层级是可以压缩的，保留5位小数足以满足可视化展示需求，再高就没有实际意义了。压缩之后文件体积能减小70%以上，对页面加载速度很有帮助。

2.4 关于地图底图：为什么不用在线瓦片

有些读者可能会问：既然显示省份地图，为什么不用高德、百度这类在线地图的省份边界？

原因有两点。第一，在线地图本质上是一个底图服务，你可以在上面叠加自己的数据，但是“省份填色”这类行政区域统计视图，并不是它的原生强项。第二，接入在线地图需要引入额外的SDK、申请Key，还会受到网络环境限制。离线GeoJSON + ECharts的方案更加可控，而且完全满足项目内网部署的需求。

当然，如果你的需求里必须显示城市道路、办公楼宇、实时位置，那另当别论，在线地图SDK是不可替代的。具体问题还得具体分析。

3. 核心实现：从零到一搭出可交互的省份分布地图

3.1 引入 ECharts 与初始化容器

实现部分，我用一段精简但完整的流程来演示。假设你已经有一个前端工程（Vue/React/原生都可以，核心逻辑一致）。

首先安装ECharts：

npm install echarts

然后在页面中准备一个容器节点。这里有一个非常重要的注意事项：容器必须有明确的宽度和高度。很多新手在初始化时发现地图渲染不出来，八成是因为容器高度为0。CSS里给#mapContainer设置一个固定高度，比如600px，或者是用flex布局撑开高度。

<div id="mapContainer" style="width: 100%; height: 600px;"></div>

3.2 加载 GeoJSON 并注册地图

接着加载GeoJSON文件，通过ECharts的registerMap接口注册地图。这里有两种常见做法。

第一种是直接import本地JSON文件：

import * as echarts from 'echarts'; import chinaJson from '@/assets/geo/china.json'; echarts.registerMap('china', chinaJson);

第二种是异步获取：

import * as echarts from 'echarts'; const response = await fetch('/geo/china.json'); const chinaJson = await response.json(); echarts.registerMap('china', chinaJson);

这里要特别提醒：只有注册了名为china的地图，后面的series.map里写map: 'china'才会生效。如果顺序颠倒，你会看到控制台报错Map china not exists。

ECharts的registerMap函数接收两个参数：第一个是地图名称，自定义即可，只要和后续配置里的map字段保持一致；第二个是JSON对象。本质上，它做的事情是把GeoJSON中的几何坐标和属性信息解析成ECharts内部的渲染数据结构。

3.3 基础配置：从“画出来”到“能交互”

注册完地图之后，就可以设置图表的option了。最基础的三件套是tooltip、visualMap和series。

const chart = echarts.init(document.getElementById('mapContainer')); const option = { tooltip: { trigger: 'item', formatter: function(params) { if (params.value) { return params.name + '<br/>项目数：' + params.value; } return params.name + '<br/>暂无数据'; } }, visualMap: { min: 0, max: 100, left: 20, bottom: 20, calculable: true, text: ['高', '低'], inRange: { color: ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'] } }, series: [{ name: '项目分布', type: 'map', map: 'china', roam: true, label: { show: true, fontSize: 10 }, data: projectData }] }; chart.setOption(option);

这一串配置，逐项说一下。

tooltip的trigger设置为item，鼠标悬浮到某个省份上时显示该省份信息。我用formatter函数自定义了展示内容：如果该省有数据，显示“项目数：XX”；如果没有数据，显示“暂无数据”。这个细节很多人会忽略，默认的tooltip在没有数据时会显示undefined，观感很差。

visualMap是ECharts的视觉映射组件，它负责把series中的数值映射成颜色。min和max对应数值范围，color数组按顺序对应从小到大。calculable: true会生成一个可拖动的筛选图标，用户可以拖动手柄筛选范围，这在数据探索场景下很有用。

series里type: 'map'告诉ECharts渲染一个地图系列，map: 'china'引用前面注册的地图数据。roam: true允许用户缩放和平移地图，这个对全国地图来说非常必要，否则省份名称会挤成一团看不清。label.show决定是否显示省份名称，全国地图上字号建议10像素左右，太大会相互重叠。

data就是我们喂给地图的实际业务数据，格式如下：

const projectData = [ { name: '广东省', value: 45 }, { name: '江苏省', value: 38 }, { name: '浙江省', value: 32 }, { name: '山东省', value: 27 } ];

这里需要强调一点：name字段必须与GeoJSON中properties.name字段完全一致，才能实现正确匹配。你只需要写有数据的省份，没有数据的省份ECharts会自动按visualMap的min值对应的浅色渲染。

3.4 数据匹配的坑：省份名称的“全称”与“简称”

这是实战中最容易出现的问题，我单独拉出来说。

GeoJSON中的省份名称，从官方数据源获取时，往往是全称，比如“新疆维吾尔自治区”、“内蒙古自治区”、“广西壮族自治区”。但业务系统里的数据，常常只存简称，比如“新疆”、“内蒙古”、“广西”。当你的data里写{name: '新疆'}，而GeoJSON里是“新疆维吾尔自治区”时，ECharts匹配不到，这个省份就无法高亮和联动。

解决方案很简单：在数据处理层做一层名称映射，把数据里的名称转换为GeoJSON中的全称。

const provinceNameMap = { '新疆': '新疆维吾尔自治区', '内蒙古': '内蒙古自治区', '广西': '广西壮族自治区', '西藏': '西藏自治区', '宁夏': '宁夏回族自治区', '香港': '香港特别行政区', '澳门': '澳门特别行政区' };

然后在组装series data的时候，统一转换：

const rawData = [ { name: '新疆', value: 12 }, { name: '广东', value: 45 } ]; const projectData = rawData.map(item => ({ name: provinceNameMap[item.name] || item.name, value: item.value }));

用|| item.name兜底，是因为大多数省份简称和全称的起始汉字是一致的，比如“广东省”可以直接用“广东”匹配到。这里要注意的是，尽量以全称数据为准来构造映射表，避免出现“黑龙江省”和“黑龙江”混淆的情况。

另外，还有一个极容易踩的坑：港澳台的名称。如果你的项目数据里有香港、澳门、台湾，务必确认GeoJSON里的名称格式。有的数据源使用“香港特别行政区”，有的使用“香港”，这两种情况做匹配时都必须覆盖。

3.5 视觉细节：让地图真正“会说话”

地图render出来只是第一步，让读者一眼看懂信息才是关键。有两个视觉细节值得打磨。

第一个是颜色分级策略。如果数据跨度很大，比如最小值是1，最大值是1000，线性color映射会导致大多数省份都呈现最浅色，只有最大值的省份是深色，地图整体看起来一片苍白。这种情况我建议使用visualMap的pieces分段模式：

visualMap: { type: 'piecewise', pieces: [ { min: 0, max: 5, label: '0-5个项目', color: '#e0f3f8' }, { min: 6, max: 20, label: '6-20个项目', color: '#abd9e9' }, { min: 21, max: 50, label: '21-50个项目', color: '#74add1' }, { min: 51, max: 100, label: '51-100个项目', color: '#4575b4' }, { min: 101, label: '100个以上', color: '#313695' } ] }

分段模式的原理是把连续数值分成若干区间，每个区间绑定一个固定颜色。这样即使数据跨度大，视觉上也能分出层次。如果你是做汇报大屏，这个方法非常实用，因为业务方更容易解读“深色代表项目多，浅色代表项目少”这种分段语义。

第二个是空白省份的处理。实际数据往往只覆盖部分省份，比如只有10个省有项目。这时其他省份会以visualMap.min对应的颜色渲染。如果min对应的颜色是浅色，和没有数据很难区分。我一般会在series里加一个data之外的处理：给没有数据的省份也放一条“空数据”记录，让tooltip显示“暂无数据”，而不是完全空白。

这里有个取巧的小方法，不用在data里填充所有省份，而是在tooltip的formatter里做判断即可，代码我已经在上面示例里写过了。核心思路就是：宁可显示“暂无数据”，也不要显示undefined或者0，因为“0个项目”和“暂无数据”对业务方来说是两种完全不同的语义。

3.6 交互增强：点击省份看明细，缩放再也不怕看不清

既然做的是项目分布地图，用户大概率想点击某个省份看具体数据。ECharts的地图组件支持click事件，这是实现下钻最基础的能力。

chart.on('click', function(params) { if (params.name) { // 这里可以触发一个自定义事件，或者联动其他图表 console.log('点击了省份：', params.name); } });

实际项目里，我经常把这个点击事件和右侧的明细列表联动起来：点击省份，右侧展示该省的项目清单；再点击空白处，清空列表。实现方式就是用chart.on('click')抛出一个自定义事件，页面的其他组件接收事件后更新自己的数据。

至于缩放，roam: true开启之后，用户可以直接用鼠标滚轮缩放。对于全国省份地图，这个功能基本是标配。不过要注意的是，缩放之后省份的边界线会变粗，视觉上不够精致。建议在series里增加一项itemStyle配置：

itemStyle: { borderColor: '#fff', borderWidth: 0.5 }, emphasis: { itemStyle: { areaColor: '#ffd700' } }

borderColor设置省份边界的颜色，borderWidth控制宽度。emphasis是鼠标悬停时的高亮样式。这些细节虽然小，但加不加，地图的质感差别很大。

3.7 异步数据加载的落地范式

真实项目中，地图数据通常不是写死在代码里的，而是通过接口返回的。我给出一个经过验证的完整范式。

async function initMap() { // 1. 并行获取地图GeoJSON和业务数据 const [geoJson, statData] = await Promise.all([ fetch('/geo/china.json').then(res => res.json()), fetch('/api/project-distribution').then(res => res.json()) ]); // 2. 注册地图 echarts.registerMap('china', geoJson); // 3. 组装数据 const projectData = statData.map(item => ({ name: item.provinceName, value: item.projectCount })); // 4. 渲染 const chart = echarts.init(document.getElementById('mapContainer')); chart.setOption({ // ...省略完整配置 series: [{ type: 'map', map: 'china', data: projectData }] }); }

用Promise.all并行加载，既能减少等待时间，又能保证两个数据都就绪后再统一渲染。这里还藏着一个容易忽略的点：如果网络请求失败，要有兜底逻辑。我一般在catch里给页面一个错误提示，而不是让页面白屏。

4. 常见问题与排查技巧实录：地图组件排雷清单

4.1 地图一片空白，什么原因

这个问题出现的频率最高，而且往往不是单一原因导致的。排查时按这个顺序来：

第一，检查容器高度。如果div的高度是0或者没有被撑开，ECharts即使初始化成功，渲染出来也是空白。打开浏览器开发者工具看看容器元素的实际尺寸。

第二，检查地图是否注册成功。在控制台执行console.log(echarts.getMap('china'))，如果返回undefined，说明registerMap没有执行或者执行失败。常见情况是GeoJSON文件没有正确导入。

第三，检查series.map字段是否和注册名称一致。这个看起来简单，但依赖多个配置文件时，复制粘贴很容易搞错名称。

4.2 部分省份不显示，或者显示成“无边界”区域

如果你看到地图上某些省份缺失，优先怀疑GeoJSON数据本身。

有个非常经典的案例：旧版本的GeoJSON中，重庆市的边界和四川省边界是合并处理的，如果数据源更新不及时，重庆区域就无法单独显示。再比如，有些二手数据缺少台湾地区的多边形数据，地图上就是一块空白。

这个问题的排查方案是：换一份已知正确的标准GeoJSON做对比测试。如果换了正常数据后地图渲染完整，那就确认是数据文件的问题。如果换了还是老样子，再往代码逻辑方向排查。

4.3 数据匹配不上，省份不上色

这是业务数据接入时最常见的问题。表现是：地图渲染出来了，tooltip也正常，但某个省份的颜色始终是浅色，即使它的数值很大。

排查思路就是我在3.4节说的名称匹配问题。你可以在series的data中临时打印一下params.name和GeoJSON里的properties.name，看看两边是否完全一致。特别注意标点符号、空格、全半角差异，肉眼看不出来但字符串比较就是过不去。

我建议在项目初期就建立一个“省份名称对照表”的公共模块，把简称、全称、别名都维护进去，后续接入任何数据源时统一走这个模块转换，一劳永逸。

4.4 地图渲染很慢，交互卡顿

省份地图的GeoJSON文件如果过大，会导致页面加载慢、缩放卡顿。

我实测过，一个完整的高精度全国省级GeoJSON可能达到几MB，这个体量在现代化网络环境下虽然不至于无法加载，但在低配机器上交互体验会直线下降。解决方案有两个方向：

一是降低GeoJSON精度。使用一些在线工具或本地脚本，把坐标精度从8位小数降到5位，文件体积能明显缩减。

二是只加载需要的区域。如果业务只关注华东地区，可以裁剪GeoJSON，只保留华东几个省份的Feature，文件体积可以降到几十KB。

4.5 大屏页面上地图位置偏移

这个问题主要出现在地图容器嵌套在复杂布局中，或者页面有滚动条、缩放比例不是100%的时候。ECharts初始化时如果容器尺寸不准确，地图会产生偏移。

排查方法是：在初始化之前，用window.getComputedStyle确认容器实际宽度高度；如果是布局动态变化，需要在init之后监听尺寸变化，调用chart.resize()。

我处理过一个实际案例：项目里有一个折叠侧边栏，折叠后地图容器宽度从1200px变成900px，地图没有自动重绘，导致右侧一部分区域被截断。后来我在侧边栏折叠事件里加了chart.resize()，问题立刻解决。

5. 从“会显示地图”到“地图用得好”：进阶方向与个人体会

5.1 从静态展示走向下钻联动

很多项目在完成“显示省份地图”之后，紧接着就会提新需求：“点一下省份，能看到这个省内部的市级分布。”这就是地图下钻。

实现下钻的思路并不复杂：准备全省的GeoJSON数据，注册多个地图名称，点击省份时切换当前地图的series.map为对应省份地图。这里推荐一个实践：不一次性加载所有省份的市级GeoJSON，而是按需加载。比如用户点击广东省，再异步加载广东省的市级GeoJSON并注册，这样初始加载压力可控。

点击事件的联动范围为市级时，你还需要处理“返回上一级”的交互。常见的做法是提供一个“返回全国”的按钮，点击后把地图重新切回china。这个交互模式虽然简单，但实用性强，领导们都很认这种“总-分”的呈现方式。

5.2 地图与图表联动才是项目分布可视化的终局

只做一张孤立的地图，对于数据分析场景是不够的。真正让项目分布地图发挥价值的，是地图 + 排名列表 + 趋势图的联动组合。

我做过一个典型的大屏，左侧是一个省份排行榜（条形图），中间是全国省份地图，右侧是该省项目明细表格。三者通过省份维度联动：点击地图上的省份，左侧排行自动高亮该省份，右侧表格刷新为该省项目清单。反向也可以：点击排行榜的某一行，地图自动聚焦到对应省份区域。

联动的基础，就是建立在“地图点击事件”之上。事件作为桥梁，把原本独立的地图组件、图表组件、表格组件串成一条链路。这也是为什么我在前面花了那么多篇幅去写点击事件和数据结构——地图上的省份，本质上就是一组可交互的数据筛选器。

5.3 个人踩坑后沉淀的三条经验

最后分享几条我自己摔过跟头才总结出来的经验。

第一，永远在项目第一天就确认地图数据版本。行政边界是会变更的，同一个省份在不同年份的数据源里可能有细微差别。项目上线前，让业务方在页面上肉眼确认一遍各省边界和名称是否准确。这一点钱不能省。

第二，地图的配色要留出无障碍余地。不要用红绿色盲无法区分的组合，深蓝色到浅蓝色系是相对稳妥的选择。大屏投影环境下，颜色过浅的色值显示效果很差，尽量用饱和度高一些的颜色。

第三，把地图封装成一个独立组件，接口设计成数据驱动。我第一次做的时候把地图逻辑全部写在一个页面里，结果后面要放到另外两个页面复用，改了三轮才抽出来。建议一开始就把组件边界划清楚：入参是省份数据数组和配置项，出参是点击省份事件。有了这层封装，后续接任何项目分布类的需求，你只需要改一行数据格式适配代码，剩下的全自动跑。

这些经验听起来都不复杂，但每一项都是用真实项目里的加班换来的。可视化开发，最怕的不是技术实现不了，而是在业务沟通过程中把方向带偏。地图只是表达载体，清晰、准确、可操作，才是项目分布可视化的本质追求。