怎么在JS饼状图中显示百分比及自定义提示框

一、核心实现机制与准备工作

饼状图的本质是将一维离散数值映射为圆周角度（360 度或 2π 弧度）。在原生配置中，图表引擎只知道每个数据项的绝对数值 value。当需要在界面上展现百分比时，系统必须经历“获取单项值 → 累计计算数据集总和（Sum） → 计算比值（Value / Sum） → 格式化为百分比文本”的处理链条。

为了保证图表能够正常挂载与渲染，页面需先提供一个具备显式宽度和高度的 DOM 容器，并准备符合图表标准的数据结构。以常用的对象数组为例：

// 标准饼图数据源格式
const chartData = [
  { name: '核心业务模块', value: 850 },
  { name: '增值订阅服务', value: 560 },
  { name: '定制交付项目', value: 350 },
  { name: '日常运维保障', value: 240 }
];

围绕标题要求的两个核心任务，标准开发流程由数据初始化、扇区标签百分比设置、交互提示框定制，以及最终的边界防御校验四个步骤顺畅衔接。

二、在饼图扇区上显示百分比标签

饼图扇区的文字展示依赖于 series[i].label 配置项。根据不同的业务需求，可以在扇区外侧通过引折线（LabelLine）指引，或者直接将文字嵌入扇区内侧。

1. ECharts 模板字符串法

在 Apache ECharts 中，底层渲染引擎已经预先计算好各分项的占比，并注入了专用的占位变量：

• {a}：系列名称（Series name）
• {b}：数据项名称（Item name）
• {c}：数值（Value）
• {d}：计算所得的百分比数值（Percent，已由引擎计算为 0~100 的实数）

若只需在扇区旁同时展示名称与百分比，配置一行模板字符串即可生效：

// ECharts 基础模板方式
series: [
  {
    type: 'pie',
    radius: ['40%', '70%'],
    data: chartData,
    label: {
      show: true,
      position: 'outside',
      formatter: '{b}: {d}%' // 直接输出：核心业务模块: 42.5%
    },
    labelLine: {
      show: true,
      length: 15,
      length2: 10
    }
  }
]

2. ECharts 函数回调精确控制法

当需要自定义小数位数、附加单位或根据数值动态增减说明文字时，应当将 formatter 声明为一个回调函数。函数入参接收当前数据项的详细参数对象 params：

// ECharts 回调函数方式
label: {
  show: true,
  formatter: function(params) {
    // params.percent 为 ECharts 内部自动算出的占比
    // params.value 为原始数值
    const formattedPercent = Number(params.percent).toFixed(1);
    return `${params.name}\n${params.value} 个 (${formattedPercent}%)`;
  }
}

3. Chart.js 中的百分比标签实现

与 ECharts 内置占比变量不同，Chart.js 默认不支持直接输出百分比。在 Chart.js 中，通常结合官方推荐的 chartjs-plugin-datalabels 插件，在插件的回调钩子中自主计算总和：

// Chart.js 配合 datalabels 插件
const config = {
  type: 'pie',
  data: {
    labels: ['核心业务', '增值服务', '定制项目', '日常运维'],
    datasets: [{
      data: [850, 560, 350, 240]
    }]
  },
  options: {
    plugins: {
      datalabels: {
        formatter: (value, ctx) => {
          // 累加当前数据集总和
          const total = ctx.chart.data.datasets[0].data.reduce((sum, val) => sum + val, 0);
          if (total === 0) return '0.0%';
          const percentage = ((value / total) * 100).toFixed(1) + '%';
          return percentage;
        },
        color: '#2C3E50',
        font: { weight: 'bold', size: 12 }
      }
    }
  }
};

三、定制交互提示框（Tooltip）的内容与视觉样式

提示框是用户通过鼠标滑动或手机触碰扇区时唤起的信息浮层。默认的提示框通常为单行纯文本，信息维度单一。通过自定义提示框，可以构建层次清晰的富文本卡片。

1. 触发模式与基本样式容器

饼图提示框的触发类型应设为 trigger: 'item'（代表单项触发，区别于折线图的 axis 坐标轴触发）。同时，建议为提示框指定背景颜色、边框半径与阴影，使其与页面整体 UI 风格和谐统一。

2. ECharts 富文本 Tooltip 回调实现

在 ECharts 中，tooltip.formatter 支持返回一段标准的 HTML 字符串。ECharts 会将该字符串动态注入到底层的绝对定位 DOM 节点中：

// ECharts 高级自定义提示框配置
tooltip: {
  trigger: 'item',
  confine: true, // 关键配置：防止提示框溢出图表容器被裁剪
  backgroundColor: '#FFFFFF',
  borderColor: '#E2DDD5',
  borderWidth: 1,
  padding: [12, 16],
  extraCssText: 'box-shadow: 0 4px 12px rgba(44, 62, 80, 0.08); border-radius: 8px;',
  formatter: function(params) {
    // params 包含 marker (对应扇区颜色的圆点标记)、name、value、percent
    const val = Number(params.value).toLocaleString('zh-CN');
    const pct = Number(params.percent).toFixed(1);
    
    return `
      <div style="font-family: -apple-system, sans-serif; font-size: 13px; color: #2C3E50; min-width: 160px;">
        <div style="font-weight: 600; font-size: 14px; margin-bottom: 8px; border-bottom: 1px solid #ECE8E1; padding-bottom: 4px;">
          ${params.name}
        </div>
        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 6px;">
          <span style="color: #607274; display: flex; align-items: center;">
            ${params.marker} 原始数值
          </span>
          <span style="font-weight: 600;">${val} 万元</span>
        </div>
        <div style="display: flex; justify-content: space-between; align-items: center;">
          <span style="color: #607274;">总额占比</span>
          <span style="color: #879B88; font-weight: 700; font-size: 15px;">${pct} %</span>
        </div>
      </div>
    `;
  }
}

四、方案对比：模板字符串标记法 vs 函数回调计算法

在配置百分比与自定义提示框时，开发者通常面临“模板字符串标记法”与“函数回调计算法”两种截然不同的实现方式。在相同的数据集与渲染环境条件下，这两种方案在多个维度展现出关键差异，直接决定了项目的开发效率与长期可维护性。

为什么理解这种差异至关重要？
许多开发者在项目初期往往因为模板字符串书写便捷而选用模板法，但随着业务发展，产品提出“数值加千分位逗号”、“负数警示飘红”、“在提示框中加入同比环比”等要求时，模板标记法便完全无法胜任，必须重构为回调函数。因此，最佳工程实践是：对于静态不变、仅需基础展示的原型报表，优先采用模板法保证轻量；而对于企业级中后台、财务核算与涉及多指标联动的交互仪表盘，应从一开始就采用函数回调法。

五、生产环境高频边界问题与防坑指南

在实际工程开发中，如果只考虑常规非零正数输入，图表往往在特定极端测试或边缘数据场景下出现视觉错乱或计算崩溃。以下是必须落实的四项关键防御措施：

1. 分母为零导致产生 NaN%

当后端接口返回的数据集所有项均为 0，或者数据尚未拉取完毕为空数组时，累计总和为 0。若直接执行 (value / total) * 100，计算结果为 NaN，界面会尴尬地显示 NaN%。

// 分母为 0 严格防御
function calculatePercentage(value, total) {
  if (!total || total === 0 || isNaN(total)) {
    return '0.0%';
  }
  return ((value / total) * 100).toFixed(1) + '%';
}

2. 四舍五入累加不等于 100% 的经典误差

例如三个切片占比分别为 33.333%...，四舍五入保留一位小数后均为 33.3%，三者相加仅为 99.9%；反之亦可能出现相加等于 100.1% 的情况。在严格的财务或审计页面中，这种误差会导致用户对数据的准确性产生质疑。

解决方案：末位补差算法。在前 N-1 项使用常规的 toFixed(1)，最后一项的百分比则通过 100 - 前(N-1)项之和 强制计算得出，从而在视觉呈现上确保所有百分比之和严格对齐 100.0%。

3. 提示框超出父容器产生裁切

当饼图贴近页面边缘或嵌套在 overflow: hidden 的卡片容器内时，浮动的 Tooltip 经常有一半被截断在视口之外。在 ECharts 中，务必在 tooltip 配置中设置 confine: true，这会强制指示引擎：当提示框靠近边界时，自动向反方向反折显示，始终留在容器边界内。

六、完整可运行的 ECharts 示例与验证

以下提供一份开箱即用、具备完备异常防御与高质量样式的完整 HTML 页面代码。读者可将其保存为本地 .html 文件，在现代浏览器中直接双击打开运行：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>JS饼状图百分比及自定义提示框验证</title>
  <!-- 引入 ECharts 官方 CDN -->
  <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
  <style>
    body {
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      background-color: #F5F4F0;
      margin: 0;
    }
    #chart-box {
      width: 720px;
      height: 480px;
      background: #FFFFFF;
      border-radius: 12px;
      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.06);
      padding: 20px;
    }
  </style>
</head>
<body>
  <div id="chart-box"></div>

  <script>
    // 1. 初始化容器
    const chartDom = document.getElementById('chart-box');
    const myChart = echarts.init(chartDom);

    // 2. 准备业务数据
    const rawData = [
      { name: '核心业务模块', value: 8520, growth: '+12.5%' },
      { name: '增值订阅服务', value: 5610, growth: '+8.2%' },
      { name: '定制交付项目', value: 3500, growth: '-2.1%' },
      { name: '日常运维保障', value: 2410, growth: '+4.0%' }
    ];

    // 预计算总和（用于防范边界）
    const totalSum = rawData.reduce((acc, cur) => acc + cur.value, 0);

    // 3. 配置项
    const option = {
      backgroundColor: '#FFFFFF',
      title: {
        text: '业务板块贡献占比分析',
        left: 'center',
        top: 20,
        textStyle: { color: '#2C3E50', fontSize: 16, fontWeight: 'bold' }
      },
      color: ['#687D8D', '#879B88', '#A4B5A5', '#8CA1B0'],
      tooltip: {
        trigger: 'item',
        confine: true,
        backgroundColor: '#FFFFFF',
        borderColor: '#E2DDD5',
        borderWidth: 1,
        padding: [12, 16],
        extraCssText: 'box-shadow: 0 4px 16px rgba(44, 62, 80, 0.1); border-radius: 8px;',
        formatter: function(params) {
          if (!totalSum) return `${params.name}: 无数据`;
          const itemVal = Number(params.value).toLocaleString('zh-CN');
          const itemPct = Number(params.percent).toFixed(1);
          const growth = params.data.growth || '0.0%';
          const growthColor = growth.startsWith('+') ? '#687D8D' : '#C0392B';

          return `
            <div style="font-family: -apple-system, sans-serif; font-size: 13px; color: #2C3E50; min-width: 170px;">
              <div style="font-weight: bold; font-size: 14px; margin-bottom: 8px; border-bottom: 1px solid #ECE8E1; padding-bottom: 4px;">
                ${params.name}
              </div>
              <div style="display: flex; justify-content: space-between; margin-bottom: 5px;">
                <span style="color: #607274;">${params.marker} 绝对产值:</span>
                <span style="font-weight: 600;">${itemVal} 万元</span>
              </div>
              <div style="display: flex; justify-content: space-between; margin-bottom: 5px;">
                <span style="color: #607274;">占比分析:</span>
                <span style="color: #879B88; font-weight: bold; font-size: 15px;">${itemPct} %</span>
              </div>
              <div style="display: flex; justify-content: space-between;">
                <span style="color: #607274;">同比变化:</span>
                <span style="color: ${growthColor}; font-weight: 600;">${growth}</span>
              </div>
            </div>
          `;
        }
      },
      legend: {
        bottom: 20,
        itemWidth: 12,
        itemHeight: 12,
        textStyle: { color: '#607274', fontSize: 12 }
      },
      series: [
        {
          name: '业务板块',
          type: 'pie',
          radius: ['38%', '68%'],
          center: ['50%', '50%'],
          avoidLabelOverlap: true,
          itemStyle: {
            borderRadius: 6,
            borderColor: '#FFFFFF',
            borderWidth: 2
          },
          label: {
            show: true,
            position: 'outside',
            formatter: '{b}\n{d}%',
            lineHeight: 18,
            fontSize: 12,
            color: '#2C3E50'
          },
          labelLine: {
            show: true,
            length: 12,
            length2: 15,
            smooth: true
          },
          data: rawData
        }
      ]
    };

    // 4. 载入配置
    myChart.setOption(option);

    // 5. 自适应窗口调整
    window.addEventListener('resize', () => myChart.resize());
  </script>
</body>
</html>

运行与结果验证

在浏览器中成功运行上述脚本后，读者应当观察到以下明确的视觉与交互反馈：

1. 扇区外部引线清晰可见：环形饼图四周通过平滑折线标注分类名称，并在第二行清晰展示形如 42.5% 的百分比字样，互不挤压叠盖。
2. 鼠标悬停即时触发富文本卡片：将光标悬停至任意扇区，浮层平滑弹出，呈现对应色标小圆点、千分位格式化的金额、强化高亮的绿色百分比以及同比增幅指标。
3. 视口自适应防裁切：当鼠标移动至画布最右侧或最上方时，提示框能自适应反转停留在图表矩形区域之内，不会被外层边界切除。