TuiEchartsMap

💎高级组件

🧊增强封装

⭐明星组件

v0.0.3+

TuiEchartsMap 是 TechUI 图表体系中的地理空间业务壳层 (Geospatial Business Shell)。

它不仅是一个用于承载地图的容器，更是一个智能的逻辑编排宿主。它采用了分离式架构设计，将 ECharts 原生的 GIS 渲染能力包裹在内部，并通过外层壳体接管了复杂的地图下钻路径管理、多维视图切换以及时间轴数据轮播等交互逻辑。

开发者无需关心底层的 GeoJSON 加载与坐标系重绘，只需通过这层“外壳”提供的标准接口（Pipeline），即可快速构建出具备企业级深度定制能力的地理可视化应用。

注意：本组件专注于 2D 矢量地图的高性能渲染（基于 SVG）。如需使用 3D 模式，请务必阅读文末的 3D 地图支持说明。

TuiEchartsMap 是组件库中7个高级组件之一，需要取得授权后使用。

核心架构 管道化处理

为了应对复杂的地图业务逻辑（如异步数据加载、下钻路径管理、动态样式计算），本组件采用了 MVC 分离式架构。index.vue 仅作为控制器（Controller），具体的业务逻辑通过 "Utils Pipeline" 进行流式处理。

推荐目录结构

建议将地图逻辑拆分为以下独立模块：

• Controller (index.vue): 负责状态管理 (reactive), 事件监听 (chartClick), 组件挂载。
• Pipeline Utils:
• 0.themeExtra.js: 主题与样式映射配置。
• 1.getMapData.js: 负责 GeoJSON 数据的异步获取与缓存策略。
• 2.processOption.js: 处理 ECharts geo 与 visualMap 等基础配置。
• 3.processData.js: 处理 series 数据（散点、Pin 图标、热力值）的生成与清洗。
• init.js: 组装上述模块的统一入口。

这种架构使得地图实例极易维护和扩展，实现了视图层与逻辑层的解耦。

远程示例说明

由于地图组件采用了管道化分离架构，涉及复杂的异步数据流与交互逻辑，不便在文档中单页展示。请前往 GitHub 或 Gitee 仓库的 Prime 测试用例 目录中查看完整的工程化源码。

核心功能特性

数据切换 (Data Switching)

组件支持在同一地图底图上动态切换不同的数据维度。

• 多形态标记：支持根据数据类型切换标记形态，例如从 散点 (Scatter) 切换到 带数值的 Pin 图标。
• 样式差异化：不同数据组可以配置完全不同的颜色方案、图标大小逻辑以及热力区域样式。
• 动态渲染：结合 updateReplace 机制，切换数据时无需销毁实例，可平滑过渡。

图层切换 (Layer Switching)

支持复杂的图层控制逻辑，满足多维度的可视化需求。

• 图元显隐：可以自由控制特定图层（如标点、特效散点、标签）的显示与隐藏。
• GeoJSON 覆盖：支持自定义 GeoJSON 图层叠加，用于显示特殊的地理边界或自定义区域。
• 模式切换：支持从“行政区划填充模式”（Choropleth）无缝切换至“地理描点模式”（Scatter/EffectScatter）。

时间轴 (Timeline)

集成时间维度的数据展示能力。

• 多维度演变：结合 ECharts Timeline 组件，展示数据随年份或时间段的变化趋势。
• 自动轮播：支持配置时间轴的自动播放，实现数据的动态演播效果。
• 图表联动：时间轴的变化可以同时驱动地图数据与关联图表（如右侧排行榜）的同步更新。

主题同步 (Theming)

深度集成 TechUI 全局主题系统。

• 全局响应：组件会自动监听 $gTheme 的变化，实时刷新地图配色。
• 精细化定制 (themeExtra)：通过 0.themeExtra.js 配置文件，您可以针对不同主题（DeepBlue, Light, Dark）单独定义地图区域颜色、边框色、高亮色以及 Pin 图标的渐变色。

地图下钻 (Drill-down)

内置开箱即用的层级交互能力。

• 交互式下钻：点击地图区域，自动加载下级行政区划数据并重绘地图。
• 面包屑导航 (breadcrumb)：顶部自动显示当前导航路径（如：全国 > 浙江省 > 杭州市），支持点击面包屑返回上级。
• 层级感知：组件内部维护 navBcrumb 状态队列，自动管理当前层级深度。

数据联动 (Data Linkage)

地图组件不仅仅是一个独立的视图，它通常作为整个大屏的**“上下文控制器 (Context Controller)”**。

• 状态监测：通过监听 navBcrumb 对象，父组件可以实时感知当前地图的导航深度与区域信息。
• 周边协同：当用户下钻至某一省份（如“浙江省”）时，您可以通过 watch 捕获最新的 adcode，并即时触发周边组件（如右侧排行榜、顶部统计卡片）的数据刷新，实现**“地图动，全屏动”**的联动体验。

详情气泡 (Popup Info)

支持丰富的信息展示交互。

• 触发方式：支持 click 手动触发或 interval 自动轮询弹出。
• 自定义内容：气泡内容完全由 Vue 组件渲染，支持复杂的 HTML 结构与业务逻辑。
• ⚠️ 组件说明：示例代码中仅通过 createPopover 演示了基本的 DOM 挂载逻辑，实际使用时请结合您项目中的基础 UI 组件库实现气泡样式。(如：TechUI Scifi 组件库不包含 PopInfo 或 PopTip 组件需自行开发相关的组件)

限制与说明

地图实例开放权限

• 测试用例：在Github和Gitee中，仅Prime组件库提供基础的地图展示实例，不包含完整的地图下钻逻辑与复杂交互源码。
• 授权版：完整的地图下钻、管道化架构及多视图切换的高级实例，属于企业级授权内容，需取得授权后方可查看与使用。

GeoJSON 数据来源

• 不提供数据：考虑到地图数据的时效性与测绘合规性，本组件库 不内置也不提供 任何 GeoJSON 文件。
• 获取方式：请开发者自行前往阿里云 DataV、高德开放平台或其他合规的开源数据平台下载所需的 GeoJSON 数据，并通过 1.getMapData.js 进行加载配置。

3D 地图支持说明 (风险提示)

虽然 TuiEchartsMap 理论上支持通过配置 echarts-gl 实现 3D 地球或 3D 地图效果，但我们 强烈建议谨慎使用，理由如下：

• 维护停滞：echarts-gl 组件库更新缓慢，且与 ECharts 5/6 版本的兼容性存在诸多已知问题。
• 交互缺失：在 3D 模式下，许多基础交互（如区域点击下钻、Tooltip 精确触发）可能无法正常工作或响应迟钝。
• 版本回退：若必须使用 3D 模式，通常需要将 ECharts 核心库回退至 v5.x 版本，这可能会影响项目中其他图表的特性使用。

API 参考

Props (属性)

除了地图特有的配置外，组件还完整透传了容器尺寸与渲染控制属性。

属性名	类型	默认值	说明
chartOption	Object	(Required)	图表核心配置对象。
geoJsonData	Object	(Required)	当前地图的 GeoJSON 数据对象。
mapName	String	(Required)	当前地图注册名称（如 'china'）。
allAreaCodes	Array	-	行政区划映射表，用于下钻时的名称-代码转换。
width	Number/String	-	容器宽度。
height	Number/String	-	容器高度。
renderer	String	'canvas'	渲染模式。推荐使用 'svg' 以获得最佳清晰度。
updateReplace	Boolean	true	更新数据时是否使用 replaceMerge 策略，用于平滑切换图层。
enableBreadcrumb	Boolean	false	是否启用内置的面包屑导航与下钻逻辑。
breadcrumbConfig	Object	{ data: [...], position: ... }	面包屑配置项（初始路径、位置坐标）。
loading	Boolean	null	加载状态控制 (支持 v-model:loading)。
ready v0.0.5+	Boolean	false	渲染控制信号。设为 true 时才开始初始化/渲染。
initOptions	Object	{}	ECharts 初始化附加参数 (如 devicePixelRatio, locale)。
resizeObserver	String	'global'	自适应策略。'self'(自身), 'global'(窗口), 'none'(禁用)。
dataOpacity	Number	-	数据层透明度（透传给底层渲染器）。
dataBlur	Number	-	数据层模糊度（透传给底层渲染器）。

移除的props

• 在v0.0.5移除过时的Props: initDelay 、initHold;

Events (事件)

组件转发了所有 ECharts 标准交互事件及地图特有逻辑事件。

事件类别	事件名	说明
交互事件	chartClick	单击地图区域或标记（常用于下钻）。
	chartDblClick	双击事件。
	chartMouseDown	鼠标按下。
	chartMouseUp	鼠标抬起。
	chartMouseOver	鼠标悬停（常用于高亮提示）。
	chartGlobalOut	鼠标移出图表容器范围。
	chartGeoRoam	地图漫游事件（缩放/平移），常用于同步更新气泡位置。
生命周期	chartInit	实例初始化完成。
	chartReady	图表首次渲染完成（包含动画）。
	chartRendered	每次渲染动作发生时触发。
	chartFinished	渲染动作完全停止时触发。
业务事件	chartUpdate	图表更新事件。
	chartTimelinechanged	时间轴节点切换事件。
	breadcrumbClick	点击面包屑导航时触发。
	update:loading	加载状态双向绑定更新。

Methods (方法)

可通过 ref 调用组件暴露的内部方法。

方法名	参数	说明
initChart	-	手动触发图表初始化流程。
setOption	(option, notMerge, lazyUpdate)	动态更新图表配置。
getChart	-	获取原始 ECharts 实例对象。
resize	-	强制触发图表尺寸重绘。
resetMapView	-	特有方法：重置地图的缩放比例与中心点到初始状态。
clear	-	清空当前实例画布。
dispose	-	销毁实例，释放资源。

致谢

Baidu EFE team

Github

Apache 软件基金会 (ASF)

Github

特别感谢 Echarts 项目的初创团队 百度 EFE (Baidu EFE) 致以诚挚的敬意，感谢他们创造了如此卓越的数据可视化开源标准。

感谢 Apache 软件基金会 (ASF) 对该项目的持续维护与管理。