{{target: geo-svg}}
Since v5.1.0
, ECharts support to use SVG as the base map in geo coordinate system and map series, where previously only GeoJSON is supported.
This feature enables ECharts to display SVG in either of the render modes (canvas
render mode and svg
render mode), and enables features like zoom, pan, select, emphasis, focus-blur, label, labelLayout, tooltip on SVG with only simple some ECharts options. Series like scatter, effectScatter, lines, custom that are available on geo coordinate system can also be positioned and displayed based on SVG base map.
There are several examples where SVG base map is used:
Beef Cuts | Organ Visualization | Flight Seatmap | SVG Map | SVG Scatter | SVG Lines | SVG Traffic
The usage of SVG base map is the same as the usage of GeoJSON.
If used in geo coordinate system:
$.get('map/organ.svg', function (svg) { // Firstly we need to register SVG raw string or parsed SVG DOM // to echarts with a name: echarts.registerMap('organ_diagram', {svg: svg}); var chart = echarts.init(document.getElementById('main')); chart.setOption({ geo: { // Reference it in echarts option. map: 'organ_diagram', ... } }); });
If used in map series:
$.get('map/beef_cuts.svg', function (svg) { // Firstly we need to register SVG raw string or parsed SVG DOM // to echarts with a name: echarts.registerMap('beef_cuts_diagram', {svg: svg}); var chart = echarts.init(document.getElementById('main')); chart.setOption({ series: { type: 'map', // Reference it in echarts option. map: 'beef_cuts_diagram', ... } }); });
option = { geo: { // Enable zoom and pan. roam: true, ... } };
For map series
option = { series: { type: 'map', // Enable zoom and pan. roam: true, ... } };
See roam. Also see example SVG Map.
If intending to interact with some elements of SVG, we need to mark those elements in SVG firstly. That can be done simply by adding names to the target elements. The interaction related feature like select, emphasis, focus-blur, label, labelLayout, tooltip depend on those named elements.
For example, we add name attribute name="named_rect"
only to the left SVG path
.
<?xml version="1.0" encoding="utf-8"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.2" fill-rule="evenodd" xml:space="preserve"> <path name="named_rect" d="M 0,0 L 0,100 100,100 100,0 Z" fill="#765" /> <path d="M 150,0 L 150,100 250,100 250,0 Z" fill="#567" /> </svg>
Then hover on the left rect, it can be highlighted, whereas the right one can not.
Option for some certain named elements can be specified in geo.regions, like:
option = { geo: { map: 'some_svg', regions: [{ name: 'element_name_1', itemStyle: { ... } }, { name: 'element_name_2', itemStyle: { ... } }] } };
Note:
rect
, circle
, line
, ellipse
, polygon
, polyline
, path
, text
, tspan
, g
.Although the style (such as color, font, lineWidth, ...) of SVG Elements can be defined directly in SVG file, style of named elements can also be customized in ECharts option, which will be handy in some scenario.
Styles can be specified in geo.itemStyle and series-map.itemStyle (also includes emphasis.itemStyle
, select.itemStyle
, blur.itemStyle
, regions[i].itemStyle
, regions[i].emphasis.itemStyle
, regions[i].select.itemStyle
, regions[i].blur.itemStyle
). Some default style of the named elements can also be removed here (e.g., set emphasis.itemStyle.color: null
to prevent the fill color from changing when mouse hovering.)
Moreover, named elements can also be styled by visualMap component if using series-map. See Beef Cuts.
Note: Only these named elements can be styled in itemStyle
: rect
, circle
, line
, ellipse
, polygon
, polyline
, path
.
Named elements can adopt “select” feature by setting geo.selectedMode or series-map.selectedMode as 'single'
or 'multiple'
. The style of element when selected can be specified in geo.select or series-map.select.
The selected names can be obtained by geoselectchanged event, like:
myChart.on('geoselectchanged', function (params) { var selectedNames = params.allSelected[0].name; console.log('selected', selectedNames); });
See Flight Seatmap for more details.
emphasis
state (highlight when hovering) can be auto adopted to named elements.
Especially, geo.emphasis.focus and be set as 'self'
to enable “focus-blur” feature, where all all of the other elements will be blurred when hovering on an named element.
See Organ Visualization for more details.
Tooltip can be enabled or disabled on named elements.
option = { // Need to declare the root tooltip to // enable tooltip feature on ECharts. tooltip: {}, geo: { map: 'some_svg', tooltip: { // Use `show` to enable/disable tooltip // on geo coordinate system. show: true }, regions: [{ name: 'some_name1', // Set named element specified tooltip option if needed. tooltip: { formatter: 'some special tooltip 1' } }, { name: 'some_name2', tooltip: { formatter: 'some special tooltip 2' } }] } };
If intending to disable the geo tooltip when hovering a on named elements, just:
option = { tooltip: {}, geo: { map: 'some_svg', tooltip: { show: false } } };
See SVG Map for more details.
Although text label can be declared in SVG file directly via <text>
/<tspan>
, we can also use ECharts built-in label feature on named elements by specifying geo.label or series-map.label.
By default the label feature is enabled when hovering on a named element. If intending to disable it, just:
option = { geo: { map: 'some_svg', emphasis: { label: { show: false } } } };
When multiple elements need to share one label text, we have two choices:
<g>
(e.g., <g name="name_a">
), where a single label will be displayed and located based on the bounding rect of the <g>
.<path name="name_b"/><path name="name_b"/>
), where multiple labels will be displayed and located based on each elements self.For example (hover to show the labels): ~500x300
Note: Only these named elements can be labeled via label
option: rect
, circle
, line
, ellipse
, polygon
, polyline
, path
, g
.
Also see Organ Visualization for the usage of label.
Mouse events or touch events of named elements can be listened simply by:
// 'name1' is a name of a SVG element. myChart.on('click', { geoIndex: 0, name: 'name1' }, function (params) { console.log(params); });
By default ECharts will position the SVG base map in the center of the canvas. If need some adjust, we usually only adjust layoutCenter/layoutSize, and occasionally <svg viewBox="...">
/geo.boundingCoords (difference: clip or not). In most cases they are enough.
If need some advanced precise control of the position and zoom, several concepts below can be noticed.
The layout rule and options of geo coordinate system and map series are the same. So we only demonstrate geo coordinate system below.
The demo above shows six geo coordinate system with three SVG files in a single ECharts canvas. Each two geo that are in the same column use the same SVG file.
Firstly, what shapes looks like is determined by SVG file itself. That is, in the demo above, determined by the <circle>
and viewBox
attribute (viewBox
cut (clips) the circle). We can noticed that the final shape outlines in each column are the same (despite the difference in position, size and scratch), since they use the same SVG file.
Secondly, users can use either of the two option groups below to determine the location and the size of the geo view port
of geo coordinate system according to the entire chart canvas (all of these options are measured in echarts canvas pixel, or percentage value):
In the demo above, the six geo geo view ports
are displayed as six black squares.
Thirdly, a bounding rect
of the SVG is determined, which is determined by methods below (all of them are measured in SVG local unit):
bounding rect
.<svg width="..." height="...">
is specified, use [0, 0, width, height]
as bounding rect
. (If only width
or only height
is specified, only use [0, width]
or [0, height]
).svg viewBox="...">
is specified, use viewBox
as bounding rect
.bounding rect
.bounding rect
determined by 1~4
above.Having bounding rect
determined, it will be placed into its corresponding geo view port
:
bounding rect
will be placed at the center and as big as possible into the geo view port
(keep aspect ratio).geo view port
entirely.Series like scatter, effectScatter, lines, custom that are available on geo coordinate system can also be positioned and displayed on SVG base map.
Note that in this kind of usage the unit of series data value is the SVG file local coords. For example:
option = { geo: { map: 'some_svg' }, series: { type: 'effectScatter', coordinateSystem: 'geo', geoIndex: 0, data: [ // SVG local coords. [488.2358421078053, 459.70913833075736], [770.3415644319939, 757.9672194986475], [1180.0329284196291, 743.6141808346214], ] } };
By the way, there is a simple approach to get SVG local coord:
myChart.setOption({ geo: { map: 'some_svg' } }); myChart.getZr().on('click', function (params) { var pixelPoint = [params.offsetX, params.offsetY]; var dataPoint = myChart.convertFromPixel({ geoIndex: 0 }, pixelPoint); // When click, the data in SVG local coords will be printed, // which can be used in `series.data`. console.log(dataPoint); });
See also SVG Scatter, SVG Lines, SVG Traffic.
Unfortunately it is difficult to implement a complete SVG parser. While the common SVG features are supported, at least these features listed below are not supported yet:
v5.1.2
):transform: skew(...)
(including transform: matrix(...)
that includes skew).transform: scale(x, y)
that x
, y
has different sign while has rotate
(e.g., scale: (1, -1), rotate(90)
).<style>
tag is not supported.<path style="color:red" />
).px
is supported. Other unit like width="231.65mm"
is not supported.<svg width="30%" height="40%">
is not supported.<defs>
tag:<linearGradient>
, <radialGradient>
are supported.<pattern>
, <path>
, ...) defined in <defs>
are not supported yet.<linearGradient>
, <radialGradient>
:fx
, fy
is not supported.gradientTransform
attribute is not supported.fill:url(...)
, stroke:utl(...)
:url(#someId)
is supported.url(https://example.com/images/myImg.jpg)
;url(data:image/png;base64,iRxVB0…)
;url(myFont.woff)
;<switch>
tag:<switch>
tag will be displayed. The “switch” feature is not supported.<text>
:textPath
is not supported.<!-- Not supported: --> <tspan x="0 4.94 9.89">abc</tspan> <!-- Supported: --> <tspan x="0">a</tspan> <tspan x="4.94">b</tspan> <tspan x="9.89">c</tspan>