# 图例

¥Legend

图表图例显示有关图表上出现的数据集的数据。

¥The chart legend displays data about the datasets that are appearing on the chart.

# 配置选项

¥Configuration options

命名空间：options.plugins.legend，图表图例的全局选项在 Chart.defaults.plugins.legend 中定义。

¥Namespace: options.plugins.legend, the global options for the chart legend is defined in Chart.defaults.plugins.legend.

警告

圆环图、饼图和极面积图会覆盖图例默认值。要更改这些图表类型的覆盖，选项在 Chart.overrides[type].plugins.legend 中定义。

¥The doughnut, pie, and polar area charts override the legend defaults. To change the overrides for those chart types, the options are defined in 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 图例。

¥If you need more visual customizations, please use an HTML legend.

# 位置

¥Position

图例的位置。选项是：

¥Position of the legend. Options are:

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

使用 'chartArea' 选项时，图例位置目前不可配置，它始终位于图表中间的左侧。

¥When using the 'chartArea' option the legend position is at the moment not configurable, it will always be on the left side of the chart in the middle.

# 对齐

¥Align

图例的对齐方式。选项是：

¥Alignment of the legend. Options are:

'start'
'center'
'end'

对于无法识别的值，默认为 'center'。

¥Defaults to 'center' for unrecognized values.

# 图例标签配置

¥Legend Label Configuration

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

¥Namespace: options.plugins.legend.labels

名称	类型	默认	描述
`boxWidth`	`number`	`40`	彩色框的宽度。
`boxHeight`	`number`	`font.size`	彩色框的高度。
`color`	`Color`	`Chart.defaults.color`	标签颜色和删除线。
`font`	`Font`	`Chart.defaults.font`	见字体
`padding`	`number`	`10`	在彩色框行之间填充。
`generateLabels`	`function`		为图例中的每个事物生成图例项。默认实现返回颜色框的文本 + 样式。详见图例条目。
`filter`	`function`	`null`	从图例中过滤出图例项。接收 2 个参数，一个图例条目和图表数据。
`sort`	`function`	`null`	对图例项进行排序。Type is : `sort(a: LegendItem, b: LegendItem, data: ChartData): number;`。接收 3 个参数，两个图例条目和图表数据。该函数的返回值是一个数字，表示两个图例项参数的顺序。顺序与 `Array.prototype.sort()` 的返回值 (opens new window) 匹配
`pointStyle`	`pointStyle`	`'circle'`	如果指定，这种样式的点将用于图例。仅在 `usePointStyle` 为真时使用。
`textAlign`	`string`	`'center'`	标签文本的水平对齐方式。选项是：`'left'`、`'right'` 或 `'center'`。
`usePointStyle`	`boolean`	`false`	标签样式将匹配相应的点样式（大小基于 pointStyleWidth 或 boxWidth 和 font.size 之间的最小值）。
`pointStyleWidth`	`number`	`null`	如果 `usePointStyle` 为真，则为用于图例的点样式的宽度。
`useBorderRadius`	`boolean`	`false`	标签 borderRadius 将匹配相应的 borderRadius。
`borderRadius`	`number`	`undefined`	覆盖要使用的 borderRadius。

# 图例标题配置

¥Legend Title Configuration

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

¥Namespace: options.plugins.legend.title

名称	类型	默认	描述
`color`	`Color`	`Chart.defaults.color`	文本的颜色。
`display`	`boolean`	`false`	是否显示图例标题。
`font`	`Font`	`Chart.defaults.font`	见字体
`padding`	`Padding`	`0`	在标题周围填充。
`text`	`string`		字符串标题。

# 图例条目界面

¥Legend Item Interface

传递给图例 onClick 函数的项目是从 labels.generateLabels 返回的项目。这些项目必须实现以下接口。

¥Items passed to the legend onClick function are the ones returned from labels.generateLabels. These items must implement the following interface.

{
    // 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://web.nodejs.cn/en/docs/Web/API/CanvasRenderingContext2D/lineCap
    lineCap: string,
    // For box border. See https://web.nodejs.cn/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash
    lineDash: number[],
    // For box border. See https://web.nodejs.cn/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset
    lineDashOffset: number,
    // For box border. See https://web.nodejs.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
}

# 示例

¥Example

以下示例将创建一个启用图例的图表，并将所有文本变为红色。

¥The following example will create a chart with the legend enabled and turn all the text red in color.

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

# 自定义点击操作

¥Custom On Click Actions

单击图例中的项目时，通常希望触发不同的行为。这可以使用配置对象中的回调轻松实现。

¥It can be common to want to trigger different behaviour when clicking an item in the legend. This can be easily achieved using a callback in the config object.

默认的图例点击处理程序是：

¥The default legend click handler is:

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;
    }
}

假设我们想要链接前两个数据集的显示。我们可以相应地更改点击处理程序。

¥Let's say we wanted instead to link the display of the first two datasets. We could change the click handler accordingly.

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
            }
        }
    }
});

现在，当你单击此图表中的图例时，前两个数据集的可见性将链接在一起。

¥Now when you click the legend in this chart, the visibility of the first two datasets will be linked together.