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

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

在 AmCharts5 的 tooltip 文本渲染中，需要了解它与 v4 版本的一个关键区别：v5 不再支持在模板中直接内嵌 JavaScript 表达式。例如，`{2 * valueY}` 或 `{customFunction(valueY)}` 这类写法在 v5 中无法使用。所有动态计算都必须通过外部逻辑完成。官方推荐两种途径：formatter 适用于简单的数值转换，而 adapters 则能应对更复杂的上下文访问和多字段组合场景。

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

当仅需要对 valueY 这样的单一数值进行数学变换时——例如取绝对值、乘以某个倍数或添加单位——formatter 是最简洁的选择。需要注意的是，formatter 函数接收的是原始数值（而非对象），且仅对 valueY 字段生效：

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 无法满足，因为它无法直接访问这些字段，此时应使用方案二。

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

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

// 定义你的自定义格式化函数
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，甚至自定义属性）；
• 支持异步操作、条件判断、国际化处理等复杂逻辑；
• 与 tooltipText 完全解耦，渲染方式完全由开发者控制。

关键注意事项

• 不建议同时使用 formatter 和 adapters：两者功能重叠，同时设置可能导致不可预期的覆盖。从实际使用角度，优先推荐 adapters，灵活性更高。
• tooltipDataItem 是核心对象：它是当前 tooltip 关联的数据项，所有原始数据均通过 `.get("fieldName")` 方法访问。
• 注意性能影响：Adapter 函数在每次 tooltip 显示或更新时都会触发，应避免在其中执行耗时操作，如 DOM 查询或大型计算。
• 空值防护不可忽略：务必检查 dataItem 和字段值是否存在，否则 undefined 可能导致运行时错误。

通过合理选择 formatter 或 adapters，可以完全掌控 AmCharts5 tooltip 的文本呈现逻辑，不再受模板语法限制，真正实现“所想即所得”的数据可视化体验。