1. 需求拆解geo 地图的动态选中态到底难在哪1.1 一个很常见的大屏需求场景先说需求本身。做数据可视化大屏的人大概都遇到过这类交互页面左边是一列省份按钮或者一个下拉框右边是一张 echarts 中国地图用户点了广东地图上的广东要立刻变色、加边框、甚至加一层发光效果同时其他地方要保持原样再点江苏广东恢复江苏亮起来。如果开了多选那就是点过的省份全部保持高亮不点则恢复默认。这事儿的核心关键词就三个echarts、geo、指定高亮显示区域而落地手段就是select。很多人第一反应是改itemStyle.areaColor或者用dispatchAction({type:highlight})这两种做法都能看起来实现了但一旦叠加缩放、拖拽、数据刷新、图表 resize各种状态错乱就冒出来了。我见过最典型的一个 bug用户点选省份后把地图放大高亮区域的位置整体偏了——因为用regions动态改itemStyle会破坏 ECharts 内部的区域索引roam 变换后就对不上了。所以这个需求看起来简单实际上是选中态管理这一个细分问题。ECharts 从 5.0 开始给 geo 组件和 map series 都补上了独立的select配置体系专门解决这件事。如果你的项目还锁在 4.x那这套东西是完全不存在的这一点必须先确认清楚我后面会专门讲。1.2 关键词歧义搜select之前先带上上下文顺带提个真实体验。select这个词在技术圈的歧义大得离谱搜出来的东西能让你怀疑人生select语句、insert into select、select top 1000 * from、C 的select使用、select replace(getdate(),-,_)甚至还有某些同名的游戏。同样geo这个词也一样你搜 geo 出来的可能是地理信息数据挖掘流程也可能是海外营销领域的生成式内容优化概念。所以找资料的时候索引词一定要拼全echarts geo select、echarts 地图 选中高亮、geoselectchanged。只丢一个select进去检索结果基本没法用。这个习惯我在带新人的时候反复强调能省掉大量时间。1.3 高亮方案横向对比为什么最终要落到 select 上在动手前把可选方案摆出来对比一遍比直接抄代码更值。下面这张表是我自己踩完坑后总结的方案触发方式状态是否持久多选支持主要问题regions[].itemStyle静态改色初始化 / 重新 setOption持久自己维护每次都要重绘动画生硬与 roam 变换耦合emphasis悬停态鼠标 hover不持久否语义是强调不是选中鼠标移开就没了dispatchAction的 highlight / downplay代码触发半持久可ECharts 4 时代的方案setOption 后常丢失需要反复重发select选中机制点击 /geoSelectaction由 ECharts 维护可multiple需要 ECharts 5.0且容易和 emphasis 混淆我的结论很明确只要需求里出现选中这个词——即状态需要被记住、需要被外部读取、需要和别的组件联动——就应该用 select而不是拿 emphasis 或者 highlight 去凑。select 有自己的样式层、自己的开关selectedMode、自己的初始态写法regions[].selected和自己的事件geoselectchanged这四点恰好是选中态该有的全部要素。1.4 select 和 emphasis 的本质区别这两个配置长得像很多人会混着写结果样式互相打架。它们的差别在语义层emphasis描述的是瞬时交互反馈鼠标移上去有、移开就没有它不参与任何状态管理也不会有事件。select描述的是可保持的状态它有独立的itemStyle、label、disabled三个子项样式优先级高于普通itemStyle并且能被dispatchAction读改。当两者同时命中一个区域比如鼠标既悬停又处于选中状态ECharts 会优先渲染emphasis的样式松开后回落到select样式。这个渲染顺序不要搞反了否则你会看到选中后突然变色又变回来的诡异现象。我的做法是尽量让两套样式在色相上拉开距离比如选中用暖色高亮悬停用同色系的浅一档这样叠加时不会突兀。2. geo.select 的配置项逐个掰开讲2.1 select 里到底能写什么geo 组件下的select接收三个字段itemStyle、label、disabled。就这么简单但每一项都有细节。select.itemStyle支持常规的区域样式areaColor填色、borderColor描边、borderWidth描边宽度还支持shadowBlur/shadowColor做外发光。发光效果在大屏上特别出效果但要注意shadowBlur是逐区域计算的地图上区域越多开销越大。我一般把shadowBlur控制在 20 以内配一层半透明的shadowColor视觉上就够了。select.label是选中后区域名称的文字样式。这里有个高频坑geo 的label.show默认是 false你只写select.label.color是看不到字的必须在select.label里显式写show: true。我见过不少人卡在这里以为是 select 没生效其实是标签压根没开。select.disabled是个布尔值设成 true 之后该组件不再响应选中连dispatchAction发过来的 geoSelect 都会被忽略。这个字段在临时锁定交互时很好用比临时把selectedMode改成 false 再改回来更干净。2.2 selectedMode 决定能不能选不是怎么选geo.selectedMode取值是false | single | multiple。geo 组件下它的默认值是 false这一点非常关键你不写这一行select配置写得再漂亮也不会生效点击地图毫无反应dispatchAction也像石沉大海。我个人的默认选择是single因为大屏上的重点区域通常只有一个单选能让状态机简单一半。需要多选再切multiple但要注意多选模式下的状态维护成本会陡增尤其是要和外部按钮列表双向同步的时候。还有一点容易忽略selectedMode会受geo.silent影响。如果silent: truegeo 不响应任何鼠标事件点击选中自然不会触发但dispatchAction发起的程序化选中仍然有效。这个组合适合只允许代码控制、不允许用户乱点的场景。2.3 初始选中regions[].selected 的正确写法页面刚加载就要让某个省份亮起来最直接的写法是在regions数组里加selected: truegeo: { map: china, selectedMode: single, regions: [ { name: 广东, selected: true }, { name: 江苏, selected: false } ], select: { itemStyle: { areaColor: #ffd166 }, label: { show: true, color: #1a1a1a } } }这里有个必须记住的细节regions里的字段叫selected而组件级的配置项叫select一个带 d 一个不带。这个字母差异坑过无数人写错了不会报错只是安静地不生效。另外regions[].itemStyle的优先级高于组件级itemStyle但低于select.itemStyle。也就是说如果某个区域既在regions里配了itemStyle又处于选中状态最终显示的是select.itemStyle。这个优先级链建议记牢出问题的时候能快速定位是哪一层覆盖了哪一层。2.4 geoselectchanged把选中结果读出来选中态光能写不够还得能读。ECharts 提供了geoselectchanged事件chart.on(geoselectchanged, function (params) { console.log(params); // 回调里能拿到当前选中区域的名称集合 });回调的 payload 里通常包含geoIndex、name、selected这几个字段其中name和selected是当前被选中区域的名称集合。不同小版本之间这个结构略有出入我的习惯是先console.log打一遍确认再写业务逻辑别照着老版本的文档硬套。这里必须提醒一句不要依赖chart.getOption().geo[0].regions去反查当前选中了谁。这个路径读出来的往往是初始配置的快照dispatchAction改动的选中态不一定同步回getOption的返回值。稳妥做法是自己用变量维护一份选中列表事件回调里更新它业务逻辑只认这份变量。3. 动态高亮的三种触发路径3.1 程序化触发geoSelect 的三个动作ECharts 给 geo 组件配了三个 actiongeoSelect把指定区域设为选中geoUnSelect取消指定区域的选中geoToggleSelect在选中与未选中之间切换调用形态是这样的chart.dispatchAction({ type: geoSelect, geoIndex: 0, name: 广东 });geoIndex指定操作的是第几个 geo 组件页面只有一个 geo 的时候写 0 就行name是区域名称必须和 GeoJSON 里properties.name完全一致。这个完全一致包括繁简、全称简称、前后空格任何一个字符对不上action 就会静默失败——不报错、不提示、什么都不发生。这是排查环节里最耗时间的一类问题。关于批量操作我的实测经验是单值调用最稳。想清空一片区域的选中不要指望geoUnSelect传数组能一把梭最保险的做法是循环发 action或者干脆走setOption更新regions的selected字段。批量发 action 会触发多次渲染区域数量少无所谓上百个区域就会有肉眼可见的卡顿这时候setOption一次性提交反而更快。3.2 外部控件驱动地图下拉框与按钮组下拉框联动的写法很直白核心是先清旧、再选新顺序不能反否则单选模式下 ECharts 自己会帮你清但你会丢失之前的状态记录let currentSelected null; selectDom.addEventListener(change, function (e) { const next e.target.value; if (currentSelected currentSelected ! next) { chart.dispatchAction({ type: geoUnSelect, geoIndex: 0, name: currentSelected }); } chart.dispatchAction({ type: geoSelect, geoIndex: 0, name: next }); currentSelected next; });这里有个细节值得说单选模式下即使你不发geoUnSelect选中新区域时旧区域也会自动取消。但自动取消不会触发一次独立的 geoselectchanged 事件来告诉你谁被取消了回调里只给你新的选中集合。如果你的外部 UI 需要精确知道上一个是谁就必须自己维护currentSelected。这个变量看着多余实际上省掉了很多状态推断的麻烦。3.3 反向驱动地图点击回写外部状态用户直接点地图外部的下拉框要跟着变这是双向绑定的另一半chart.on(geoselectchanged, function (params) { const names params.name || []; currentSelected names[0] || null; selectDom.value currentSelected || ; refreshSidePanel(currentSelected); });这段代码里隐藏了一个经典陷阱由外部 dispatchAction 引发的选中同样会触发 geoselectchanged。也就是说你在下拉框的 change 回调里发 actionaction 又回调到 geoselectchangedgeoselectchanged 里再去改下拉框的值。如果不加判断就会出现代码设值触发事件、事件又设值的循环风险。处理方式有两种一是加一个isProgrammatic标志位在发 action 前置 true、事件回调里判断后复位二是在事件回调里先比对当前值值没变就不往下走。我通常用第二种代码更短副作用也更小。4. 完整实操从零搭一个可切换的中国地图4.1 地图数据准备与注册先解决数据源。ECharts 5 之后官方不再内置中国地图数据需要自己准备一份 GeoJSON然后注册import chinaGeoJson from ./china.json; echarts.registerMap(china, chinaGeoJson);注册名china后面要在geo.map里对应引用两个字符串必须一致。这里最容易出问题的不是注册本身而是GeoJSON 里的区域命名和你业务数据里的命名不一致。GeoJSON 里可能写的是广西壮族自治区、新疆维吾尔自治区、香港特别行政区而你的后端接口返回的是广西、新疆、香港。名称对不上dispatchAction就找不到目标区域。ECharts 提供了nameMap来做映射可以直接在 geo 里写geo: { map: china, nameMap: { 广西壮族自治区: 广西, 新疆维吾尔自治区: 新疆, 香港特别行政区: 香港, 澳门特别行政区: 澳门 } }nameMap的键是 GeoJSON 里的原名值是显示名。注意映射之后dispatchAction里的name要用映射后的名字因为注册进 ECharts 内部的区域名已经被替换了。这一条我踩过当时对着 GeoJSON 原文找了半小时最后发现要用映射名。提示改完nameMap之后如果选中始终不生效最省时间的排查方式是先在geoselectchanged里打日志看看手动点击时回调里的name到底是什么照着那个字符串写代码基本不会错。4.2 初始化 option 与事件绑定下面是完整的一份可直接跑的配置我把关键行都加了注释const chart echarts.init(document.getElementById(map)); const option { tooltip: { trigger: item, formatter: {b} }, geo: { map: china, roam: true, zoom: 1.15, center: [104, 36], selectedMode: single, label: { show: true, fontSize: 10, color: #b9c8e4 }, itemStyle: { areaColor: #0d1b34, borderColor: #2b4b7e, borderWidth: 1 }, emphasis: { // 悬停态浅一档的同色系 label: { show: true, color: #ffffff }, itemStyle: { areaColor: #1b3a6b } }, select: { // 选中态暖色 外发光 disabled: false, label: { show: true, color: #1a1a1a, fontWeight: bold }, itemStyle: { areaColor: #ffd166, borderColor: #fff3c4, borderWidth: 1.5, shadowBlur: 16, shadowColor: rgba(255, 209, 102, 0.7) } } } }; chart.setOption(option);配色上我是这么想的底图用深蓝悬停用比底图亮一档的蓝选中用完全不同的暖黄色。这样三层状态在深色大屏上层次分明用户一眼就能分辨我点了哪个。如果悬停和选中都用暖色视觉上就分不清了体验会很糊。写完之后先别急着接业务逻辑手动点两下地图确认三件事点击有变色、鼠标移开颜色保持在选中色、标签正常显示。这三件事都过了说明基础配置没问题可以往上叠交互了。4.3 状态管理与 setOption 的正确姿势真正让高亮状态出问题的几乎都是setOption。数据刷新时重新调用setOption如果没有把选中态一起带进去ECharts 会按新 option 里的regions重新算选中态就丢了。我的做法是把选中列表做成唯一数据源每次setOption前重建regionsfunction buildRegions(selectedList) { return selectedList.map(function (name) { return { name: name, selected: true }; }); } function refresh(newData) { chart.setOption({ series: newData.series, geo: { regions: buildRegions(selectedList) } }); }注意这里setOption只提交了变化的部分ECharts 默认走 merge 模式没提交的配置会保留。这是好事也是坑好处是不用每次都写完整 option坑在于你如果在新 option 里显式写了regions: []那就等于把所有选中态清空了。所以刷新数据时要么不提regions要么把当前选中态一起提上去不要写个空数组了事。还有一点setOption的第二个参数控制是否不合并日常业务我强烈建议保持默认的合并行为notMerge: true用在高频刷新的图表上会带来整图重绘选中态和 roam 视角都会被重置得不偿失。4.4 多选、清空与全选切换到selectedMode: multiple后选中的维护逻辑要换成数组。这里有几个常用操作的标准写法// 追加选中一个 function addSelect(name) { if (selectedList.indexOf(name) -1) { selectedList.push(name); } chart.dispatchAction({ type: geoSelect, geoIndex: 0, name: name }); } // 取消一个 function removeSelect(name) { const idx selectedList.indexOf(name); if (idx -1) { selectedList.splice(idx, 1); } chart.dispatchAction({ type: geoUnSelect, geoIndex: 0, name: name }); } // 清空全部 function clearAll() { selectedList.slice().forEach(function (name) { chart.dispatchAction({ type: geoUnSelect, geoIndex: 0, name: name }); }); selectedList []; }清空这块我特意用了slice()复制一份再遍历因为geoUnSelect触发的geoselectchanged回调有可能反过来修改selectedList直接在原数组上遍历会踩到索引错位。这个坑很隐蔽表现是明明点了清空还剩一两个区域亮着排查起来相当费劲。全选的性能要注意。中国地图省级单位 34 个全选没问题如果你的地图到了市级甚至区县级几百上千个区域循环发 action 就会明显卡。这种情况下我推荐放弃 dispatchAction改用setOption一次性把regions全部标成selected: true实测在 300 个区域量级下一次性提交比循环快一个数量级。5. 常见问题与排查速查5.1 select 完全不生效的几类原因按我遇到的频率排序第一是版本问题。select机制是 ECharts 5.0 才引入的如果你项目里锁的是 4.x无论怎么写都无效控制台还不会给任何提示。先在浏览器里echarts.version打一下确认是 5 开头再往下查。第二是忘记开selectedMode。geo 下它的默认值是 false必须显式写single或multiple。第三是区域名对不上。GeoJSON 原名和代码里写的不一致或者用了nameMap之后代码里还是写的原名。第四是把select写成了selected字母差一个静默失效。第五是**select.disabled被设成了 true**可能是之前调试时留下的。第六是地图silent为 true导致点击无效但程序化选中应该还是好的如果你发现点击和代码都无效那就不是这一条。5.2 状态丢失与事件重复触发状态丢失基本都跟setOption有关处理原则上面讲过了。这里补充一种更隐蔽的情况图表容器尺寸变化触发的 resize。chart.resize()本身不会重置选中态这点可以放心。但如果你的 resize 逻辑里顺手调了一次setOption很多响应式方案的通用写法那就把状态一起重置了。所以 resize 回调里只调resize()别夹带私货。事件重复触发的问题通常出在监听器被重复绑定。比如在一个 Vue 组件里onMounted里绑了geoselectchanged但组件被缓存或者热更新时又绑了一次同一次点击就会触发两遍业务逻辑。解决办法是在绑定前先chart.off(geoselectchanged)清一遍或者在组件卸载时严格解绑。5.3 问题速查表现象最可能的原因处理方式点击地图完全没反应未设置selectedMode显式设single或multipleselect 配置全写了也不变色ECharts 4.x升级到 5.x代码发 action 无反应区域名与注册名不一致打日志确认实际 name必要时配nameMap选中后看不到文字select.label.show未开显式设show: true悬停与选中颜色混乱emphasis 与 select 样式太接近两套样式拉开色相差异数据刷新后高亮消失setOption未携带regions提交前重建regions选中列表resize 后高亮消失resize 回调里夹带了setOption回调里只调resize()一次点击业务逻辑跑两遍事件监听器重复绑定绑定前先off卸载时解绑全选时明显卡顿循环发 action改为一次setOption提交 regions注意排查顺序建议从版本 → selectedMode → 区域名 → 配置字母这个链条走前四项能覆盖九成以上的问题比你漫无目的地翻文档快得多。6. 进阶玩法与几个容易被忽略的细节6.1 geo 组件与 map series 别混着用选中这是我在一个项目里被坑得最惨的一次。当时地图上既要显示省份底色又要显示一些散点表示数据采集点于是用了 geo 做底图、series 用type: scatter配coordinateSystem: geo。这套组合本身没问题选中也走 geo 的geoSelect。但如果你的 series 是type: map、并且通过geoIndex挂到了 geo 上那就变成了两个组件共享同一张地图选中逻辑会走 series 的selectaction而不是 geo 的geoSelect。两套 action 名字不一样// geo 组件 chart.dispatchAction({ type: geoSelect, geoIndex: 0, name: 广东 }); // map series chart.dispatchAction({ type: select, seriesIndex: 0, name: 广东 });判断该用哪一个的简单办法看你的选中视觉是从哪儿来的。如果select配在geo里就用geoSelect配在series里就用select。两个都配了的话以实际渲染的那一层为准另一个是无效配置。我的建议是一个页面只保留一种选中机制的载体。要么纯 geo要么纯 map series别两边都配select不然维护成本翻倍而且很容易出现改了这边忘了那边的样式不一致。6.2 地图下钻与返回时的状态保持下钻是很常见的功能点某个省地图切换到该省的市级 GeoJSON点返回再切回全国。这时候选中态怎么处理我见过两种做法。一种是下钻时清空所有选中返回时也不恢复简单但用起来割裂。另一种是维护一个层级栈把每一级的选中列表存下来返回时按层级恢复。我推荐后者实现也不复杂const levelState { china: [广东], guangdong: [深圳, 广州] }; function goBack() { currentLevel china; echarts.registerMap(china, chinaGeoJson); chart.setOption({ geo: { map: china, regions: buildRegions(levelState.china) } }); }注意registerMap可以重复调用同名注册会覆盖这个特性让下钻切换很顺手。但切换时一定要把regions换成对应层级的状态否则上一级的区域名会带到下一级去ECharts 找不到就会忽略表现是返回后高亮莫名其妙没了。6.3 与折线图、饼图联动的收尾处理选中一个省旁边的折线图跟着切数据这是大屏最常见的联动。实现上没什么难点在geoselectchanged里调接口或者从本地缓存取数然后更新其他图表实例就行。真正要注意的是空选状态的兜底。用户取消选中之后折线图该显示什么全量数据还是清空这个必须先定好不能留空。我的做法是取消选中时回落到全国汇总数据并给标题加一个全国的标识让用户明确知道自己现在看的是哪一层数据。另外tooltip的换行问题在联动面板里也会冒出来。区域名称加上数值拼起来太长tooltip 撑出屏幕。ECharts 的 tooltip 支持formatter返回 HTML 字符串我一般会在 formatter 里手动插br/控制换行位置比让其自动换行可控得多。这个小技巧和大屏整体体验关系很大值得单独花十分钟调一下。6.4 一点性能上的个人经验最后说性能。区域数量在 34 个以内省级上面所有写法都不需要优化怎么写都快。区域数量上到几百市级要注意三点第一别在geoselectchanged里做重活。这个事件在快速连续点击时会连续触发如果回调里同步发了网络请求很容易出现请求竞态。加一个请求序号只认最后一次的结果。第二shadowBlur慎用。发光效果好看但每个选中区域都要算一遍阴影多选模式下选中十几个区域时帧率能掉到肉眼可见的卡顿。替代方案是用borderColor加粗描边视觉上接近开销小很多。第三roam缩放时的渲染压力主要来自地图矢量数据的复杂度和选中态关系不大但如果你的 GeoJSON 是超高精度的比如包含大量岛屿细节可以考虑用工具做一次简化文件体积能降下来不少首屏加载和缩放都更顺。在深色大屏上选中态用暖色、底图用冷色这个配色思路我用了好几个项目反馈都还不错用户不需要额外说明就能看懂哪块是被选中的。唯一要注意的是暖色的饱和度别太高纯亮黄在长时间盯着看的时候会有点刺眼稍微压一点明度配合一层柔和的外发光观感会舒服很多。