ECharts全国地图自定义图标：选型、定位与性能优化实践

ECharts 全国地图加自定义图标这个组合我在最开始做业务分布大屏的时候就反复折腾过。当时的需求特别朴素底图上把每个站点的位置标出来但领导明确要求不能用系统默认的小圆点每个站点要有自己的身份感——仓配中心是一个箱子图标门店是一个房子图标临时点位是一个小旗子图标鼠标悬停还得能弹出详情卡片。看着只是把symbol从圆点换成图片真正动起手来才发现问题一个接一个图标不显示、位置往下飘了半个身位、放大之后糊成一片、点位一多就开始掉帧。这篇就围绕“ECharts 全国地图 自定义图标”这一件事把整套方案从选型、配置、参数换算到性能与排错完整讲一遍。适合三类人看正在做大屏的、后台需要一张区域分布分析的、以及移动端塞了一个轻量地图组件的。哪怕你之前只画过柱状图照着文里的配置块改一改也能跑起来做过几张地图的同学可以重点看参数换算和性能那两节那里面的坑基本上人人都要踩一遍。1. 先把需求拆开这张图到底难在哪1.1 地图和图标其实是两件互不干扰的事很多人一上手就想找“带图标的地图组件”思路一开始就跑偏了。在 ECharts 的模型里地图和标记从来是分离的两层下层是geo组件或map系列负责把地理轮廓画出来提供一个经纬度到画布坐标的投影变换上层是scatter、effectScatter这类散点系列负责拿到经纬度之后在自己的位置画一个符号。符号长什么样完全由symbol决定跟地图没有半毛钱关系。理解了这个分层后面所有配置就有归属了底图不好看调geo.itemStyle图标画不出来调series.scatter.symbol图标位置不对调symbolOffset图标太大太小调symbolSize。我见过不少项目把这三件事混在一个配置对象里瞎试改一处动全身最后配置成了玄学。分层思维是这张图能不能维护的前提。另一个容易忽略的点是图标的坐标必须和地图用同一套坐标系。ECharts 内部对geo上的散点做投影时走的是和地图完全一致的变换管线所以你只要给对经纬度位置就是准的。真正会偏的通常是你自己在地图上叠了 DOM 覆盖层、或者用了一张设计师画的位图当底图——那种情况下 ECharts 根本不知道你的底图用了什么投影自然对不上。1.2 三类典型场景决定三套不同做法同样是“地图 图标”不同场景的最优解差别很大硬套一套配置会很难受。第一类是运营大屏。特点是点位少十几个到几十个、视觉要求高、有动画和交互、通常投在 4K 大屏上。这种做法可以用高精度位图图标甚至每个点位配不同图片配合effectScatter做呼吸效果视觉冲击力最强。代价是图片资源多、首屏加载慢得做预加载。第二类是后台分析页。点位可能上百需要筛选、联动、点击下钻。这种场景我更推荐path://矢量图标颜色能跟着itemStyle.color走方便用不同颜色表达不同状态而且没有额外请求缩放不失真。第三类是移动端轻量图。屏幕小、点位密、点击热区要求大。这种就得控制图标数量和尺寸必要时做聚合或者在缩小时用圆点、放大时切图片别一上来就怼几十张 PNG。先想清楚自己属于哪一类再往下看具体实现能省掉一半返工。2. 底座选型geo 组件还是 map 系列2.1 两者的分工与选择标准ECharts 里画地图有两条路series.type: map和geo组件。它们长相相似能力边界却不一样。series-map本质是一个“数据驱动的图表系列”它能直接把数据映射成省份填色配visualMap很方便但它自带的坐标系是封闭的你在它上面叠散点会比较别扭。geo组件则是一个纯粹的“坐标底图”它不消费数据、不参与图例、只负责画轮廓和提供投影天生适合当背景板。我的判断口径很简单只要你要在地图上叠自定义图标就用geo打底散点系列用coordinateSystem: geo挂上去。反过来如果你的需求是“各省按指标填色不要标记点”那series-map更顺手。两者也可以共存geo画底图series-map用geoIndex关联过去但配置会绕非必要不这么干。用geo打底还有一个隐性好处roam缩放拖拽是geo自身的能力缩放后散点会跟着地图一起移动坐标不会脱节。这一点在series-map上做叠加时经常出岔子。2.2 aspectScale 这个参数决定了地图“胖瘦”geo.aspectScale默认值是0.75很多人压根没注意过它。它的作用是调整地图的纵横比用来抵消常见投影方式带来的形变。默认0.75意味着地图在垂直方向被压缩了四分之一看起来更“扁”一些。这个参数本身不会导致图标错位因为图标和地图共用同一套变换。但它会影响视觉观感如果你把aspectScale设成1地图会变“高”图标之间的相对疏密关系也会跟着变。做视觉对齐的时候如果设计稿是按1出的代码里用了默认0.75你会觉得“怎么图标全都挤在一起了”。这种问题不是坐标错了是比例不对。我一般会在项目初期就把aspectScale定死并写进注释避免后面有人调了半天以为是数据问题。实测下来做全国范围的展示0.75到0.85之间观感比较自然如果只展示单个区域可以适当往1靠。2.3 注册地图数据的完整流程ECharts 本身不带地理数据得先把 GeoJSON 注册进去。流程就三步拿到 GeoJSON、调用echarts.registerMap()、在配置里引用注册名。import * as echarts from echarts; import geoJson from ./data/my-region.json; // 注册名随便起但要和后面 geo.map 里的名字严格一致 echarts.registerMap(myMap, geoJson); const option { geo: { map: myMap, roam: true, zoom: 1.1, aspectScale: 0.8, itemStyle: { areaColor: #0f2544, borderColor: #2c5f9e, borderWidth: 1 }, emphasis: { itemStyle: { areaColor: #1b3b66 }, label: { show: false } }, label: { show: false } } }; echarts.init(document.getElementById(chart)).setOption(option);几点要留心。注册名必须唯一且一致同一个页面注册两次同名地图后一次会覆盖前一次如果两个图用了不同粒度的数据就会出现“这个图的地图变了那个图也变了”的诡异现象。另外registerMap是全局的在单页应用里如果组件销毁时不清理反复挂载会一直往内存里堆。GeoJSON 的体积也要关注。全国省级的 GeoJSON 精简后通常几百 KB市级或更细粒度的动辄几 MB。我的做法是在构建阶段把它转成 JSON 模块并做简化比如用工具降低坐标点精度或者干脆在服务端按需裁剪后返回别把一份全量数据塞进首屏包里。3. 自定义图标的四条路怎么选3.1 image:// 位图方案视觉最自由坑也最多最直观的做法就是symbol: image://路径。设计给了什么图就用什么图渐变、阴影、立体感全都能保留这是大屏场景的标配。{ type: scatter, coordinateSystem: geo, geoIndex: 0, symbol: image:///static/icons/warehouse.png, symbolSize: [36, 44], data: [ { name: 点位A, value: [116.40, 39.90, 128] }, { name: 点位B, value: [121.47, 31.23, 96] } ] }这条路的问题集中在三点。第一是尺寸失真symbolSize对图片是直接给定宽高的图片会按这个尺寸拉伸比例不对就变形所以宽高比必须和原图一致。第二是清晰度ECharts 会按浏览器的devicePixelRatio渲染画布symbolSize写的是逻辑像素在 2 倍屏上等于被放大了两倍1 倍图必糊。第三是跨域图片来自其他域且没做跨域许可时画布会被污染导出图片getDataURL会直接失败。3.2 path:// 矢量方案颜色可控、体积为零path://后面接一段 SVG 的路径数据ECharts 会把它当路径填充渲染。最大的好处是能被itemStyle.color染色同一套图标可以用不同颜色表达不同状态还不用额外请求。{ type: scatter, coordinateSystem: geo, geoIndex: 0, symbol: path://M512 64C264.6 64 64 264.6 64 512c0 247.4 200.6 448 448 448s448-200.6 448-448S759.4 64 512 64z, symbolSize: 22, itemStyle: { color: #ff7a45, borderColor: #ffffff, borderWidth: 1.5 } }注意这里用的是填充色所以 SVG 路径最好是从设计软件里导出“合并后的实心轮廓”而不是一堆带描边的线条。路径里如果有多个子路径会按同一个填充规则统一上色。另外path://的坐标系是 1024×1024 的视口路径数据超出这个范围会被裁掉拿到的图标如果显示不全八成是这个原因。和它配套的还有symbolKeepAspect设成true时图标会保持原始宽高比不拉伸在symbolSize写成单值时特别有用。3.3 字体图标与雪碧图省请求的两种打法如果项目里本来就有图标字体比如各种 iconfont可以直接用文字符号当symbol。这种方式的好处是颜色、大小全靠itemStyle和fontSize控制跟着主题走。缺点是字体文件本身就有一两百 KB而且图标的视觉风格受限于字体库。雪碧图方案适合“图标种类固定但数量多”的场景把十几张小图拼成一张大图用 CSS 式的偏移量去取。ECharts 的symbol不支持背景定位所以这条路要配合graphic组件或者自己写一个自定义系列实现成本偏高。我自己的项目里用得不多除非点位规模真的到了几千级别且图片资源很多否则不划算。3.4 选型对照表方案视觉表现是否可染色清晰度额外请求适用场景image://位图最强支持渐变阴影否需 2 倍图每类图标一个请求大屏、图标种类少path://矢量中等纯色填充是无损无后台分析、状态着色字体图标取决于字库是无损字体文件已有图标库的项目雪碧图强否需 2 倍图一个请求图标种类极多的场景选的时候问自己两个问题图标需不需要按数据变颜色点位规模是不是超过两百答案确定了方案基本也就定了。4. 完整实现从底图到可点击的图标4.1 容器与初始化容器必须给明确高度这是新手最常犯的错。div没有高度时 ECharts 初始化出来的画布是 0 高现象就是“图没出来”控制台却干干净净。div idchart stylewidth: 100%; height: 640px;/divconst chart echarts.init(document.getElementById(chart), null, { renderer: canvas, devicePixelRatio: window.devicePixelRatio || 1 });renderer我基本只选canvas。svg渲染器在图标数量少、需要矢量导出时有用但遇到大量图片符号时性能反而不如 canvas而且部分滤镜效果不支持。4.2 散点系列的核心配置下面这段是我项目里比较通用的一份骨架把常用参数都摆出来了const iconMap { warehouse: image:///static/icons/warehouse.png, store: image:///static/icons/store.png, site: image:///static/icons/site.png }; const option { tooltip: { trigger: item, confine: true, backgroundColor: rgba(8, 22, 40, 0.92), borderColor: #2c5f9e, textStyle: { color: #dbe9ff, fontSize: 12 }, formatter: (p) { const [lng, lat, val] p.value; return div styledisplay:flex;align-items:center;gap:8px; img src${p.data.icon} stylewidth:20px;height:24px; / b${p.name}/b /div div stylemargin-top:6px;指标值${val}/div div经纬度${lng.toFixed(2)}, ${lat.toFixed(2)}/div ; } }, geo: { map: myMap, roam: true, zoom: 1.2, aspectScale: 0.8, itemStyle: { areaColor: #0f2544, borderColor: #2c5f9e, borderWidth: 1 }, emphasis: { itemStyle: { areaColor: #1b3b66 } } }, series: [ { name: 业务点位, type: scatter, coordinateSystem: geo, geoIndex: 0, zlevel: 2, symbol: (value, params) iconMap[params.data.type] || iconMap.site, symbolSize: (value, params) (params.data.level core ? [40, 48] : [28, 34]), symbolOffset: [0, -50%], itemStyle: { opacity: 1 }, emphasis: { scale: 1.15 }, selectedMode: single, select: { itemStyle: { borderColor: #ffd666, borderWidth: 2 } }, data: [ { name: 点位A, value: [116.40, 39.90, 128], type: warehouse, level: core, icon: /static/icons/warehouse.png }, { name: 点位B, value: [121.47, 31.23, 96], type: store, level: normal, icon: /static/icons/store.png } ] } ] };这里有几个关键点值得单独说。symbol和symbolSize都支持函数回调第一个参数是数据项的值第二个参数是带data的对象所以可以直接按业务类型选不同的图标和尺寸一套系列搞定多种点位不用拆成五个系列。zlevel: 2让图标的画布层压在底图之上避免某些环境下被地图区域盖住。emphasis.scale是悬停放大注意它只在鼠标上有效触摸设备上要点一下才有反馈。4.3 symbolOffset 的换算图标为什么会“飘”这是最高频的问题没有之一。ECharts 的符号默认以坐标点为中心绘制也就是说如果你放一个 40×48 的图钉图片它的中心会落在经纬度对应的位置上视觉上整个图标就往上飘了半个高度图钉的尖端并没有指向目标点。解决办法是symbolOffset: [0, -50%]。这里的百分比是相对于symbolSize的-50%就是把图标整体上移自身高度的一半这样图标底部就正好压住坐标点。如果你用的是圆形图标、想让它居中就别加这个偏移用的是小旗子、路锥这类“底部为锚点”的图标就必须加。横向偏移同样道理。有些图标在设计时右侧有多余留白视觉重心偏左就得用[2, -50%]这种组合微调。我的经验是先按图标实际视觉锚点算再用肉眼在校验点上校准一次别指望公式一次到位。还有一点容易被忽略symbolOffset的百分比基准是符号尺寸当你用函数让不同点位有不同大小时同一个百分比会产生不同的像素位移——这恰好是我们想要的因为大图标的偏移量本来就该更大。4.4 交互点击、选中与联动点击事件的params里带componentType、seriesIndex、data拿数据很方便chart.on(click, (params) { if (params.componentType ! series) return; const { name, value, type } params.data; openDetailPanel({ name, lng: value[0], lat: value[1], type }); }); chart.on(georoam, () { // 缩放拖拽后做尺寸自适应见 5.2 });需要注意的是geo本身也会触发点击点在空白区域时componentType是geo如果不做判断用户点地图空白处也可能弹出面板。加一行判断就能避免。选中态用的是selectedModeselect注意select样式对图片符号的效果有限borderColor只会作用在符号外框上对image://的图片是画不出来的。想让选中效果明显我的做法是额外叠一个effectScatter系列选中时只把这一条数据喂进去用涟漪动画做高亮反馈视觉上比改边框强得多。5. 视觉打磨不糊、不飘、不打架5.1 高清屏上的位图清晰度ECharts 初始化时会把devicePixelRatio传给画布2 倍屏上画布实际像素是 CSS 尺寸的两倍。这意味着你写symbolSize: [36, 44]时图片在画布上占了 72×88 的物理像素1 倍图被插值放大边缘必然发虚。做法很直接图标源文件按最大展示尺寸的 2 倍准备也就是显示 36×44 就切 72×88 的图。这样在 2 倍屏上一比一映射3 倍屏会轻微放大但肉眼可接受。如果再往上堆 3 倍图体积会失控收益不成正比。还有一种更省的做法用 SVG 图片文件当symbol。现代浏览器支持 SVG 作为图片源ECharts 通过image://加载时不做特殊处理但浏览器本身会做矢量渲染缩放不糊体积还小。这条路我实测在主流浏览器上没问题唯一要注意的是 SVG 里别引用外部字体或图片否则会加载失败。5.2 缩放拖拽时图标尺寸的处理geo.roam打开之后地图可以缩放。这里有个反直觉的现象地图放大了图标尺寸却不变。原因是symbolSize的单位是逻辑像素与地图的缩放级别无关。视觉上的结果就是地图细节越来越大图标相对越来越小最后变成一堆小点。如果产品要求“图标随地图等比缩放”就得自己监听georoam事件读当前zoom值动态改写symbolSizelet baseSize 36; let rafId null; chart.on(georoam, () { if (rafId) cancelAnimationFrame(rafId); rafId requestAnimationFrame(() { const opt chart.getOption(); const zoom opt.geo[0].zoom || 1; const nextSize Math.round(baseSize * Math.min(zoom, 2.2)); chart.setOption({ series: [{ symbolSize: [nextSize, Math.round(nextSize * 1.2)] }] }); }); });注意三点。用requestAnimationFrame做节流不然拖拽一次会触发几十次setOption直接卡死。setOption时只传要改的字段别把整个option重新塞一遍那样会触发全量重绘。给缩放上限设个阈值上面写的2.2避免放大到极限时图标大得像贴纸。反过来如果产品希望图标始终固定大小大多数分析型页面的选择那就什么都不用做反而要保持symbolSize是常量。5.3 重叠、遮挡与图例配合点位密集时图标会互相压盖尤其在经济活跃、点位扎堆的区域。三个应对思路第一按重要度控制绘制顺序。ECharts 的散点按数据顺序绘制后画的压在先画的上面所以把核心点位排在数组末尾就能浮在最上层。第二用大小和透明度做层次。核心点位大且不透明次要点位小而半透明视觉上自然分层。第三真的挤不下就聚合。可以按经纬度网格做一次分桶同一格子里的点位合并成一个显示数量气泡点击后再展开。这一步需要自己写预处理逻辑官方没有现成的聚合能力。图例这块也有个坑legend绑定的是系列名不是数据项名。你想通过图例控制“仓库/门店/施工点”的显隐用单个系列是做不到的必须拆成多个scatter系列每个类型一个name分别对应图例项。这是设计上必须提前决策的点——想省事就用单系列 函数式symbol想灵活筛选用多系列两者不可兼得。6. 性能点位从 20 个涨到 2000 个6.1 卡顿的真实来源第一次遇到大数据量时我以为是数据太多后来逐项测下来真正的瓶颈往往不是数据量本身而是这几处大量图片解码。每个image://图标都要走一次图片加载即使浏览器有缓存几百个不同的 URL 也会产生明显开销。解决办法是把图标数量压到个位数或者干脆用path://。zlevel 分层过多。每多一个zlevelECharts 就多创建一块画布内存和合成开销都涨。分层控制在两层以内geo一层、标记一层就够了。tooltip 里的 HTML 太重。formatter返回一大段带img的 HTML鼠标快速划过时会频繁重建 DOM掉帧非常明显。可以在 tooltip 里只放文字图片交给别的地方展示或者给img加上固定的宽高避免布局抖动。频繁 setOption。任何在mousemove、georoam里直接调setOption而不做节流的代码都是性能杀手。6.2 降级策略与实测数据我在一个中等规模的项目上做过一轮压测配置是geo底图 单个scatter系列 2 倍图 PNG 图标容器 1440×800在普通办公本上得到大致这样的体感点位数量首屏渲染拖拽缩放处理方式50 以内无感知流畅直接用位图图标200 左右约 200ms轻微掉帧图标改path://减少 tooltip 复杂度500 左右约 500ms明显卡顿分级显示缩小视图只留核心点1000 以上超过 1s不可用必须聚合或分区域按需加载这组数字会随设备和图标复杂度浮动但量级关系是可靠的。我的降级顺序是先换矢量图标再减少同时可见的点位最后才考虑聚合。聚合虽然效果最好但实现成本和交互复杂度都高能不做就不做。另外一个实用技巧是初始化时先只渲染核心点位等chart.on(finished)之后再追加次要点位。用户的感知是“图先出来了细节慢慢补上”体验比白屏等两秒好得多。7. 常见问题排查实录7.1 图标不显示或者显示成方块按发生概率排原因依次是路径写错相对路径的基准是页面 URL 而不是 JS 文件位置、跨域被拦、图片尺寸为 0、symbolSize被设成了0。排查顺序我一般这么走先把symbol换成circle如果圆点能出来说明坐标系和系列配置没问题问题在图标本身再把图片 URL 直接贴到浏览器地址栏能打开说明路径没问题打不开就是路径或权限问题最后看控制台的网络面板有没有 404 或 CORS 报错。symbol写成函数时还有一种隐蔽的坑回调返回了undefined。比如用iconMap[params.data.type]取值而某个数据项的type拼错了就会拿到undefinedECharts 不报错直接画个默认方块或者什么都不画。建议在回调里加个兜底iconMap[type] || iconMap.default。7.2 图标位置整体偏移先分清是“整体偏了一个方向”还是“某个区域偏”。整体偏移最常见的原因是symbolOffset没配。如前所述符号默认以中心对齐底部锚点的图标会整体上浮半个身位看起来就像“所有点都往北移了”。加[0, -50%]立刻正常。如果偏移量很小但普遍存在怀疑坐标基准不一致。不同来源的地理数据可能用了不同的坐标系混用之后会产生几百米级别的系统性偏移在城市级别的地图上一眼就能看出来。解决办法是统一数据源或者在入库前做一次坐标转换别在渲染层做偏移修正——那是治标不治本。如果只有部分区域偏那基本可以断定是那份 GeoJSON 的特殊区域处理没做对。ECharts 支持specialAreas配置用来手动指定某些区域的位置跨区域展示时经常需要它。7.3 缩放后图标糊了 / 错位了糊了是因为位图分辨率不够参考 5.1换 2 倍图或 SVG。错位了先检查有没有在georoam里做了setOption但没做节流导致中途某次更新用了旧的zoom值。还有一种更隐晦的错位在roam过程中如果同时存在多个geo组件比如画中画小地图getOption()拿到的zoom是全部geo的数组你得按下标取对那个。用opt.geo[0]还是opt.geo[1]取错了图标就会按错误的比例缩放看起来像位置飘了。7.4 问题速查表现象最可能的原因快速验证处理方式整张图空白容器无高度检查div的 computed height给容器显式高度只有底图没有图标coordinateSystem未设或geoIndex错把 symbol 改成 circle 看能否出现补全coordinateSystem: geo图标是方块图片加载失败地址栏直接访问 URL修路径或加兜底图标全部上浮未设symbolOffset注释掉偏移观察变化加[0, -50%]图标拉伸变形symbolSize比例与图不符对比原图宽高比按比例改尺寸高清屏发虚1 倍图在 2 倍屏渲染放大浏览器检查换 2 倍图或 SVG缩放后图标相对变小symbolSize不随 zoom 变缩放前后对比监听georoam动态调整点位密集处互相遮挡数据顺序与层级问题按重要度排序后重绘调数据顺序 分层尺寸导出图片失败图片跨域污染画布看getDataURL是否报错同域部署或加跨域头拖拽时卡顿严重georoam里无节流看事件触发频率加requestAnimationFrame一些在实际使用中总结出的体会做这类图时间长了会发现真正难的不是把图标画出来而是把它画得在每台设备上都对。我自己踩得最狠的一次是上线后才发现图表在导出的截图里图标全丢了原因就是图片跨域污染了画布而本地开发环境是同域所以从来没暴露过。后来我养成了一个习惯凡是涉及外部图片的图表上线前一定要在真实域名下走一遍导出流程这个检查只要两分钟能省掉一次深夜回滚。还有一个小技巧可以分享把图标资源集中在一个常量对象里管理并且给每个类型都留一个default兜底。数据是后端给的字段值拼错、新增了没登记的类型这些都是家常便饭一个兜底图标能让页面在数据出问题时依然可读而不是一片空白。图表的健壮性往往不体现在正常流程而体现在脏数据到来时它还能不能站住。