# 图例

图表图例显示图表上显示的数据集的相关信息。

# 配置选项

命名空间：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`	从图例中过滤掉图例项。接收两个参数，一个图例项和图表数据。
`sort`	`function`	`null`	对图例项进行排序。类型为：`sort(a: LegendItem, b: LegendItem, data: ChartData): number;`。接收三个参数，两个图例项和图表数据。函数的返回值是一个数字，它指示两个图例项参数的顺序。排序与返回值 (在新窗口打开) 的 `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`	`undefined`	覆盖要使用的 borderRadius。

# 图例标题配置

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

名称	类型	默认值	描述
`color`	`颜色`	`Chart.defaults.color`	文本颜色。
`display`	`boolean`	`false`	图例标题是否显示。
`font`	`字体`	`Chart.defaults.font`	参见字体
`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://mdn.org.cn/en/docs/Web/API/CanvasRenderingContext2D/lineCap
    lineCap: string,
    // For box border. See https://mdn.org.cn/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
    lineDash: number[],
    // For box border. See https://mdn.org.cn/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
    lineDashOffset: number,
    // For box border. See https://mdn.org.cn/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
            }
        }
    }
});

现在，当您点击此图表中的图例时，前两个数据集的可见性将相互链接。

← 布局区域设置 →