AmCharts5自定义Tooltip文本格式完整实现指南

在 AmCharts5 中，无法直接在 labelText 模板中执行 JavaScript 表达式（如 {Math.abs(valueY)}），但可通过 adapters 或 formatter 灵活实现任意数值格式化逻辑，包括绝对值、倍数运算或自定义函数处理。

聊到 AmCharts5 的 tooltip 文本渲染，得先说说它和 v4 版本的一个关键区别：v5 不再支持在模板里直接内嵌 JS 表达式了。像 `{2 * valueY}` 或者 `{customFunction(valueY)}` 这种写法，在 v5 里是行不通的。所有动态计算都得通过外部逻辑来完成。官方推荐了两条路：formatter 适合简单的数值转换，而 adapters 则能应对更复杂的上下文访问和多字段组合场景。掌握 AmCharts5 tooltip 格式化技巧，能显著提升数据可视化的灵活性与用户体验。

✅ 方案一：使用 formatter 进行基础数值格式化

当只需要对 valueY 这样一个单一数值做数学变换时——比如取绝对值、乘以某个倍数，或者添加个单位——formatter 是最简洁的选择。不过要注意，formatter 函数接收的是原始数值（不是对象），而且只对 valueY 字段生效。这种 AmCharts5 自定义 tooltip 文本的方式非常适合简单场景：

var series2 = chart.series.push(
  am5xy.LineSeries.new(root, {
    name: "Expenses",
    xAxis: xAxis,
    yAxis: yAxis,
    valueYField: "expenses",
    categoryXField: "year",
    tooltip: am5.Tooltip.new(root, {
      pointerOrientation: "horizontal",
      // formatter 接收 valueY 原始值，返回格式化后的字符串
      formatter: function(value) {
        return Math.abs(value) + " $"; // 示例：绝对值 + 单位
      }
    }),
    tooltipText: "{name}: {valueY}" // 此处 {valueY} 仅作占位，实际由 formatter 覆盖
  }));

不过这里有个小坑：tooltipText 里的 `{valueY}` 虽然写着，但它并不会被自动格式化，它的作用仅仅是触发 tooltip 显示。真正生效的是 formatter 的返回值。如果还需要显示其他字段，比如 `{categoryX}`，那 formatter 就无能为力了——它会直接访问不到，这时候就得用方案二。在 AmCharts5 tooltip 定制过程中，理解这种机制差异至关重要。

✅ 方案二：使用 adapters 实现全字段动态定制

当需要组合多个数据字段（比如 `{name}`、`{categoryX}`、`{valueY}`），或者要调用自定义函数、执行条件逻辑时，adapters 是唯一推荐的方式。它直接劫持 tooltip 标签的 text 属性，给你完整的上下文访问能力，是实现 AmCharts5 tooltip 文本自定义的终极方案：

// 定义你的自定义格式化函数
function customFun(value) {
  if (value === null || value === undefined) return "—";
  return (value * 2).toFixed(2); // 示例：2 倍并保留两位小数
}

// 为 tooltip 的 label 绑定 text adapter
series2.get("tooltip").label.adapters.add("text", function(text, target) {
  const dataItem = series2.get("tooltipDataItem");
  if (!dataItem) return text;
  const name = series2.get("name") || "";
  const year = dataItem.get("categoryX") || "";
  const expenses = dataItem.get("valueY");
  return `${name} in ${year}: $${customFun(expenses)}`;
});

这个方案的优势很明显：

• 可以安全地访问 tooltipDataItem，拿到当前悬停点的所有字段（categoryX、valueY，甚至自定义属性）；
• 支持异步操作、条件判断、国际化处理这些复杂逻辑，极大拓展了 AmCharts5 自定义 tooltip 的能力边界；
• 和 tooltipText 完全解耦，你怎么渲染完全由你说了算。

关键注意事项

• 别把 formatter 和 adapters 混着用：两者功能重叠，同时设置可能会导致不可预期的覆盖。从实际使用来看，优先推荐用 adapters，灵活性更高，能满足绝大多数 AmCharts5 tooltip 格式化需求。
• tooltipDataItem 是核心：它是当前 tooltip 关联的数据项对象，所有原始数据都通过 `.get("fieldName")` 来访问。
• 性能方面要留个心：Adapter 函数在每次 tooltip 显示或更新时都会触发，所以尽量避免在里面做耗时操作，比如 DOM 查询或者大型计算。
• 空值防护不能少：务必检查 dataItem 和字段值是否存在，不然 undefined 可能会在运行时给你来个意外惊喜。

通过合理选择 formatter 或 adapters，你就能完全掌控 AmCharts5 tooltip 的文本呈现逻辑了。不用再受模板语法的限制，真正实现“所想即所得”的数据可视化体验。无论是简单的数值转换还是复杂的多字段组合，AmCharts5 tooltip 定制都能轻松应对。