# 圖例

圖表圖例會顯示圖表上出現的數據集相關資訊。

# 設定選項

命名空間：options.plugins.legend，圖表圖例的全域選項定義於 Chart.defaults.plugins.legend。

警告

圓環圖、派圖和極地區域圖會覆寫圖例的預設值。若要變更這些圖表類型的覆寫值，選項定義於 Chart.overrides[type].plugins.legend。

名稱	類型	預設值	描述
`display`	`boolean`	`true`	是否顯示圖例？
`position`	`string`	`'top'`	圖例的位置。更多...
`align`	`string`	`'center'`	圖例的對齊方式。更多...
`maxHeight`	`number`		圖例的最大高度，以像素為單位
`maxWidth`	`number`		圖例的最大寬度，以像素為單位
`fullSize`	`boolean`	`true`	標記此方塊應佔用畫布的完整寬度/高度（移動其他方塊）。在日常使用中不太可能需要變更此值。
`onClick`	`function`		當在標籤項目上註冊點擊事件時呼叫的回呼函數。參數：`[event, legendItem, legend]`。
`onHover`	`function`		當在標籤項目上方註冊 'mousemove' 事件時呼叫的回呼函數。參數：`[event, legendItem, legend]`。
`onLeave`	`function`		當在先前滑鼠懸停的標籤項目外部註冊 'mousemove' 事件時呼叫的回呼函數。參數：`[event, legendItem, legend]`。
`reverse`	`boolean`	`false`	圖例將以相反的順序顯示數據集。
`labels`	`object`		請參閱下方的圖例標籤設定章節。
`rtl`	`boolean`		`true` 表示從右至左渲染圖例。
`textDirection`	`string`	畫布預設值	這將強制在畫布上使用 `'rtl'` 或 `'ltr'` 的文字方向來渲染圖例，而無論畫布上指定的 CSS 為何
`title`	`object`		請參閱下方的圖例標題設定章節。

注意

如果您需要更多視覺自訂功能，請使用 HTML 圖例。

# 位置

圖例的位置。選項包括

'top'
'left'
'bottom'
'right'
'chartArea'

當使用 'chartArea' 選項時，圖例位置目前無法設定，它將始終位於圖表的左側中間。

# 對齊

圖例的對齊方式。選項包括

'start'
'center'
'end'

對於無法辨識的值，預設為 'center'。

# 圖例標籤設定

命名空間：options.plugins.legend.labels

名稱	類型	預設值	描述
`boxWidth`	`number`	`40`	彩色方塊的寬度。
`boxHeight`	`number`	`font.size`	彩色方塊的高度。
`color`	`顏色`	`Chart.defaults.color`	標籤和刪除線的顏色。
`font`	`字體`	`Chart.defaults.font`	請參閱字體
`padding`	`number`	`10`	彩色方塊列之間的間距。
`generateLabels`	`function`		為圖例中的每個項目產生圖例項目。預設實作會傳回顏色方塊的文字 + 樣式。詳細資訊請參閱圖例項目。
`filter`	`function`	`null`	從圖例中篩選出圖例項目。接收 2 個參數，一個圖例項目和圖表資料。
`sort`	`function`	`null`	排序圖例項目。類型為：`sort(a: LegendItem, b: LegendItem, data: ChartData): number;`。接收 3 個參數，兩個圖例項目和圖表資料。函數的傳回值是一個數字，表示兩個圖例項目參數的順序。排序方式符合 `Array.prototype.sort()` 的傳回值 (在新視窗開啟)
`pointStyle`	`pointStyle`	`'circle'`	如果指定，此點樣式會用於圖例。僅在 `usePointStyle` 為 true 時使用。
`textAlign`	`string`	`'center'`	標籤文字的水平對齊方式。選項包括：`'left'`、`'right'` 或 `'center'`。
`usePointStyle`	`boolean`	`false`	標籤樣式將與對應的點樣式匹配（大小基於 pointStyleWidth 或 boxWidth 和 font.size 之間的最小值）。
`pointStyleWidth`	`number`	`null`	如果 `usePointStyle` 為 true，則用於圖例的點樣式的寬度。
`useBorderRadius`	`boolean`	`false`	標籤的 borderRadius 將與對應的 borderRadius 匹配。
`borderRadius`	`number`	`未定義`	覆寫要使用的 borderRadius。

# 圖例標題設定

命名空間：options.plugins.legend.title

名稱	類型	預設值	描述
`color`	`顏色`	`Chart.defaults.color`	文字的顏色。
`display`	`boolean`	`false`	是否顯示圖例標題。
`font`	`字體`	`Chart.defaults.font`	請參閱字體
`padding`	`Padding`	`0`	標題周圍的間距。
`text`	`string`		字串標題。

# 圖例項目介面

傳遞到圖例 onClick 函數的項目是從 labels.generateLabels 傳回的項目。這些項目必須實作下列介面。

{
    // Label that will be displayed
    text: string,
    // Border radius of the legend item.
    // Introduced in 3.1.0
    borderRadius?: number | BorderRadius,
    // Index of the associated dataset
    datasetIndex: number,
    // Fill style of the legend box
    fillStyle: Color,
    // Text color
    fontColor: Color,
    // If true, this item represents a hidden dataset. Label will be rendered with a strike-through effect
    hidden: boolean,
    // For box border. See https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap
    lineCap: string,
    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
    lineDash: number[],
    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
    lineDashOffset: number,
    // For box border. See https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin
    lineJoin: string,
    // Width of box border
    lineWidth: number,
    // Stroke style of the legend box
    strokeStyle: Color,
    // Point style of the legend box (only used if usePointStyle is true)
    pointStyle: string | Image | HTMLCanvasElement,
    // Rotation of the point in degrees (only used if usePointStyle is true)
    rotation: number
}

# 範例

以下範例將建立一個啟用圖例的圖表，並將所有文字的顏色設為紅色。

const chart = new Chart(ctx, {
    type: 'bar',
    data: data,
    options: {
        plugins: {
            legend: {
                display: true,
                labels: {
                    color: 'rgb(255, 99, 132)'
                }
            }
        }
    }
});

# 自訂點擊動作

當點擊圖例中的項目時，想要觸發不同的行為是很常見的。這可以使用設定物件中的回呼函數輕鬆實現。

預設的圖例點擊處理程序為

function(e, legendItem, legend) {
    const index = legendItem.datasetIndex;
    const ci = legend.chart;
    if (ci.isDatasetVisible(index)) {
        ci.hide(index);
        legendItem.hidden = true;
    } else {
        ci.show(index);
        legendItem.hidden = false;
    }
}

假設我們想要改為連結前兩個數據集的顯示。我們可以相應地變更點擊處理程序。

const defaultLegendClickHandler = Chart.defaults.plugins.legend.onClick;
const pieDoughnutLegendClickHandler = Chart.controllers.doughnut.overrides.plugins.legend.onClick;
const newLegendClickHandler = function (e, legendItem, legend) {
    const index = legendItem.datasetIndex;
    const type = legend.chart.config.type;
    if (index > 1) {
        // Do the original logic
        if (type === 'pie' || type === 'doughnut') {
            pieDoughnutLegendClickHandler(e, legendItem, legend)
        } else {
            defaultLegendClickHandler(e, legendItem, legend);
        }
    } else {
        let ci = legend.chart;
        [
            ci.getDatasetMeta(0),
            ci.getDatasetMeta(1)
        ].forEach(function(meta) {
            meta.hidden = meta.hidden === null ? !ci.data.datasets[index].hidden : null;
        });
        ci.update();
    }
};
const chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            legend: {
                onClick: newLegendClickHandler
            }
        }
    }
});

現在，當您點擊此圖表中的圖例時，前兩個數據集的能見度將會連結在一起。

← 佈局地區設定 →