ipecharts.option.tooltip module#
- class ipecharts.option.tooltip.Tooltip(**kwargs: Any)[source]#
Bases:
BaseWidget- Warning:
Autogenerated class
Tooltip component.
—
General Introduction:
tooltip can be configured on different places:
Configured on global: [tooltip](#tooltip)
Configured in a coordinate system: [grid.tooltip](#grid.tooltip), [polar.tooltip](#polar.tooltip), [single.tooltip](#single.tooltip)
Configured in a series: [series.tooltip](#series.tooltip)
Configured in each item of series.data: [series.data.tooltip](#series.data.tooltip)
- show Bool(None)#
Whether to show the tooltip component.
including tooltip floating layer and [axisPointer](#tooltip.axisPointer).
- trigger Unicode(None)#
Type of triggering.
Options:
‘item’
Triggered by data item, which is mainly used for charts that don’t have a category axis like scatter charts or pie charts.
‘axis’
Triggered by axes, which is mainly used for charts that have category axes, like bar charts or line charts.
ECharts 2.x only supports axis trigger for category axis. In ECharts 3, it is supported for all types of axes in [grid](#grid) or [polar](#polar). Also, you may assign axis with [axisPointer.axis](#tooltip.axisPointer.axis).
‘none’
Trigger nothing.
- axisPointer Dict()#
Configuration item for axisPointer.
tooltip.axisPointer is like syntactic sugar of axisPointer settings on axes (for example, [xAxis.axisPointer](#xAxis.axisPointer) or [angleAxis.axisPointer](#angleAxis.axisPointer)). More detailed features can be configured on someAxis.axisPointer. But in common cases, using tooltip.axisPointer is more convenient.
> Notice: configurations of tooltip.axisPointer has lower priority than that of someAxis.axisPointer.
—
axisPointer is a tool for displaying reference line and axis value under mouse pointer.
For example:
In the demo above, [axisPointer.link](#axisPointer.link) is used to link axisPointer from different coordinate systems.
axisPointer can also be used on touch device, where user can drag the button to move the reference line and label.
In the cases that more than one axis exist, axisPointer helps to look inside the data.
—
> Notice: > Generally, axisPointers is configured in each axes who need them (for example [xAxis.axisPointer](#xAxis.axisPointer)), or configured in tooltip (for example [tooltip.axisPointer](#tooltip.axisPointer)).
> But these configurations can only be configured in global axisPointer: > [axisPointer.triggerOn](#axisPointer.triggerOn), [axisPointer.link](#axisPointer.link).
—
—
How to display axisPointer:
In [cartesian (grid)](#grid) and [polar](~polar) and (single axis](#single), each axis has its own axisPointer.
Those axisPointer will not be displayed by default, utill configured as follows:
Set someAxis.axisPointer.show (like [xAxis.axisPointer.show](#xAxis.axisPointer.show)) as true. Then axisPointer of this axis will be displayed.
Set [tooltip.trigger](#tooltip.trigger) as ‘axis’, or set [tooltip.axisPointer.type](#tooltip.axisPointer.type) as ‘cross’. Then coordinate system will automatically chose the axes who will display their axisPointers. ([tooltip.axisPointer.axis](#tooltip.axisPointer.axis) can be used to change the choice.) Notice, axis.axisPointer will override tooltip.axisPointer settings.
—
How to display the label of axisPointer:
The label of axisPointer will not be displayed by default(namely, only reference line will be displayed by default), utill configured as follows:
Set someAxis.axisPointer.label.show (for example [xAxis.axisPointer.label.show](#xAxis.axisPointer.show)) as true. Then the label of the axisPointer will be displayed.
Set [tooltip.axisPointer.type](#tooltip.axisPointer.type) as ‘cross’. Then the label of the crossed axisPointers will be displayed.
—
How to configure axisPointer on touch device:
Set someAxis.axisPointer.handle.show (for example [xAxis.axisPointer.handle.show](#xAxis.axisPointer.handle.show) as true. Then the button for dragging will be displayed. (This feature is not supported on polar).
Notice: If tooltip does not work well in this case, try to set[tooltip.triggerOn](#tooltip.triggerOn) as ‘none’ (for the effect: show tooltip when finger holding on the button, and hide tooltip after finger left the button), or set [tooltip.alwaysShowContent](#tooltip.alwaysShowContent) as true (then tooltip will always be displayed).
See the [example](https://echarts.apache.org/examples/en/editor.html?c=line-tooltip-touch&edit=1&reset=1).
—
Snap to point
In value axis and time axis, if [snap](#xAxis.axisPointer.snap) is set as true, axisPointer will snap to point automatically.
—
- showContent Bool(None)#
Whether to show the tooltip floating layer, whose default value is true. It should be configurated to be false, if you only need tooltip to trigger the event or show the axisPointer without content.
- alwaysShowContent Bool(None)#
Whether to show tooltip content all the time. By default, it will be hidden [after some time](#tooltip.hideDelay). It can be set to be true to preserve displaying.
This attribute is newly added to ECharts 3.0.
- triggerOn Unicode(None)#
Conditions to trigger tooltip. Options:
‘mousemove’
Trigger when mouse moves.
‘click’
Trigger when mouse clicks.
‘mousemove|click’
Trigger when mouse clicks and moves.
‘none’
Do not triggered by ‘mousemove’ and ‘click’. Tooltip can be triggered and hidden manually by calling [action.tooltip.showTip](api.html#action.tooltip.showTip) and [action.tooltip.hideTip](api.html#action.tooltip.hideTip). It can also be triggered by [axisPointer.handle](#xAxis.axisPointer.handle) in this case.
This attribute is new to ECharts 3.0.
- showDelay Float(None)#
Delay time for showing tooltip, in ms. No delay by default, and it is not recommended to set. Only valid when [triggerOn](#tooltip.triggerOn) is set to be ‘mousemove’.
- hideDelay Float(None)#
Delay time for hiding tooltip, in ms. It will be invalid when [alwaysShowContent](#tooltip.alwaysShowContent) is true.
- enterable Bool(None)#
Whether mouse is allowed to enter the floating layer of tooltip, whose default value is false. If you need to interact in the tooltip like with links or buttons, it can be set as true.
- renderMode Unicode(None)#
Render mode for tooltip. By default, it is set to be ‘html’ so that extra DOM element is used for tooltip. It can also set to be ‘richText’ so that the tooltip will be rendered inside Canvas. This is very useful for environments that don’t have DOM, such as Wechat applications.
- confine Bool(None)#
Whether confine tooltip content in the view rect of chart instance.
Useful when tooltip is cut because of ‘overflow: hidden’ set on outer dom of chart instance, or because of narrow screen on mobile.
- appendToBody Bool(None)#
> Since v4.7.0
(DEPRECATED since v5.5.0, use [appendTo](#tooltip.appendTo) instead.)
Whether to append the tooltip DOM element as a child of the <body> of the HTML page, when using [renderMode](#tooltip.renderMode) ‘html’.
The default value is false, which means that the tooltip DOM element will be one of a descendant of its echarts DOM container. But that means that the tooltip might be cut when overflow the container if some of the ancestors DOM element of the echarts container are styled with overflow: hidden. This case could also be resolved by setting [tooltip.confine](#tooltip.confine), but it might not suitable for all scenarios.
Here we provide appendToBody: true to auto append the tooltip element to <body>, which is a common way to resolve this kind of issue. But true is not set as a default value because to void to bring break change for some cases where tooltip is deeply customized and to void some unexpected bad cases.
Note that it also works when CSS transform used.
- appendTo Union(None)#
> Since v5.5.0
Which DOM element to append the tooltip to. Only available when using [renderMode](#tooltip.renderMode) ‘html’.
The default value is null, which means that the tooltip’s DOM node will be added as a descendant node of the chart’s DOM container. However, this approach can cause the tooltip to be truncated if it extends beyond the container, due to ancestors of the chart’s DOM container having overflow: hidden set. This issue can be partially addressed using tooltip.confine, but it may not cover all scenarios.
For such scenarios, appendTo can be specified. When it is a function, the interface is in the form of
``` (chartContainer: HTMLElement) => HTMLElement | undefined | null
which means it returns the node that the tooltip’s DOM node should be added to. Returning undefined or null indicates that the default logic described above should be used. Returning an HTMLElement means that it should be added under that node.
Note that it also works when CSS transform used.
- className Unicode(None)#
> Since v5.0.0
Specify the classes for the tooltip root DOM. (Only works in [html](#tooltip.renderMode) render mode).
Example:
``` className: ‘echarts-tooltip echarts-tooltip-dark’
- transitionDuration Float(None)#
The transition duration of tooltip’s animation, in seconds. When it is set to be 0, it would move closely with the mouse.
- position Union(None)#
The position of the tooltip’s floating layer, which would follow the position of mouse by default.
Options:
Array
Display the position of tooltip’s floating layer through array, which supports absolute position and relative percentage.
Example:
Function
Callback function in the following form:
- ```
(point: Array, params: Object|Array.<Object>, dom: HTMLDomElement, rect: Object, size: Object) => Array
Parameters:
point: Mouse position.
param: The same as formatter.
dom: The DOM object of tooltip.
rect: It is valid only when mouse is on graphic elements, which stands for a bounding box with x, y, width, and height.
size: The size of dom echarts container. For example: {contentSize: [width, height], viewSize: [width, height]}.
Return:
Return value is an array standing for tooltip position, which can be absolute pixels, or relative percentage.
Or can be an object, like {left: 10, top: 30}, or {right: ‘20%’, bottom: 40}.
For example:
- ```
- position: function (point, params, dom, rect, size) {
// fixed at top return [point[0], ‘10%’];
}
Or:
‘inside’
Center position of the graphic element where the mouse is in, which is only valid when [trigger](#tooltip.trigger) is ‘item’.
‘top’
Top position of the graphic element where the mouse is in, which is only valid when [trigger](#tooltip.trigger) is ‘item’.
‘left’
Left position of the graphic element where the mouse is in, which is only valid when [trigger](#tooltip.trigger) is ‘item’.
‘right’
Right position of the graphic element where the mouse is in, which is only valid when [trigger](#tooltip.trigger) is ‘item’.
‘bottom’
Bottom position of the graphic element where the mouse is in, which is only valid when [trigger](#tooltip.trigger) is ‘item’.
- formatter Union(None)#
The content formatter of tooltip’s floating layer which supports string template and callback function.
1. String template
The template variables are {a}, {b}, {c}, {d} and {e}, which stands for series name, data name and data value and ect. When [trigger](#tooltip.trigger) is set to be ‘axis’, there may be data from multiple series. In this time, series index can be referred as {a0}, {a1}, or {a2}.
{a}, {b}, {c}, {d} have different meanings for different series types:
Line (area) charts, bar (column) charts, K charts: {a} for series name, {b} for category name, {c} for data value, {d} for none;
Scatter (bubble) charts: {a} for series name, {b} for data name, {c} for data value, {d} for none;
Map: {a} for series name, {b} for area name, {c} for merging data, {d} for none;
Pie charts, gauge charts, funnel charts: {a} for series name, {b} for data item name, {c} for data value, {d} for percentage.
Example:
``` formatter: ‘{b0}: {c0}<br />{b1}: {c1}’
2. Callback function
The format of callback function:
``` (params: Object|Array, ticket: string, callback: (ticket: string, html: string)) => string | HTMLElement | HTMLElement[]
The first parameter params is the data that the formatter needs. Its format is shown as follows:
``` {
componentType: ‘series’, // Series type seriesType: string, // Series index in option.series seriesIndex: number, // Series name seriesName: string, // Data name, or category name name: string, // Data index in input data array dataIndex: number, // Original data as input data: Object, // Value of data. In most series it is the same as data. // But in some series it is some part of the data (e.g., in map, radar) value: number|Array|Object, // encoding info of coordinate system // Key: coord, like (‘x’ ‘y’ ‘radius’ ‘angle’) // value: Must be an array, not null/undefined. Contain dimension indices, like: // { // x: [2] // values on dimension index 2 are mapped to x axis. // y: [0] // values on dimension index 0 are mapped to y axis. // } encode: Object, // dimension names list dimensionNames: Array<String>, // data dimension index, for example 0 or 1 or 2 … // Only work in radar series. dimensionIndex: number, // Color of data color: string, // The percentage of current data item in the pie/funnel series percent: number, // The ancestors of current node in the sunburst series (including self) treePathInfo: Array, // The ancestors of current node in the tree/treemap series (including self) treeAncestors: Array, // A function that returns a boolean value to flag if the axis label is truncated isTruncated: Function, // Current index of the axis label tick tickIndex: number
}
How to use `encode` and `dimensionNames`?
When the dataset is like
``` dataset: {
- source: [
[‘Matcha Latte’, 43.3, 85.8, 93.7], [‘Milk Tea’, 83.1, 73.4, 55.1], [‘Cheese Cocoa’, 86.4, 65.2, 82.5], [‘Walnut Brownie’, 72.4, 53.9, 39.1]
]
}
We can get the value of the y-axis via
``` params.value[params.encode.y[0]]
When the dataset is like
``` dataset: {
dimensions: [‘product’, ‘2015’, ‘2016’, ‘2017’], source: [
{product: ‘Matcha Latte’, ‘2015’: 43.3, ‘2016’: 85.8, ‘2017’: 93.7}, {product: ‘Milk Tea’, ‘2015’: 83.1, ‘2016’: 73.4, ‘2017’: 55.1}, {product: ‘Cheese Cocoa’, ‘2015’: 86.4, ‘2016’: 65.2, ‘2017’: 82.5}, {product: ‘Walnut Brownie’, ‘2015’: 72.4, ‘2016’: 53.9, ‘2017’: 39.1}
]
}
We can get the value of the y-axis via
``` params.value[params.dimensionNames[params.encode.y[0]]]
When [trigger](#tooltip.trigger) is ‘axis’, or when tooltip is triggered by [axisPointer](#xAxis.axisPointer), params is the data array of multiple series. The content of each item of the array is the same as above. Besides,
``` {
componentType: ‘series’, // Series type seriesType: string, // Series index in option.series seriesIndex: number, // Series name seriesName: string, // Data name, or category name name: string, // Data index in input data array dataIndex: number, // Original data as input data: Object, // Value of data. In most series it is the same as data. // But in some series it is some part of the data (e.g., in map, radar) value: number|Array|Object, // encoding info of coordinate system // Key: coord, like (‘x’ ‘y’ ‘radius’ ‘angle’) // value: Must be an array, not null/undefined. Contain dimension indices, like: // { // x: [2] // values on dimension index 2 are mapped to x axis. // y: [0] // values on dimension index 0 are mapped to y axis. // } encode: Object, // dimension names list dimensionNames: Array<String>, // data dimension index, for example 0 or 1 or 2 … // Only work in radar series. dimensionIndex: number, // Color of data color: string
}
How to use `encode` and `dimensionNames`?
When the dataset is like
``` dataset: {
- source: [
[‘Matcha Latte’, 43.3, 85.8, 93.7], [‘Milk Tea’, 83.1, 73.4, 55.1], [‘Cheese Cocoa’, 86.4, 65.2, 82.5], [‘Walnut Brownie’, 72.4, 53.9, 39.1]
]
}
We can get the value of the y-axis via
``` params.value[params.encode.y[0]]
When the dataset is like
``` dataset: {
dimensions: [‘product’, ‘2015’, ‘2016’, ‘2017’], source: [
{product: ‘Matcha Latte’, ‘2015’: 43.3, ‘2016’: 85.8, ‘2017’: 93.7}, {product: ‘Milk Tea’, ‘2015’: 83.1, ‘2016’: 73.4, ‘2017’: 55.1}, {product: ‘Cheese Cocoa’, ‘2015’: 86.4, ‘2016’: 65.2, ‘2017’: 82.5}, {product: ‘Walnut Brownie’, ‘2015’: 72.4, ‘2016’: 53.9, ‘2017’: 39.1}
]
}
We can get the value of the y-axis via
``` params.value[params.dimensionNames[params.encode.y[0]]]
Note: Using array to present all the parameters in ECharts 2.x is not supported anymore.
The second parameter ticket is the asynchronous callback flag which should be used along with the third parameter callback when it is used.
The third parameter callback is asynchronous callback. When the content of tooltip is acquired asynchronously, ticket and htm as introduced above can be used to update tooltip with callback.
Example:
``` formatter: function (params, ticket, callback) {
- $.get(‘detail?name=’ + params.name, function (content) {
callback(ticket, toHTML(content));
}); return ‘Loading’;
}
- valueFormatter Unicode(None)#
> Since v5.3.0
Callback function for formatting the value section in tooltip.
Interface:
``` (value: number | string, dataIndex: number) => string
``` > dataIndex is provided since v5.5.0.
Example:
``` // Add $ prefix valueFormatter: (value) => ‘$’ + value.toFixed(2)
- backgroundColor Any(None)#
The background color of tooltip’s floating layer.
- borderColor Any(None)#
The border color of tooltip’s floating layer.
- borderWidth Float(None)#
The border width of tooltip’s floating layer.
- padding Float(None)#
The floating layer of tooltip space around content. The unit is px. Default values for each position are 5. And they can be set to different values with left, right, top, and bottom.
Examples:
``` // Set padding to be 5 padding: 5 // Set the top and bottom paddings to be 5, and left and right paddings to be 10 padding: [5, 10] // Set each of the four paddings separately padding: [
5, // up 10, // right 5, // down 10, // left
]
- textStyle Dict()#
The text style of tooltip’s floating layer.
- extraCssText Unicode(None)#
Extra CSS style for floating layer. The following is an example for adding shadow.
``` extraCssText: ‘box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);’
- order Unicode(None)#
> Since v5.0.0
Tooltip order for multiple series. Defaults is ‘seriesAsc’.
Conditions to order tooltip. Options:
‘seriesAsc’
Base on series declaration, ascending order tooltip.
‘seriesDesc’
Base on series declaration, descending order tooltip.
‘valueAsc’
Base on value, ascending order tooltip, only for numeric value.
‘valueDesc’
Base on value, descending order tooltip, only for numeric value.