十一、基礎教程-圖例（Legend）

圖例是圖表中用不同形狀、顏色、文字等 標示不同數據列，通過點擊標示可以顯示或隱藏該數據列；通過設置 legend.enabled = true | false 來打開或關閉圖例。

一、 圖例樣式

1、圖例容器樣式

圖例容器指的是整個圖例容器的樣式，包含背景、邊框、邊距、寬度等，詳細屬性及說明見下表

參數名	解釋	默認值
backgroundColor	背景顏色	null
borderColor	邊框顏色	‘#909090’
margin	外邊距	15
padding	內邊距	8
maxHeight	最大高度	null
navigation	導航，當設置了最大高度後，圖例無法完整顯示時，則會用導航的形式展示（分頁）
shadow	圖例陰影效果，賦值可以是 boolean 或 Object	false
width	圖例寬度	null
verticalAlign	垂直對齊方式，有 ‘top’， ‘middle’ 及 ‘bottom’ 可選	‘bottom’
useHTML	是否以HTML形式渲染（默認是SVG渲染），當使用 HTML 模式渲染是，圖例導航無效	false

2、圖例項樣式

上面說到了圖例容器的樣式可以控制圖例整體樣式，對應配置圖例裏的內容是通過圖例項相關屬性來控制的，見下表

參數名	解釋	默認值
itemDistance	圖例項間距	20
itemStyle	圖例樣式	itemStyle: { cursor: ‘pointer’, color: ‘#3E576F’ }
itemHiddenStyle	圖例隱藏時的樣式	itemHiddenStyle: { color: ‘#CCC’ }
itemHoverStyle	圖例鼠標劃過時樣式	itemHoverStyle: { color: ‘#000’ }
itemMarginBottom	圖例項底邊距	0
itemMarginTop	圖例項頂部邊距	0
itemWidth	圖例項寬度	null
symbolHeight	圖例項標示高度	12
symbolRadius	圖例項標示圓角	2
symbolWidth	圖例項標示寬度	16

二、圖例內容及定位

1. 圖例內容

|       參數名         |                       解釋                      |               默認值             |
|----------------       |-------------------                            |               ---                 |
|labelFormat|圖例文字格式化字符串 |{name}|
|labelFormatter|圖例內容格式化函數|function() { return this.name}|
|reversed|是否倒序|false|
|rtl|文字是否顯示在符號前面，主要針對閱讀習慣從右至左的用戶|false|
|title|圖例標題 |title: { text: null, style: { fontWeight: "blod"}}|
關於格式化函數及格式化字符串這裏簡單說明如下：

labelFormatter: function() {
   /*
    *  格式化函數可用的變量：this， 可以用 console.log(this) 來查看包含的詳細信息
    *  this 代表當前數據列對象，所以默認的實現是 return this.name 
    */
    return  this.name + '(Click to hide or show)';
} 

labelFormat 格式化字符是格式化函數的一種簡寫方式，即用包含變量的字符串代替函數。

labelFormat: '{name} (Click to hide or show)'; 

2. 定位

|       參數名         |                       解釋                      |               默認值             |
|----------------       |-------------------                            |               ---                 |
| align|圖例在圖表中的對齊方式，有 “left”, "center", "right" 可選|“center”|
|floating|圖例是否浮動，設置浮動後，圖例將不佔位置|false|
|layout|圖例內容佈局方式，有水平佈局及垂直佈局可選，對應的配置值是： “horizontal”， “vertical”|"horizontal"|
|x|水平偏移|0|
|y|豎直偏移|0|

三、圖例點擊事件

1、默認圖例點擊事件

圖例默認的點擊行爲是顯示或隱藏當前數據列。

plotOptions: {
  series: {
    events: {
        legendItemClick: function(e) {
            /*
             * 默認實現是顯示或隱藏當前數據列，e 代表事件， this 爲當前數據列
             */
        }
    }
  }
} 

2、禁用圖例點擊隱藏效果

plotOptions: {
  series: {
    events: {
        legendItemClick: function(e) {
            return false; // 直接 return false 即可禁用圖例點擊事件
        }
    }
  }
} 

3、餅圖圖表點擊事件

上述代碼對餅圖是無效的，因爲餅圖的扇區是數據點對象，所有針對數據列的配置函數當然無效。
對於餅圖對應 legendItemClick 事件是 point.legengItemClick 。

plotOptions: {
  pie: {
    point: {
        events: {
            legendItemClick: function(e) {
                return false; // 直接 return false 即可禁用圖例點擊事件
            }
        }
    }
  }
}

4、自定義圖例點擊事件

默認是點擊某個圖例顯示或隱藏當前數據列，這裏改變爲點擊某個圖例只顯示當前數據列，隱藏其他數據列

plotOptions: {
    series: {
        events: {
            legendItemClick: function(e) {
                var index = this.index;
                var series = this.chart.series;
                if (!series[index].visible) {
                    for (var i = 0; i < series.length; i++) {
                        var s = series[i];
                        i === index ? s.show() : s.hide();
                    }
                }
                return false;
            }
        }
    }
}

四、關於圖例的常見問題

以下列舉出關於圖例的常見問題，

1、如何不顯示某個圖例

series: [{
    data: [],
    name: "",
    showInLegend: false // 設置爲 false 即爲不顯示在圖例中
}, {
    data: [],
    name: "",
    showInLegend: true // 默認值
}]