工具提示 | Chart.js 中文

命名空间：options.plugins.tooltip，图表工具提示的全局选项定义在 Chart.defaults.plugins.tooltip 中。

名称	类型	默认值	描述
`enabled`	`boolean`	`true`	是否启用画布上的工具提示？
`external`	`function`	`null`	参见外部工具提示部分。
`mode`	`string`	`interaction.mode`	设置工具提示中显示哪些元素。更多....
`intersect`	`boolean`	`interaction.intersect`	如果为 true，则工具提示模式仅在鼠标位置与元素相交时应用。如果为 false，则该模式将始终应用。
`position`	`string`	`'average'`	工具提示定位的模式。更多...
`callbacks`	`object`		参见回调部分。
`itemSort`	`function`		对工具提示项进行排序。更多...
`filter`	`function`		过滤工具提示项。更多...
`backgroundColor`	`颜色`	`'rgba(0, 0, 0, 0.8)'`	工具提示的背景颜色。
`titleColor`	`颜色`	`'#fff'`	标题文本的颜色。
`titleFont`	`字体`	`{weight: 'bold'}`	参见字体。
`titleAlign`	`string`	`'left'`	标题文本行的水平对齐方式。更多...
`titleSpacing`	`number`	`2`	添加到每行标题顶部和底部的间距。
`titleMarginBottom`	`number`	`6`	添加到标题部分底部的边距。
`bodyColor`	`颜色`	`'#fff'`	正文文本的颜色。
`bodyFont`	`字体`	`{}`	参见字体。
`bodyAlign`	`string`	`'left'`	正文文本行的水平对齐方式。更多...
`bodySpacing`	`number`	`2`	添加到每个工具提示项顶部和底部的间距。
`footerColor`	`颜色`	`'#fff'`	页脚文本的颜色。
`footerFont`	`字体`	`{weight: 'bold'}`	参见字体。
`footerAlign`	`string`	`'left'`	页脚文本行的水平对齐方式。更多...
`footerSpacing`	`number`	`2`	添加到每行页脚顶部和底部的间距。
`footerMarginTop`	`number`	`6`	在绘制页脚之前添加的边距。
`padding`	`填充`	`6`	工具提示内部的填充。
`caretPadding`	`number`	`2`	将工具提示箭头末端从工具提示点移开的额外距离。
`caretSize`	`number`	`5`	工具提示箭头的尺寸（以像素为单位）。
`cornerRadius`	`number`\|`object`	`6`	工具提示角的圆角半径。
`multiKeyBackground`	`颜色`	`'#fff'`	在工具提示中有多个项目时，在彩色方块后面绘制的颜色。
`displayColors`	`boolean`	`true`	如果为 true，则在工具提示中显示彩色方块。
`boxWidth`	`number`	`bodyFont.size`	如果 displayColors 为 true，则彩色方块的宽度。
`boxHeight`	`number`	`bodyFont.size`	如果 displayColors 为 true，则彩色方块的高度。
`boxPadding`	`number`	`1`	彩色方块与文本之间的填充。
`usePointStyle`	`boolean`	`false`	使用相应的点样式（来自数据集选项）代替彩色方块，例如：星形、三角形等（大小基于 boxWidth 和 boxHeight 的最小值）。
`borderColor`	`颜色`	`'rgba(0, 0, 0, 0)'`	边框的颜色。
`borderWidth`	`number`	`0`	边框的尺寸。
`rtl`	`boolean`		`true` 表示从右到左渲染工具提示。
`textDirection`	`string`	canvas' 默认值	这将强制在画布上渲染工具提示时强制文本方向 `'rtl'` 或 `'ltr'`，而不管在画布上指定的 css 是什么
`xAlign`	`string`	`undefined`	工具提示箭头在 X 方向上的位置。更多
`yAlign`	`string`	`undefined`	工具提示箭头在 Y 方向上的位置。更多

注意

如果您需要更多视觉自定义，请使用 HTML 工具提示。

# 位置模式

可能的模式是

'average'
'nearest'

'average' 模式会将工具提示放置在工具提示中显示的项目的平均位置。'nearest' 会将工具提示放置在最靠近事件位置的元素的位置。

您还可以定义自定义位置模式。

xAlign 和 yAlign 选项定义工具提示箭头的方向。如果这些参数未设置，则会确定最佳的箭头方向。

xAlign 设置支持以下值。

'left'
'center'
'right'

yAlign 设置支持以下值。

'top'
'center'
'bottom'

# 文本对齐方式

titleAlign、bodyAlign 和 footerAlign 选项定义文本行相对于工具提示框的水平位置。支持以下值。

'left'（默认）
'right'
'center'

这些选项仅应用于文本行。彩色方块始终对齐到左边缘。

# 排序回调

允许对工具提示项进行排序。必须至少实现一个可以传递给 Array.prototype.sort (在新窗口中打开) 的函数。此函数还可以接受第三个参数，该参数是传递给图表的 data 对象。

# 过滤回调

允许过滤工具提示项。必须至少实现一个可以传递给 Array.prototype.filter (在新窗口中打开) 的函数。此函数还可以接受第四个参数，该参数是传递给图表的 data 对象。

命名空间：options.plugins.tooltip.callbacks，工具提示具有以下回调，用于提供文本。对于所有函数，this 将是使用 Tooltip 构造函数创建的工具提示对象。如果回调返回 undefined，则将使用默认回调。要从工具提示中删除内容，回调应返回空字符串。

命名空间：data.datasets[].tooltip.callbacks，标记为 Yes 的项（在 Dataset override 列中）可以按数据集进行覆盖。

为工具提示中显示的每个项目生成一个工具提示项上下文。这是回调方法交互的主要模型。对于返回文本的函数，字符串数组将被视为多行文本。

名称	参数	返回值类型	数据集覆盖	描述
`beforeTitle`	`TooltipItem[]`	`string \| string[] \| undefined`		返回在标题之前渲染的文本。
`title`	`TooltipItem[]`	`string \| string[] \| undefined`		返回要作为工具提示标题渲染的文本。
`afterTitle`	`TooltipItem[]`	`string \| string[] \| undefined`		返回在标题之后渲染的文本。
`beforeBody`	`TooltipItem[]`	`string \| string[] \| undefined`		返回在正文部分之前渲染的文本。
`beforeLabel`	`TooltipItem`	`string \| string[] \| undefined`	Yes	返回在单个标签之前渲染的文本。这将针对工具提示中的每个项目调用。
`label`	`TooltipItem`	`string \| string[] \| undefined`	Yes	返回要为工具提示中的单个项目渲染的文本。更多...
`labelColor`	`TooltipItem`	`object \| undefined`	Yes	返回要为工具提示项渲染的颜色。更多...
`labelTextColor`	`TooltipItem`	`颜色 \| undefined`	Yes	返回工具提示项标签文本的颜色。
`labelPointStyle`	`TooltipItem`	`object \| undefined`	Yes	返回要使用的点样式，而不是彩色方块，如果 usePointStyle 为 true（具有值 `pointStyle` 和 `rotation` 的对象）。默认实现使用来自数据集点的点样式。更多...
`afterLabel`	`TooltipItem`	`string \| string[] \| undefined`	Yes	返回在单个标签之后渲染的文本。
`afterBody`	`TooltipItem[]`	`string \| string[] \| undefined`		返回在正文部分之后渲染的文本。
`beforeFooter`	`TooltipItem[]`	`string \| string[] \| undefined`		返回在页脚部分之前渲染的文本。
`footer`	`TooltipItem[]`	`string \| string[] \| undefined`		返回要作为工具提示页脚渲染的文本。
`afterFooter`	`TooltipItem[]`	`string \| string[] \| undefined`		在页脚部分之后渲染的文本。

# 标签回调

label 回调函数可以更改显示给定数据点的文本。一个常见的例子是显示单位。下面的示例在每一行前面添加了 '$'。

const chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            tooltip: {
                callbacks: {
                    label: function(context) {
                        let label = context.dataset.label || '';
                        if (label) {
                            label += ': ';
                        }
                        if (context.parsed.y !== null) {
                            label += new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(context.parsed.y);
                        }
                        return label;
                    }
                }
            }
        }
    }
});

# 标签颜色回调函数

例如，要返回一个红色边框和蓝色虚线边框，并且每个项目都有边框半径的工具提示框，您可以执行以下操作

const chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            tooltip: {
                callbacks: {
                    labelColor: function(context) {
                        return {
                            borderColor: 'rgb(0, 0, 255)',
                            backgroundColor: 'rgb(255, 0, 0)',
                            borderWidth: 2,
                            borderDash: [2, 2],
                            borderRadius: 2,
                        };
                    },
                    labelTextColor: function(context) {
                        return '#543453';
                    }
                }
            }
        }
    }
});

# 标签点样式回调函数

例如，要在工具提示中的每个项目中绘制三角形而不是常规的彩色框，您可以执行以下操作

const chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            tooltip: {
                usePointStyle: true,
                callbacks: {
                    labelPointStyle: function(context) {
                        return {
                            pointStyle: 'triangle',
                            rotation: 0
                        };
                    }
                }
            }
        }
    }
});

传递给工具提示回调函数的工具提示项实现以下接口。

{
    // The chart the tooltip is being shown on
    chart: Chart
    // Label for the tooltip
    label: string,
    // Parsed data values for the given `dataIndex` and `datasetIndex`
    parsed: object,
    // Raw data values for the given `dataIndex` and `datasetIndex`
    raw: object,
    // Formatted value for the tooltip
    formattedValue: string,
    // The dataset the item comes from
    dataset: object
    // Index of the dataset the item comes from
    datasetIndex: number,
    // Index of this data item in the dataset
    dataIndex: number,
    // The chart element (point, arc, bar, etc.) for this tooltip item
    element: Element,
}

# 外部（自定义）工具提示

外部工具提示允许您挂钩到工具提示渲染过程，以便您可以以自己的自定义方式渲染工具提示。通常，这用于创建 HTML 工具提示而不是画布上的工具提示。external 选项接受一个函数，该函数传递一个包含 chart 和 tooltip 的上下文参数。您可以像这样在全局或图表配置中启用外部工具提示

const myPieChart = new Chart(ctx, {
    type: 'pie',
    data: data,
    options: {
        plugins: {
            tooltip: {
                // Disable the on-canvas tooltip
                enabled: false,
                external: function(context) {
                    // Tooltip Element
                    let tooltipEl = document.getElementById('chartjs-tooltip');
                    // Create element on first render
                    if (!tooltipEl) {
                        tooltipEl = document.createElement('div');
                        tooltipEl.id = 'chartjs-tooltip';
                        tooltipEl.innerHTML = '<table></table>';
                        document.body.appendChild(tooltipEl);
                    }
                    // Hide if no tooltip
                    const tooltipModel = context.tooltip;
                    if (tooltipModel.opacity === 0) {
                        tooltipEl.style.opacity = 0;
                        return;
                    }
                    // Set caret Position
                    tooltipEl.classList.remove('above', 'below', 'no-transform');
                    if (tooltipModel.yAlign) {
                        tooltipEl.classList.add(tooltipModel.yAlign);
                    } else {
                        tooltipEl.classList.add('no-transform');
                    }
                    function getBody(bodyItem) {
                        return bodyItem.lines;
                    }
                    // Set Text
                    if (tooltipModel.body) {
                        const titleLines = tooltipModel.title || [];
                        const bodyLines = tooltipModel.body.map(getBody);
                        let innerHtml = '<thead>';
                        titleLines.forEach(function(title) {
                            innerHtml += '<tr><th>' + title + '</th></tr>';
                        });
                        innerHtml += '</thead><tbody>';
                        bodyLines.forEach(function(body, i) {
                            const colors = tooltipModel.labelColors[i];
                            let style = 'background:' + colors.backgroundColor;
                            style += '; border-color:' + colors.borderColor;
                            style += '; border-width: 2px';
                            const span = '<span style="' + style + '">' + body + '</span>';
                            innerHtml += '<tr><td>' + span + '</td></tr>';
                        });
                        innerHtml += '</tbody>';
                        let tableRoot = tooltipEl.querySelector('table');
                        tableRoot.innerHTML = innerHtml;
                    }
                    const position = context.chart.canvas.getBoundingClientRect();
                    const bodyFont = Chart.helpers.toFont(tooltipModel.options.bodyFont);
                    // Display, position, and set styles for font
                    tooltipEl.style.opacity = 1;
                    tooltipEl.style.position = 'absolute';
                    tooltipEl.style.left = position.left + window.pageXOffset + tooltipModel.caretX + 'px';
                    tooltipEl.style.top = position.top + window.pageYOffset + tooltipModel.caretY + 'px';
                    tooltipEl.style.font = bodyFont.string;
                    tooltipEl.style.padding = tooltipModel.padding + 'px ' + tooltipModel.padding + 'px';
                    tooltipEl.style.pointerEvents = 'none';
                }
            }
        }
    }
});

有关如何开始使用外部工具提示的示例，请参阅示例。

工具提示模型包含可用于渲染工具提示的参数。

{
    chart: Chart,
    // The items that we are rendering in the tooltip. See Tooltip Item Interface section
    dataPoints: TooltipItem[],
    // Positioning
    xAlign: string,
    yAlign: string,
    // X and Y properties are the top left of the tooltip
    x: number,
    y: number,
    width: number,
    height: number,
    // Where the tooltip points to
    caretX: number,
    caretY: number,
    // Body
    // The body lines that need to be rendered
    // Each object contains 3 parameters
    // before: string[] // lines of text before the line with the color square
    // lines: string[], // lines of text to render as the main item with color square
    // after: string[], // lines of text to render after the main lines
    body: object[],
    // lines of text that appear after the title but before the body
    beforeBody: string[],
    // line of text that appear after the body and before the footer
    afterBody: string[],
    // Title
    // lines of text that form the title
    title: string[],
    // Footer
    // lines of text that form the footer
    footer: string[],
    // style to render for each item in body[]. This is the style of the squares in the tooltip
    labelColors: TooltipLabelStyle[],
    labelTextColors: Color[],
    labelPointStyles: { pointStyle: PointStyle; rotation: number }[],
    // 0 opacity is a hidden tooltip
    opacity: number,
    // tooltip options
    options: Object
}

# 自定义位置模式

可以通过将函数添加到 Chart.Tooltip.positioners 地图来定义新模式。

示例

import { Tooltip } from 'chart.js';
/**
 * Custom positioner
 * @function Tooltip.positioners.myCustomPositioner
 * @param elements {Chart.Element[]} the tooltip elements
 * @param eventPosition {Point} the position of the event in canvas coordinates
 * @returns {TooltipPosition} the tooltip position
 */
Tooltip.positioners.myCustomPositioner = function(elements, eventPosition) {
    // A reference to the tooltip model
    const tooltip = this;
    /* ... */
    return {
        x: 0,
        y: 0
        // You may also include xAlign and yAlign to override those tooltip options.
    };
};
// Then, to use it...
new Chart.js(ctx, {
    data,
    options: {
        plugins: {
            tooltip: {
                position: 'myCustomPositioner'
            }
        }
    }
})

有关更详细的示例，请参阅示例。

如果您使用的是 TypeScript，您还需要注册新模式

declare module 'chart.js' {
  interface TooltipPositionerMap {
    myCustomPositioner: TooltipPositionerFunction<ChartType>;
  }
}

← 标题面积图 →

# 工具提示

# 工具提示配置