TuiEchartsMap

💎Advanced

🧊Enhanced

⭐Star

v0.0.3+

TuiEchartsMap is the Geospatial Business Shell within the TechUI chart system.

It is not merely a container for hosting maps, but an intelligent logical orchestration host. It adopts a separated architecture design, wrapping ECharts' native GIS rendering capabilities internally, while the outer shell takes over complex interaction logic such as map drill-down path management, multi-dimensional view switching, and timeline data rotation.

Developers do not need to concern themselves with low-level GeoJSON loading and coordinate system redrawing. Through the standard interfaces (Pipeline) provided by this "shell", one can quickly build geospatial visualization applications with enterprise-level deep customization capabilities.

Note: This component focuses on high-performance rendering of 2D vector maps (based on SVG). If you need to use 3D mode, please be sure to read the 3D Map Support Notes at the end of this document.

TuiEchartsMap is one of the 7 advanced components in the library and requires authorization to use.

Core Architecture

To handle complex map business logic (such as asynchronous data loading, drill-down path management, dynamic style calculation), this component adopts an MVC Separated Architecture. index.vue acts only as the Controller, while specific business logic is processed in a stream via the "Utils Pipeline".

Recommended Directory Structure

It is recommended to split the map logic into the following independent modules:

• Controller (index.vue): Responsible for state management (reactive), event listening (chartClick), and component mounting.
• Pipeline Utils:
• 0.themeExtra.js: Theme and style mapping configuration.
• 1.getMapData.js: Responsible for asynchronous fetching and caching strategies for GeoJSON data.
• 2.processOption.js: Handles basic configurations like ECharts geo and visualMap.
• 3.processData.js: Handles the generation and cleaning of series data (Scatter, Pin icons, Heatmap values).
• init.js: The unified entry point for assembling the above modules.

This architecture makes map instances extremely easy to maintain and extend, achieving decoupling between the view layer and the logic layer.

Remote Example Note

Since the map component uses a pipelined separation architecture involving complex asynchronous data flows and interaction logic, it is inconvenient to display it on a single page in the documentation. Please visit the Prime Test Cases directory in the GitHub or Gitee repository to view the complete engineering source code.

Core Features

Data Switching

The component supports dynamic switching of different data dimensions on the same base map.

• Multi-form Markers: Supports switching marker forms based on data types, such as switching from Scatter to Pin Icons with values.
• Differentiated Styles: Different data groups can be configured with completely different color schemes, icon size logic, and heat area styles.
• Dynamic Rendering: Combined with the updateReplace mechanism, instances do not need to be destroyed when switching data, allowing for smooth transitions.

Layer Switching

Supports complex layer control logic to meet multi-dimensional visualization needs.

• Element Visibility: You can freely control the display and hiding of specific layers (such as markers, effect scatters, labels).
• GeoJSON Overlay: Supports custom GeoJSON layer overlays for displaying special geographical boundaries or custom areas.
• Mode Switching: Supports seamless switching from "Administrative Division Fill Mode" (Choropleth) to "Geographic Plotting Mode" (Scatter/EffectScatter).

Timeline

Integrated time-dimension data display capabilities.

• Multi-dimensional Evolution: Combined with the ECharts Timeline component, it displays trends in data changes over years or time periods.
• Automatic Rotation: Supports configuration of automatic playback for the timeline, achieving dynamic data presentation effects.
• Chart Linkage: Changes in the timeline can simultaneously drive the synchronized update of map data and associated charts (such as a ranking list on the right).

Theming

Deeply integrated with the TechUI global theme system.

• Global Response: The component automatically listens for changes in $gTheme and refreshes map color schemes in real-time.
• Refined Customization (themeExtra): Through the 0.themeExtra.js configuration file, you can individually define map area colors, border colors, highlight colors, and Pin icon gradient colors for different themes (DeepBlue, Light, Dark).

Map Drill-down

Built-in out-of-the-box hierarchical interaction capabilities.

• Interactive Drill-down: Clicking on a map area automatically loads the lower-level administrative division data and redraws the map.
• Breadcrumb Navigation (breadcrumb): Automatically displays the current navigation path at the top (e.g., National > Zhejiang Province > Hangzhou City), supporting clicking on breadcrumbs to return to the upper level.
• Hierarchy Perception: The component internally maintains a navBcrumb state queue to automatically manage the current hierarchy depth.

Data Linkage

The map component is not just an independent view; it usually serves as the "Context Controller" for the entire dashboard.

• State Monitoring: By listening to the navBcrumb object, the parent component can perceive the current map navigation depth and regional information in real-time.
• Peripheral Collaboration: When a user drills down to a certain province (e.g., "Zhejiang Province"), you can capture the latest adcode via watch and instantly trigger data refreshes for peripheral components (such as right-side rankings, top statistics cards), achieving a "Map moves, Full screen moves" linkage experience.

Popup Info

Supports rich information display interactions.

• Trigger Methods: Supports manual triggering via click or automatic polling popups via interval.
• Custom Content: The content of the popup is rendered entirely by Vue components, supporting complex HTML structures and business logic.
• ⚠️ Component Note: The example code only demonstrates basic DOM mounting logic via createPopover. In actual use, please implement popup styles in combination with the basic UI component library in your project (e.g., the TechUI Scifi component library does not include PopInfo or PopTip components; these need to be developed independently).

Limitations and Notes

Map Instance Permissions

• Test Cases: In Github and Gitee, only the Prime component library provides basic map display examples. It does not include complete map drill-down logic and complex interaction source code.
• Authorized Version: Advanced instances with complete map drill-down, pipelined architecture, and multi-view switching are part of the enterprise authorization content and can only be viewed and used after obtaining authorization.

GeoJSON Data Source

• Data Not Provided: Considering the timeliness of map data and surveying compliance, this component library does not build in nor provide any GeoJSON files.
• Acquisition Method: Developers are requested to download the required GeoJSON data from Alibaba Cloud DataV, Amap Open Platform, or other compliant open-source data platforms, and load/configure them via 1.getMapData.js.

3D Map Support Notes (Risk Warning)

Although TuiEchartsMap theoretically supports 3D Earth or 3D map effects by configuring echarts-gl, we strongly advise caution for the following reasons:

• Stagnant Maintenance: The echarts-gl library is updated slowly, and there are many known compatibility issues with ECharts versions 5/6.
• Missing Interaction: In 3D mode, many basic interactions (such as area click drill-down, precise Tooltip triggering) may not work properly or respond sluggishly.
• Version Rollback: If 3D mode must be used, it is usually necessary to roll back the ECharts core library to v5.x, which may affect the use of features in other charts within the project.

API Reference

Props

In addition to map-specific configurations, the component also fully passes through container size and rendering control attributes.

Property Name	Type	Default	Description
chartOption	Object	(Required)	Chart core configuration object.
geoJsonData	Object	(Required)	GeoJSON data object for the current map.
mapName	String	(Required)	Registered name of the current map (e.g., 'china').
allAreaCodes	Array	-	Administrative division mapping table, used for name-code conversion during drill-down.
width	Number/String	-	Container width.
height	Number/String	-	Container height.
renderer	String	'canvas'	Rendering mode. Recommended to use 'svg' for optimal clarity.
updateReplace	Boolean	true	Whether to use replaceMerge strategy when updating data, for smooth layer switching.
enableBreadcrumb	Boolean	false	Whether to enable built-in breadcrumb navigation and drill-down logic.
breadcrumbConfig	Object	{ data: [...], position: ... }	Breadcrumb configuration items (initial path, position coordinates).
loading	Boolean	null	Loading state control (supports v-model:loading).
ready v0.0.5+	Boolean	false	Rendering Control Signal. Initialization/rendering begins only when set to true.
initOptions	Object	{}	Additional parameters for ECharts initialization (e.g., devicePixelRatio, locale).
resizeObserver	String	'global'	Adaptation strategy. 'self' (component itself), 'global' (window), 'none' (disabled).
dataOpacity	Number	-	Data layer opacity (passed through to the underlying renderer).
dataBlur	Number	-	Data layer blurriness (passed through to the underlying renderer).

Removed Props

• Obsolete Props removed in v0.0.5: initDelay, initHold;

Events

The component forwards all standard ECharts interaction events and map-specific logic events.

Event Category	Event Name	Description
Interaction	chartClick	Single click on map area or marker (commonly used for drill-down).
	chartDblClick	Double click event.
	chartMouseDown	Mouse button pressed.
	chartMouseUp	Mouse button released.
	chartMouseOver	Mouse hover (commonly used for highlight tips).
	chartGlobalOut	Mouse leaves the chart container area.
	chartGeoRoam	Map roam event (zoom/pan), commonly used to synchronize popup positions.
Lifecycle	chartInit	Instance initialization complete.
	chartReady	Chart first render complete (including animation).
	chartRendered	Triggered every time a render action occurs.
	chartFinished	Triggered when rendering actions completely stop.
Business	chartUpdate	Chart update event.
	chartTimelinechanged	Timeline node switching event.
	breadcrumbClick	Triggered when breadcrumb navigation is clicked.
	update:loading	Two-way binding update for loading state.

Methods

Internal methods exposed by the component can be called via ref.

Method Name	Arguments	Description
initChart	-	Manually trigger the chart initialization process.
setOption	(option, notMerge, lazyUpdate)	Dynamically update chart configuration.
getChart	-	Get the raw ECharts instance object.
resize	-	Force trigger chart size redrawing.
resetMapView	-	Specific Method: Reset map zoom ratio and center point to initial state.
clear	-	Clear the current instance canvas.
dispose	-	Destroy the instance and release resources.

Credits

Baidu EFE team

Github

Apache Software Foundation (ASF)

Github

Special thanks and sincere respect to Baidu EFE, the founding team of the Echarts project, for creating such an outstanding open-source standard for data visualization.

We also thank the Apache Software Foundation (ASF) for the continuous maintenance and management of this project.