Custom series seriesLayoutBy configuration
Custom series supports seriesLayoutBy option for configuring how data is organized in relation to dataset.
custom-series
51 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
renderItem function purpose and parameters
The renderItem function is the core of custom series, called on each data item. It receives two parameters: params (providing info about the current series, data, and coordinate system) and api (providing methods to retrieve values, convert coordinates, get sizes, apply styles, and more). renderItem should return graphic element definitions or nothing if nothing should be rendered.
renderItem params object structure
The params object passed to renderItem contains: context (object for temporary storage, lifecycle is current rendering round), seriesId (string), seriesName (string), seriesIndex (number), dataIndex (number, index in original data), dataIndexInside (number, index in current data window from dataZoom), dataInsideLength (number, count of data in current data window), actionType (string, type of action triggering render), and coordSys (object whose structure varies by coordinate system type).
coordSys cartesian2d structure in renderItem
For cartesian2d coordinate system, coordSys contains: type ('cartesian2d'), x (number, x of grid rect), y (number, y of grid rect), width (number, width of grid rect), height (number, height of grid rect).
coordSys calendar structure in renderItem
For calendar coordinate system, coordSys contains: type ('calendar'), x (number, x of calendar component rect), y (number, y of calendar component rect), width (number, width of calendar component rect), height (number, height of calendar component rect), cellWidth (number), cellHeight (number), rangeInfo object with start (date start of calendar), end (date end of calendar), weeks (number of weeks), dayCount (day count).
coordSys matrix structure in renderItem
For matrix coordinate system, coordSys contains: type ('matrix'), x (number, x of matrix component rect), y (number, y of matrix component rect), width (number, width of matrix component rect), height (number, height of matrix component rect).
coordSys geo structure in renderItem
For geo coordinate system, coordSys contains: type ('geo'), x (number, x of geo rect), y (number, y of geo rect), width (number, width of geo rect), height (number, height of geo rect), zoom (number, zoom ratio where 1 means no zoom and 0.5 means shrink to 50%).
coordSys polar structure in renderItem
For polar coordinate system, coordSys contains: type ('polar'), cx (number, x of polar center), cy (number, y of polar center), r (number, outer radius of polar), r0 (number, inner radius of polar).
coordSys singleAxis structure in renderItem
For singleAxis coordinate system, coordSys contains: type ('singleAxis'), x (number, x of singleAxis rect), y (number, y of singleAxis rect), width (number, width of singleAxis rect), height (number, height of singleAxis rect).
api.value() method in renderItem
The api.value() method retrieves a value on the given dimension. It takes a required parameter 'dimension' (number, index from 0) and an optional parameter 'dataIndexInside' (usually not necessary). It returns the value (number) for that dimension.
api.coord() method in renderItem
The api.coord() method converts data to coordinate. Its behavior, parameters, and returns are the same as chart.convertToPixel (excluding its first 'finder' parameter). It converts data values to pixel coordinates in the current coordinate system.
api.layout() method in renderItem
The api.layout() method converts data to the corresponding layout info based on the current coordinate system. Available since v6.0.0. Its behavior, parameters, and returns are the same as chart.convertToLayout (excluding its first 'finder' parameter). Useful for coordinate systems like matrix.
api.size() method in renderItem
The api.size() method gets the size by given data range. For cartesian2d, calling api.size([2, 4]) might return [12.4, 55], representing that data range 2 on x axis corresponds to size 12.4, and data range 4 on y axis corresponds to size 55. Takes required parameter 'dataSize' (array of numbers) and optional parameter 'dataItem' (array of numbers, point where size will be calculated). Returns array of numbers representing the size.
api.style() method in renderItem
The api.style() method obtains style info defined in series.itemStyle and visual info from visual mapping, returning them for direct assignment to graphic element style attribute. Takes optional parameters: 'extra' (object for extra style info) and 'dataIndexInside' (usually not necessary). Can be called like api.style({fill: 'green', stroke: 'yellow'}) to override style settings. Returns object with style info.
api.styleEmphasis() method in renderItem
The api.styleEmphasis() method obtains style info defined in series.itemStyle.emphasis and visual info from visual mapping, returning them for direct assignment to graphic element style attribute. Takes optional parameters: 'extra' (object for extra style info) and 'dataIndexInside' (usually not necessary). Can be called like api.styleEmphasis({fill: 'green', stroke: 'yellow'}) to override style settings. Returns object with emphasis style info.
api.visual() method in renderItem
The api.visual() method gets the visual info. Takes required parameter 'visualType' (string like 'color', 'symbol', 'symbolSize', etc.) and optional parameter 'dataIndexInside' (usually not necessary). Returns the value of the visual (string or number). This method is rarely used.
api.barLayout() method in renderItem
The api.barLayout() method obtains bar layout info when needed (e.g., when attaching extra graphic elements to bar chart). Takes parameter 'opt' (object) with: count (number, how many bars in each group), barWidth (number or string, absolute value like 40 or percent like '60%', based on calculated category width), barMaxWidth (number or string, has higher priority than barWidth), barMinWidth (number or string, has higher priority than barWidth), barGap (number, gap of bars in a group), barCategoryGap (number, gap of groups). Returns array of objects with width (number), offset (number, based on left most edge), offsetCenter (number, based on bar center).
api.currentSeriesIndices() method in renderItem
The api.currentSeriesIndices() method obtains the current series index. Returns a number. Note that currentSeriesIndex is different from seriesIndex when legend is used to filter some series.
api.font() method in renderItem
The api.font() method obtains font string which can be used directly on style setting. Takes optional parameter 'opt' (object) with: fontStyle (string), fontWeight (number), fontSize (number), fontFamily (string). Returns font string.
api.getWidth() method in renderItem
The api.getWidth() method returns the width (number) of the ECharts container.
api.getHeight() method in renderItem
The api.getHeight() method returns the height (number) of the ECharts container.
api.getZr() method in renderItem
The api.getZr() method returns the zrender instance (module:zrender).
api.getDevicePixelRatio() method in renderItem
The api.getDevicePixelRatio() method returns the current devicePixelRatio (number).
renderItem return value types
renderItem should return graphic element definitions. Each graphic element is an object. Valid element types include rect, circle, line, text, image, path, polygon, polyline, and group. The return value can be a single graphic element object or nothing if nothing should be rendered. Note that width, height, top, bottom properties are not supported in renderItem graphic elements.
renderItem return group element with children
renderItem can return a group element containing multiple child elements. The group object has: type ('group'), optional diffChildrenByName (boolean, default false; if true, child.name will be used to diff children improving animation transition but degrading performance), children (array of graphic element objects).
renderItem example with x-range chart
Example renderItem function that creates rectangles for an x-range chart: ```ts renderItem: function (params, api) { var categoryIndex = api.value(0); var start = api.coord([api.value(1), categoryIndex]); var end = api.coord([api.value(2), categoryIndex]); var height = api.size([0, 1])[1] * 0.6; var rectShape = echarts.graphic.clipRectByRect({ x: start[0], y: start[1] - height / 2, width: end[0] - start[0], height: height }, { x: params.coordSys.x, y: params.coordSys.y, width: params.coordSys.width, height: params.coordSys.height }); return rectShape && { type: 'rect', shape: rectShape, style: api.style() }; } ```
Encode mapping for custom series dimensions
In custom series, series.encode should typically be specified to indicate dimension mapping, allowing ECharts to render appropriate axis by the extent of those data. The encode option can specify: x (array of dimension indices for x axis), y (array or number for y axis), label (dimension index for label content), tooltip (array or number for tooltip content). For example: encode: { x: [2, 4, 3], y: 1, label: 0, tooltip: [2, 4, 3] }
Dimensions configuration for custom series
series.dimensions can be specified to define names of each dimension, which will be displayed in tooltip.
Custom series with dataZoom filterMode
When using custom series with dataZoom, dataZoom.filterMode should usually be set as 'weakFilter', which prevents dataItem from being filtered when only part of its dimensions are out of the current data window.
dataIndex vs dataIndexInside in custom series
dataIndex is the index of a dataItem in the original data. dataIndexInside is the index of a dataItem in the current data window (affected by dataZoom). renderItem.arguments.api uses dataIndexInside as input parameter rather than dataIndex, because conversion from dataIndex to dataIndexInside is time-consuming.
Event listener with named elements in custom series
In custom series renderItem, graphic elements can be given a name property and an info property. When an element with a specific name is clicked, the event handler receives that element's info. Example: ```ts rendItem: function () { return { type: 'group', children: [{ type: 'circle', name: 'aaa', info: 12345, // ... }] }; } chart.on('click', {element: 'aaa'}, function (params) { console.log(params.info); // outputs 12345 }); ```
Custom series coordinate system support
Custom series supports coordinate systems: cartesian2d (default), polar, singleAxis, geo, calendar, and matrix, plus 'none' for coordinate system-agnostic rendering.
renderItem as string registration (v6.0+)
Since v6.0.0, renderItem can be a registered rendering logic provided as a string instead of a function. Use echarts.registerCustomSeries to register custom series.
Custom series data array format
Custom series data is an array where each item can have: name (string, name of data item), value (number, value of data item), itemStyle (object for item-specific styling), emphasis (object with itemStyle for emphasis state), and tooltip properties.
Custom series itemStyle configuration
Custom series supports itemStyle option for setting the default item style. Individual data items can override this with their own itemStyle. emphasis.itemStyle specifies styling for the emphasis state.
Custom series labelLine configuration
Custom series supports labelLine option with properties: length2 (support for two-stage label line), minTurnAngle, showAbove, and smooth.
Custom series labelLayout configuration
Custom series supports labelLayout option which can be an object or function for configuring label layout behavior.
Custom series selectedMode configuration
Custom series supports selectedMode option (available since v5.0.0) for configuring data selection behavior.
Custom series type definition
The custom series type is specified as `type: 'custom'`. Custom series supports customizing graphic elements to generate more types of charts. ECharts manages creation, deletion, animation, and interaction with other components like dataZoom and visualMap, freeing developers from handling those issues themselves.
Custom series datasetIndex configuration
Custom series supports datasetIndex option for specifying which dataset to use.
Custom series groupId configuration
Custom series supports groupId option for series grouping, and data items support groupId and childGroupId for data grouping.
Custom series clip configuration
Custom series supports clip option with default value false. The clip option controls whether to clip graphic elements outside the coordinate system bounds.
Custom series z and zLevel configuration
Custom series supports z option (rendering order) and zLevel option (canvas layer) for controlling stacking and layering of the custom series.
Custom series silent configuration
Custom series supports silent option for controlling whether the series is interactive (silent: true disables interaction).
Custom series animation configuration
Custom series supports animation options for controlling animation behavior during rendering and updates.
Custom series universal transition configuration
Custom series supports universal transition option for animating transitions between different data states or series configurations.
Custom series tooltip configuration
Custom series supports tooltip option for configuring tooltip behavior specific to the series, including formatter and other tooltip properties.
Custom series colorBy option
Custom series supports colorBy option for controlling how colors are applied from the palette.
Custom series legendHoverLink option
Custom series supports legendHoverLink option for controlling whether legend hover interaction affects the series.
Custom series api.style() and api.styleEmphasis() deprecated in v5
In custom series renderItem, the methods api.style(...) and api.styleEmphasis(...) are deprecated in v5 because they are not necessary and hard to ensure backward compatibility. Use api.visual(...) instead to fetch system-designated visuals.
Custom series animation enhancements
Apache ECharts 5 provides richer and more powerful animations in custom series, supporting interpolation animations for label value text, and transition animations for morph, combine, separate, and other effects of graphics.