←ECharts 标题组件

ECharts 图例组件→

ECharts 提示框

在我们的图表旁边一般都看不到大量的展示，大量的展示不仅会影响美观性，而且还容易破坏图表的布局。那当我们要展示某点的数据信息时又该如何做呢？不用担心，ECharts 已经帮我们准备好了，让我们在不影响整体简洁图表的美观性，又能看到某一处的相信数据信息。下面我们一起去了解一下 ECharts 中框是如何使用的吧。

：

框组件。

解释

框指当鼠标悬停在图表的某点或坐标轴的某个值上时，以浮层形式展示该点数据信息的组件。例如：

tooltip 组件使用范围较大，首先可以在图表的多个层级配置：

Tips：
ECharts 会沿配置链路逐级向上 merge，计算出最终作用在数据项上的配置值。

其次，部分辅助组件也 tooltip ，：

tooltip 的配置项在上有详细罗列，此处不赘述。本文将更多关注框组件常规的用例场景，以实例方式展示使用。

启动 tooltip 组件，最简单的是在实例级别上配置 tooltip ，例如：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: { show: true },
				series: [
					{
						data: [, , , , , , ],
						type: 'line',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);
		</script>
	</body>
</html>

实例中，配置对象 option 配置有根 tooltip: { show: true }即可在所有图表上开启框，示例：

图表上的 tooltip 认触发类型为 item，即鼠标悬停在数据项上时触发，且框紧跟在数据项附近。可通过触发方式，如下值：

首先看看 item 示例：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: { show: true },
				series: [
					{
						data: [, , , , , , ],
						type: 'line',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);
		</script>
	</body>
</html>

示例：

上例基础上， tooltip 为：

tooltip: {
  show: true,
  // 设定为按坐标轴触发
  trigger: 'axis',
},

示例：

Tips：
axis 模式在直角坐标系、极坐标系下的所有图表均有效，且可以通过指定触发的坐标轴。

其他坐标系图表只能 item或 none 触发。

认情况下，tooltip 在鼠标悬停时触发，可以通过 tooltip.triggerOn配置项触发条件，接受如下值：

当 tooltip.triggerOn值为 none 时，可通过接口控制框：

echartInstance.dispatchAction({
    type: 'showTip',
    // 系列的 index
    seriesIndex?: number,
    // 数据的 index
    dataIndex?: number,
    // 可选，数据，在有 dataIndex 的时候忽略
    name?: string,
    // 本次 tooltip 的位置。只在本次 action 中生效。
    // 缺省则使用 option 中定义的 tooltip 位置。
    position: Array.<number>|string|Function,
})

dispatchAction({
	type: 'hideTip',
});

综合示例：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));
			const data = [, , , , , , ];

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: {
					show: true,
					trigger: 'item',
				},
				series: [
					{
						data: data,
						type: 'line',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);

			const len = data.length;
			(function triggerTooltip(index) {
				myChart.dispatchAction({ type: 'showTip', seriesIndex: , dataIndex: index % len });
				setTimeout(() => triggerTooltip(index + ), );
			})();
		</script>
	</body>
</html>

运行：

Tips：
tooltip.showTip行为是鼠标交互的替换方式，与鼠标触发一模一样，这背后有两层含义，一是无论多少次，当前只会有框被激活。例如上例中并没有 tooltip.hideTip行为，当每次 tooltip.showTip之后都会把前框隐藏掉。

二是，接口触发与鼠标交互触发相互冲突，比如上例运行过程中，如果鼠标悬停在数据项上，：

这一点可能导致图表比较混乱，应用时务必注意。

tooltip 组件的核心作用是展示数据项相关的信息，可以通过 tooltip.formatter项进行配置。tooltip.formatter接受模板字符串、模板两种类型的值：

模板字符串行人如 {a}: {c}其中 {}为 echarts 提供的模板变量，不同图表所提供的变量集合不同，但通常有：

更多信息可参考。

模板字符串传入 html ，这在 tooltip.renderModel = html时会被渲染为标准的 DOM 结构，例如：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: {
					show: true,
					trigger: 'item',
					// 定义框
					formatter: 'Data Item:<br /> {b}: <strong>{c}</strong>',
				},
				series: [
					{
						data: [, , , , , , ],
						type: 'line',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);
		</script>
	</body>
</html>

示例中设定框的格式为 'Data Item: {b0}: {c0}'渲染结果：

Tips：
模板字符串存在一些明显的缺陷：

模板字符串实现的非常鸡肋，无法承担较复杂的格式化需求，建议尽量使用模板方式。

当图表上有多个数据序列，传入的变量名会出现有点变化，例如：

例如下例中：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: {
					show: true,
					trigger: 'axis',
					// 定义框
					formatter: 'Data Item:<br /> {a0}: <strong>{c0}</strong> <br /> {a1}: <strong>{c1}</strong>',
				},
				series: [
					{
						data: [, , , , , , ],
						type: 'line',
						name: 'line-1',
						smooth: true,
					},
					{
						data: [, , , , , , ],
						type: 'line',
						name: 'line-2',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);
		</script>
	</body>
</html>

示例包含两个折线图，此时 tooltip.formatter为 'Data Item: {a0}: {c0} {a1}: {c1}'指定了 a0、a1 等变量，渲染结果：

tooltip.formatter还传入值，签名形如：

(params: Object|Array, ticket: string, callback: (ticket: string, html: string)) => string

Tips：
模板需返回字符串值，与模板字符串相似，若渲染模式 tooltip.renderMode = html则字符串中 html 。

其中包含参数：

params 形态不定，根据触发方式、图表类型会有些差异，但通常包含如下：

{
    componentType: 'series',
		// 系列类型，如 line、pie、bar
    seriesType: string,
    // 系列在传入的 option.series 中的 index
    seriesIndex: number,
    // 系列
    seriesName: string,
    // 数据名，类目名
    name: string,
    // 数据在传入的 data 数组中的 index
    dataIndex: number,
    // 传入的原始数据项
    data: number|Array|Object,
    // 传入的数据值。在多数系列下它和 data 相同。在一些系列下是 data 中的分量（如 map、radar 中）
    value: number|Array|Object,
		// 坐标轴 encode 编码方式
    encode: Object,
    // 维度名列表
    dimensionNames: Array<String>,
    // 数据的维度 index，如 0 或 1 或 2 ...
    // 仅在雷达图中使用。
    dimensionIndex: number,
    // 数据图形的颜色
    color: string,
    // 饼图的百分比
    percent: number,
}

示例：

<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		< charset="utf-8" />
		< http-equiv="X-UA-Compatible" content="IE=edge" />
		< name="viewport" content="width=device-width,initial-scale=1.0" />
		<title>Echarts Example</title>
	</head>
	<body>
		<div id="main" style="width: px;height: px"></div>

		<script src="//cdn.bootcss.com/echarts/4.5.0/echarts.js"></script>
		<script type="text/javascript">
			const myChart = echarts.init(document.getElementById('main'));

			const option = {
				xAxis: {
					type: 'category',
					data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
				},
				yAxis: { type: 'value' },
				tooltip: {
					show: true,
					trigger: 'item',
					// 定义框
					formatter(params) {
						const { seriesName, name, data } = params;
						return `${name}: <br />${seriesName}:${data}`;
					},
				},
				series: [
					{
						data: [, , , , , , ],
						type: 'line',
						smooth: true,
					},
				],
			};
			myChart.setOption(option);
		</script>
	</body>
</html>

示例：

Tips：
params 参数的值与框所在位置强相关，建议开发时使用 debugger、console.dir 等手段进一步确认。

模板异步形式，需要配合使用 ticket、callback 两个参数，在上例基础上， tooltip 配置：

formatter(params, ticket, cb) {
	// 执行异步操作
	setTimeout(() => {
		// 异步操作完成后，需 cb 回调
		// 传入 ticket 及字符串
		cb(ticket, 'Async Success');
	}, );
	// 立即返回过渡态的
	return 'Loading';
},

其中，ticket 为 ECharts 内部令牌，无需关注；callback 为异步回调，示例：

Tips：
模板在每次激活框时都会被触发，ECharts 没有对的执行做任何优化，这可能导致：

与框渲染方式有关的配置项：

renderMode 用于指定框的渲染模式。当 renderMode = html时，框会以 DOM 形式追加到图表容器节点的后面，结果如：

此时可以使用 extraCssText 为浮层更多样式，extraCssText 与 html 的 style 一样，接受 ;分割的 CSS 值，如：extraCssText: '@R_830_2@-shadow: 0 0 3px rgba(0, 0, 0, 0.3);'

Tips：
在官方文档中有提及另外：，用于指定当 renderMode = html时，框的 DOM 是否追加到 <body>节点下，但实测无效，无论如何设置，渲染出的结果都只会追加到图表容器节点上。

当 renderMode = richText时，将渲染在 canvas 上(SVG 模式目前还)，关于 richText的更多介绍，可参考一节。 html 与 richText 模式的主要区别有：

Tips：
html 模式与普通的开发相似，更容易通过浏览器的 debugger 工具调试，所以个人更推荐使用 html 模式。canvas 则可应对一些没有 DOM 的环境，例如中。

←ECharts 标题组件

ECharts 图例组件→

ECharts 提示框

您的鼓励是对我最大的支持