5.4 图例项目
图例由一个或者多个图例项目构成。每个图例项目对应绘图区的一个数据列。通过图例项目，可以帮助浏览者更好地操作数据列。本节将详细讲解图例项目的各种设置。
5.4.1 图例项目的构成
图例项目通常由图例符号和图例标签构成，如图5.15所示。图例符号同数据列的节点符号保持一致，用以区分每个数据列。所以，图例符号需要在数据列组件series指定。图例标签用来说明图例符号所代表的含义。通常，图例标签的文本也是由数据列组件series指定。
图5.15 图例项目的构成
在组件legend中，能够对图例符号和图例标签的位置和样式进行指定。下面依次讲解如何设置这两部分。
5.4.2 图例项目的基本设置
由于图例项目构成简单，所以对其本身设置也相对简单。下面简要讲解常用的两个设置。
1．设置图例项目宽度
默认情况下，图例项目的宽度Highcharts是自动计算的。由于每个图例标签的文本长度不固定，所以每个图例项目长度不固定。当图例项目多余一行时会折行显示，这个时候往往造成上下图例项目无法对齐，如图5.16所示。
图5.16 无法上下对齐的图例项目
这时，可以通过配置项itemWidth指定项目宽度，让项目对齐。其语法如下：
itemWidth: Number
其中，参数Number指定图例项目的宽度，单位为px。
【实例5-8：itemWidth】下面为图例项目设定固定宽度，以保证图例项目上下对齐。代码如下：
legend: {
itemWidth:150 //设置图例项目固定宽度
}
执行代码后，效果如图5.17所示。
图5.17 设置固定宽度的图例项目
从图中可以看到，上下两行的图例项目可以垂直左对齐。设置宽度时，设置的值不能太小。否则，会造成图例项目重叠显示，如图5.18所示。
图5.18 设置太小的后果
2．设置图例符号和标签的顺序
在图例中，图例符号默认显示在标签前面，这样方便用户根据数据列查阅说明。当一个图表中数据列较多时，浏览者往往需要直接查阅指定的数据列。这个时候，标签放到后面不方便用户查找。为了解决这个问题，Highcharts提供了配置项rtl，用来反转两者的前后顺序。其语法如下：
rtl: Boolean
其中，rtl值类型为布尔类型。当值为true时，反转显示。否则，不反转显示。默认值为false。
【实例5-9：rtl】为了方便浏览者根据年份查询天气温度，修改实例5-8的代码。修改代码如下：
legend: {
itemWidth:150,
rtl:true //设置图例符号和标签反转
}
执行代码后，效果如图5.19所示。这时，标签就显示在图例的前面了。浏览者可以快速根据标签找到对应的数据列。
图5.19 图例符号和图例标签反转显示
5.4.3 图例符号
虽然图例项目在图例区中显示，但是图例符号却是在对应的数据列中定义的。图例区只是从数据列中提取对应的符号进行显示。图例符号的显示一般有两种形式。下面依次讲解这两种方式。
1．横线+图例符号
第一种形式是横线+图例符号形式，如图5.20所示。一条宽度为2px的横线贯穿图例符号。
图5.20 横线+图例符号
对于这种形式的图例，用户可以设置横线的长度，以及图例符号和后面文字的间距。设置横线长度需要使用配置项symbolWidth。其语法如下：
symbolWidth: Number
其中，参数Number指定横线的长度，单位为px。默认值为16。当设置的宽度小于图例符号的宽度，则值显示图例符号本身。
【实例5-10：symbolWidth】下面设置图例符号宽度为0，代码如下：
legend: {
itemWidth:150,
symbolWidth:0 //设置图例符号宽度
}
执行代码后，效果如图5.21所示。这时，图例符号的横线消失了，只有图例符号本身。
图5.21 图例符号宽度为0
除了设置横线长度以外，用户还可以设置图例符号和图例标签的间距。这时，需要使用配置项symbolPadding。其语法如下：
symbolPadding: Number
其中，参数Number指定间距值，单位为px，默认值为5。
2．矩形图例符号
当图表是条形图和柱形图时，图例符号均为矩形，如图5.22所示。这时用户不仅可以设置图例符号的宽度和间距，还可以设置图例符号的高度和圆角半径。
图5.22 矩形图例符号
设置图例符号的高度和圆角半径，需要使用配置项symbolHeight和symbolRadius。其语法如下：
symbolHeight: Number1 symbolRadius: Number2
其中，参数Number1设置矩形图例符号的高度，单位为px，默认值为12；参数Number2设置矩形图例符号的圆角半径，单位为px，默认值为2。
5.4.4 图例标签
虽然图例标签的文本提取自数据列组件serial中，但用户也可以对其进行显示格式的修改，并做一定格式化修改。下面依次讲解这两个方面。
1．显示格式修改
在Highcharts中，只要是文本标签，就默认支持文本内容中格式标签，如<b>、<strong>、<i>、<em>、<br/>和<span>。如果这些标签无法满足用户的需要，用户还可以通过配置项useHTML来启用HTML渲染。其语法如下：
useHTML: Boolean
其中，useHTML的值类型为布尔类型。当值为true时，启用HTML渲染，这时标签中可以使用复杂的HTML样式标记；当值为false时，禁用HTML渲染。默认值为false。
注意：当该配置项设置为true后，会禁用图例的导航功能。
2．标签文本格式化
很多时候，为了保持数据的单一性，往往不会把数据和格式混杂在一起。这个时候，可以通过个格式化配置项来修改。修改的方式有两种，下面依次讲解。
（1）使用配置项labelFormat。
配置项labelFormat可以采用字符串嵌入式的方式，对标签文本进行格式化。其语法如下：
labelFormat: String
其中，参数String是字符串。在该字符串中可以嵌入原有的值。默认值为{name}。
【实例5-11：labelFormat】下面修改图例标签的文字为斜体。代码如下：
legend: {
itemWidth: 150,
labelFormat:'<i>{name}</i>' //设置斜体效果
}
执行代码后，图例区效果如图5.23所示。从图中可以看出，在不修改原有数据列名字的前提下，原有的字体变为斜体。
图5.23 设置图例标签文本为斜体
（2）使用配置项labelFormatter。
由于字段串嵌入的形式比较单一，所以无法完成复杂的处理。这时，可以使用配置项labelFormatter。该配置项的值为一个回调函数，可以完成更为复杂的格式化。其语法如下：
labelFormatter: Function
其中，参数Function是一个回调函数，以回调函数的返回值作为图例标签的内容。
【实例5-12：labelFormatter】下面截取数据列serial名称的一部分作为图例标签文本。修改代码如下：
legend: {
itemWidth: 150,
labelFormatter: function () { //设置格式化回调函数
return this.name.substring(0,6); //截取前六个字符
}
}
执行代码后，图例区效果如图5.24所示。
图5.24 截短后的图例标签
这里只是简单的演示。用户可以根据自己的需要，定制更为复杂、强大的格式化回调函数。
5.4.5 图例项目的布局
图例项目可以帮助用户更好地查阅数据。当图例项目较多的时候，需要合理地设置其布局方式。下面详细讲解图例的各种布局问题。
1．设置图例项目的水平间距
在前面的介绍中，我们讲解了如何控制图例符号的宽度、图例符号和标签的间距、图例标的宽度。除了这几个宽度和间距外，影响图例项目水平排列的因素还有图例项目之间的间距。Highcharts默认为图例项目设置了水平间距。用户可以通过配置项itemDistance修改这个间距。其语法如下：
itemDistance: Number
其中，参数Number指定图例项目之间的间距，单位为px。默认值为20。
【实例5-13：itemDistance】下面修改图例项目之间的间距，使得图例项目由原有的两行显示变为3行显示。修改代码如下：
legend: {
//itemWidth: 150,
itemDistance:80 //设置图例项目之间的间距
}
执行代码后，效果如图5.25所示。从图中可以明显看出，图例项目改为两列、三行显示了。
图5.25 设置图例项目的间距
注意：一旦设置配置项itemWidth后，配置项itemDistance就无法生效了。
2．设置图例项目的排列方式
图例项目的默认排列方式为水平排列。用户也可以通过配置项layout修改排列方位为垂直排列。其语法如下：
layout: String
其中，参数String指定排列方式，允许的值包括horizontal（水平）和vertical（垂直）。默认值是horizontal。
【实例5-14：layout】下面使用垂直方式排列图例项目。修改代码如下：
legend: {
layout:'vertical' //设置图例项目垂直对齐
}
执行代码后，效果如图5.26所示。从图中可以看到，图例项目已经垂直排列，每行只有一个图例项目。
图5.26 垂直排列图例项目
使用垂直排列方式后，当图例项目较多的时候，图例项目会压缩绘图区的大小。这个时候，可以调整图例区的对齐方式，将其修改为水平右对齐，修改代码如下：
legend: {
layout: 'vertical',
align: 'right', //设置水平右对齐
verticalAlign: 'middle',
y:60
}
执行代码后，效果如图5.27所示。
图5.27 调整后的图例项目
3．设置图例项目外边距
除了能设置图例项目之间的间距，用户还可以设置图例项目的上下边距，来调整图例项目的间距。这时，需要使用配置项itemMarinBottom和itemMarinTop。其语法如下：
itemMarginBottom: Number1 itemMarginTop: Number2
其中，参数Number1表示图例项目的下边距，单位为px，默认值为0；参数Number2表示图例项目的上边距，单位为px，默认值也为0。
【实例5-15：itemMargin】下面为图例项目添加上下边距，修改代码如下：
legend: {
itemDistance: 80,
itemMarginBottom: 10, //设置下边距
itemMarginTop:10 //设置上边距
}
执行代码后，效果如图5.28所示。
图5.28 设置图例项目的上下边距
4．倒序排列图例项目
在图表中，图例项目的顺序和数据列添加的顺序一致。当用户希望强调最后添加的数据列，可以将图例项目的显示顺序颠倒。这时需要通过配置项reversed设置。其语法如下：
reversed: Boolean
其中，reversed的值为布尔类型，允许的值为true和false。当设置为true时，逆序显示图例项目；否则，顺序显示图例项目。默认值为false。
【实例5-16：reversed】下面逆序显示图例项目，强调最后添加的数据列。修改代码如下：
legend: {
itemDistance: 80,
reversed:true //设置逆序显示图例项目
}
执行代码后，效果如图5.29所示。从图中看出，图例项目按照2013、2014和2015的顺序显示。这与数据列添加数据的顺序刚好相反。
图5.29 逆序显示图例项目
5.4.6 图例项目的状态
图例和数据列是一一对应。当数据列较多的时候，直接在图表中操作数据列就不是很方便了。为了方便用户操作，Highcharts允许用户通过图例来操作数据列。例如，当用户单击图例，就可以在绘图区中隐藏对应的数据列。再次单击该图例，又可以显示该数据列。
为了方便用户进行操作，每个图例被设置了3种状态：显示状态、鼠标悬浮状态和隐藏数据列状态，如图5.30所示。每种状态下，图例通过不同的CSS样式进行修饰。下面依次讲解这3种状态。
图5.30 图例的三种状态
1．显示状态
图表加载后，数据列被显示在绘图区，此时图例处于显示状态。这也是默认状态。用户可以通过配置项itemStyle来设置该状态下的图例样式。其语法如下：
itemStyle: CSSObject
其中，参数CSSObject用来设置图例项目显示状态下的CSS样式。默认值如下：
{
"Color": "#333333",
"cursor": "pointer",
"fontSize": "12px",
"fontWeight":"bold"
}
2．悬浮状态
当鼠标移动到图例项目的上方，为了方便用户确认单击鼠标所操作的数据列，对应的图例会改变部分的显示样式。用户可以通过配置项itemHiddenStyle重新设置该状态的CSS样式。其语法如下：
itemHoverStyle: CSSObject
其中，参数CSSObject用来设置鼠标悬浮在图例项目上的CSS样式。默认值如下：
{
color: '#000'
}
由于悬浮状态修改样式较少，所以鼠标移动到图例上的样式变化最为小。为了提醒用户操作，往往会对该样式做比较多的修改。
3．隐藏状态
当单击处于显示状态的图例项目时，图例项目往往会变成灰色，并且隐藏对应的数据列。用户也可以设置配置项itemHiddenStyle改变默认的隐藏状态。其语法如下：
itemHiddenStyle: CSSObject
其中，参数CSSOjbect用来设置图例项目隐藏状态下的CSS样式。默认值如下：
{
color: '#CCC'
}