怎么自定义 Chart.js Tooltip 提示框内容与样式

图 0：Chart.js Tooltip 提示框自定义两大核心路径概览

一、Tooltip 内置样式的精细化配置

在现代 Chart.js（v3 及 v4 版本）中，提示框的所有配置均统一收拢在 options.plugins.tooltip 命名空间下。Canvas 原生提示框具备极高的渲染性能，不需要开发者手动维护 DOM 元素，因此在绝大多数常规业务报表场景中，优先通过内置属性调整样式是最高效的做法。

内置样式配置主要覆盖提示框的容器外观、文本排版以及指示点（Color Box）的视觉形态。

图 1：Chart.js Tooltip 视觉组件与配置项映射解构

1. 常用样式属性速查与配置示例

以下代码展示了如何精细定制提示框的外观，包括设置半透明深蓝背景、圆角、内边距、自定义字体以及隐藏默认的色块小方块：

const config = {
  type: 'line',
  data: chartData,
  options: {
    responsive: true,
    plugins: {
      tooltip: {
        // 1. 容器外观配置
        enabled: true,                       // 开启内置提示框
        backgroundColor: 'rgba(44, 62, 80, 0.95)', // 提示框底色（支持 HEX 与 RGBA）
        borderColor: '#6487A5',              // 边框描边颜色
        borderWidth: 1.5,                    // 边框粗细
        cornerRadius: 8,                     // 提示框圆角弧度（v3+ 亦可用 borderRadius）
        padding: 12,                         // 内边距，也可传 { top: 10, bottom: 10, left: 14, right: 14 }
        
        // 2. 指针箭头（Caret）配置
        caretSize: 6,                        // 小三角箭头像素大小
        caretPadding: 6,                     // 箭头与激活数据点间的距离
        
        // 3. 标题样式
        titleColor: '#FFFFFF',               // 标题文字颜色
        titleFont: {
          size: 14,
          weight: 'bold',
          family: "'PingFang SC', 'Microsoft YaHei', sans-serif"
        },
        titleMarginBottom: 8,                // 标题下方的间距
        
        // 4. 正文样式
        bodyColor: '#E2E8F0',                // 正文条目颜色
        bodyFont: {
          size: 13,
          lineHeight: 1.4
        },
        bodySpacing: 6,                      // 多个数据条目之间的行距
        
        // 5. 数据小色块（Color Box）
        displayColors: true,                 // 是否显示数据对应的数据集颜色小方块
        boxWidth: 10,                        // 色块宽度
        boxHeight: 10,                       // 色块高度
        boxPadding: 6,                       // 色块与正文文字之间的间隙
        usePointStyle: false,                // 是否使用数据集 points 的形状替代矩形方块
        
        // 6. 页脚样式
        footerColor: '#C28B68',              // 底部汇总文字颜色
        footerFont: {
          size: 12,
          weight: 'bold'
        },
        footerMarginTop: 8                   // 页脚上方的分割间距
      }
    }
  }
};

二、使用 Callbacks 回调深度定制文本内容

仅改变文字颜色与背景往往无法满足真实业务需求，例如展示带货币符号的金额（如“¥ 12,800”）、追加百分比单位、在悬停时动态计算多条折线的合计数，或显示服务端附带的扩展字段。这时需要使用 callbacks 回调函数。

图 2：Tooltip 文本生命周期与 Callbacks 回调执行流程

1. 核心回调函数及其应用场景

Chart.js 在渲染 Tooltip 前，会按照固定生命周期顺序依次调用以下核心回调：

• callbacks.title(tooltipItems)：返回提示框顶部的标题字符串或字符串数组。参数为当前激活的数据项数组。
• callbacks.beforeBody(tooltipItems)：在正文条目之前插入全局描述信息。
• callbacks.label(context)：最常用的钩子。每条被激活的数据都会执行一次，用于输出单条数据的具体展示文本。
• callbacks.afterLabel(context)：紧随单条 label 之后输出补充说明，如同比环比、占比等。
• callbacks.footer(tooltipItems)：提示框底部的统计或总结行，适合做数据求和、平均值计算。

2. 实用的 Callbacks 完整代码示例

下面的例子演示了如何利用 callbacks 完成三项高频需求：格式化金额千分位、追加单位、以及在 footer 动态计算选中项的总和：

const chartOptions = {
  responsive: true,
  plugins: {
    tooltip: {
      callbacks: {
        // 1. 自定义标题：在日期后附加星期几
        title: function(tooltipItems) {
          const item = tooltipItems[0];
          return `日期：${item.label}（统计周期）`;
        },

        // 2. 自定义条目标签：增加业务标签与千分位货币格式化
        label: function(context) {
          let label = context.dataset.label || '';
          if (label) {
            label += '：';
          }
          // 读取原始数据值
          const val = context.raw;
          if (val !== null && val !== undefined) {
            // 格式化为人民币千分位
            label += new Intl.NumberFormat('zh-CN', {
              style: 'currency',
              currency: 'CNY',
              maximumFractionDigits: 0
            }).format(val);
          }
          return label;
        },

        // 3. 自定义补充信息：通过返回字符串数组实现自动换行
        afterLabel: function(context) {
          // 支持直接读取绑定在 data 对象上的自定义字段
          const rawItem = context.raw;
          if (typeof rawItem === 'object' && rawItem.note) {
            return `备注: ${rawItem.note}`;
          }
          return null;
        },

        // 4. 自定义页脚：计算当前列所有数据集的总合计
        footer: function(tooltipItems) {
          let sum = 0;
          tooltipItems.forEach(function(tooltipItem) {
            sum += Number(tooltipItem.raw) || 0;
          });
          return `全部渠道总计: ¥${sum.toLocaleString('zh-CN')}`;
        }
      }
    }
  }
};

三、终极方案：基于 External 回调实现完全自定义 HTML 提示框

由于 Canvas 无法原生承载复杂排版（如带背景高亮、带图片缩略图、多列复杂表格）或者带有交互动作（如“点击复制”、“查看详情”链接）的卡片，Chart.js 提供了 external 钩子函数。配置此钩子后，开发者可以完全关闭 Canvas 内部绘制，并将提示框状态委派给页面上的标准 HTML DOM 节点。

图 3：External HTML Tooltip 定位计算与 DOM 渲染模型

1. External HTML Tooltip 完整实现代码

实现外部 HTML 提示框需要三个核心步骤：创建或复用浮层 DOM、根据 tooltipModel 更新内容、结合 canvas.offsetLeft/offsetTop 与 caretX/caretY 进行绝对定位。

// 1. 获取或创建单例 Tooltip DOM 容器
function getOrCreateTooltip(chart) {
  let tooltipEl = chart.canvas.parentNode.querySelector('.custom-chartjs-tooltip');

  if (!tooltipEl) {
    tooltipEl = document.createElement('div');
    tooltipEl.className = 'custom-chartjs-tooltip';
    // 基础定位与视觉样式
    tooltipEl.style.position = 'absolute';
    tooltipEl.style.background = '#2C3E50';
    tooltipEl.style.color = '#FFFFFF';
    tooltipEl.style.borderRadius = '8px';
    tooltipEl.style.padding = '12px 16px';
    tooltipEl.style.boxShadow = '0 8px 24px rgba(0, 0, 0, 0.15)';
    tooltipEl.style.transition = 'all 0.15s ease-out';
    tooltipEl.style.pointerEvents = 'none'; // 防止鼠标移入提示框自身引起闪烁
    tooltipEl.style.zIndex = '999';

    // 挂载在图表容器（容器须设置 position: relative）
    chart.canvas.parentNode.appendChild(tooltipEl);
  }

  return tooltipEl;
}

// 2. external 处理器核心逻辑
function externalTooltipHandler(context) {
  const { chart, tooltip } = context;
  const tooltipEl = getOrCreateTooltip(chart);

  // 如果提示框透明度为 0，说明当前未悬停在任何数据上，执行隐藏
  if (tooltip.opacity === 0) {
    tooltipEl.style.opacity = '0';
    return;
  }

  // 拼接 HTML 内容
  if (tooltip.body) {
    const titleLines = tooltip.title || [];
    const bodyLines = tooltip.body.map(b => b.lines);

    let innerHtml = '<div style="font-weight: bold; margin-bottom: 6px; font-size: 13px;">';
    titleLines.forEach(title => {
      innerHtml += title;
    });
    innerHtml += '</div>';

    innerHtml += '<div style="font-size: 12px; line-height: 1.6;">';
    bodyLines.forEach((body, i) => {
      const colors = tooltip.labelColors[i];
      const style = `
        display: inline-block;
        background: ${colors.backgroundColor};
        border: 1px solid ${colors.borderColor};
        width: 10px;
        height: 10px;
        border-radius: 2px;
        margin-right: 6px;
      `;
      innerHtml += `<div style="display: flex; align-items: center;">
        <span style="${style}"></span>
        <span>${body}</span>
      </div>`;
    });
    innerHtml += '</div>';

    tooltipEl.innerHTML = innerHtml;
  }

  // 计算绝对定位坐标
  const position = chart.canvas.getBoundingClientRect();
  const parentPosition = chart.canvas.parentNode.getBoundingClientRect();

  // 坐标计算：以父容器为原点，叠加 Canvas 相对偏移与 Caret 相对坐标
  const left = chart.canvas.offsetLeft + tooltip.caretX;
  const top = chart.canvas.offsetTop + tooltip.caretY;

  // 定位与渐显
  tooltipEl.style.opacity = '1';
  tooltipEl.style.left = left + 'px';
  tooltipEl.style.top = top + 'px';
  tooltipEl.style.transform = 'translate(-50%, -110%)'; // 居中并浮动于数据点上方
}

// 3. 在图表配置中启用
const chartConfig = {
  type: 'bar',
  data: myData,
  options: {
    plugins: {
      tooltip: {
        enabled: false, // 关闭 Canvas 内置提示框，完全交由 external 接管
        external: externalTooltipHandler
      }
    }
  }
};

四、方案选型矩阵与高频避坑排查指南

在实际项目落地时，选择最轻量适用的方案能显著降低代码维护成本并保障运行性能。

图 4：Chart.js Tooltip 自定义方案选型矩阵与排查速查

排查 Checklist：常见问题与修复对策

• 样式配置不生效：首先检查 Chart.js 版本。在 v3 及更高版本中，必须编写为 options.plugins.tooltip，而非旧版的 options.tooltips。
• 取值为 undefined 或报错：在 v2 中常用的 tooltipItem.yLabel 已被移除，在 v3/v4 中应使用 tooltipItem.raw 读取原始数值，或使用 tooltipItem.formattedValue 读取格式化文本。
• External 提示框发生剧烈闪烁抖动：这是因为光标移入生成的外层 HTML DOM 节点后，触发了 Canvas 的 mouseout 事件导致隐藏，隐藏后又触发 mousemove 重新显示。解决方法是在浮层 CSS 中添加 pointer-events: none;。
• 提示框被图表外层容器截断：检查图表父级容器是否设置了 overflow: hidden。若必须设置 overflow: hidden，则应将外部 Tooltip 挂载至 document.body，并结合 getBoundingClientRect() 计算全局屏幕坐标。

综上所述，常规的样式调整优先采用 options.plugins.tooltip 原生配置，文本数据的加工和运算采用 callbacks 回调链；仅当需要复杂的 HTML/CSS 特效或组件交互时，再引入 external 处理器。通过合理分层选型，既能保持图表的高性能，又能满足多样化的产品设计要求。