# 图例

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://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
}

# 示例

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.