工具提示

工具提示配置

命名空間：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	畫布的預設值	這將強制在畫布上使用 '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 (在新視窗開啟) 的函數。此函數也可以接受第三個參數，該參數是傳遞給圖表的資料物件。

篩選回呼

允許篩選工具提示項目。必須至少實作一個可以傳遞給 Array.prototype.filter (在新視窗開啟) 的函數。此函數也可以接受第四個參數，該參數是傳遞給圖表的資料物件。

工具提示回呼

命名空間：options.plugins.tooltip.callbacks，工具提示具有以下回呼，用於提供文字。對於所有函數，this 將是從 Tooltip 建構函式建立的工具提示物件。如果回呼傳回 undefined，則將使用預設回呼。若要從工具提示中移除內容，回呼應傳回空字串。

命名空間：data.datasets[].tooltip.callbacks，在 資料集覆寫 欄中標記為 是 的項目可以針對每個資料集覆寫。

會為每個出現在工具提示中的項目產生工具提示項目內容。這是回呼方法互動的主要模型。對於傳回文字的函數，字串陣列會被視為多行文字。

名稱	引數	傳回類型	資料集覆寫	描述
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	是	傳回要在個別標籤之前渲染的文字。這將針對工具提示中的每個項目呼叫。
label	TooltipItem	string | string[] | undefined	是	傳回要在工具提示中為個別項目渲染的文字。更多...
labelColor	TooltipItem	object | undefined	是	傳回要為工具提示項目渲染的顏色。更多...
labelTextColor	TooltipItem	Color | undefined	是	傳回工具提示項目標籤文字的顏色。
labelPointStyle	TooltipItem	object | undefined	是	如果 usePointStyle 為 true，則傳回要使用的點樣式，而不是彩色方塊（具有 pointStyle 和 rotation 值的物件）。預設實作使用來自資料集點的點樣式。更多...
afterLabel	TooltipItem	string | string[] | undefined	是	傳回要在個別標籤之後渲染的文字。
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>;
  }
}