AGGrid自定义cellRenderer下tooltipShowMode不生效如何处理?

摘要

AG Grid 中设置tooltipShowMode: 'whenTruncated'后，普通单元格可以只在文本被截断时显示 tooltip；但如果列使用cellRendererSelector或自定义 cell renderer，tooltip 逻辑会换到 renderer 内部。本文基于 AG Grid 官方 issue 回复，整理setTooltip(value, shouldDisplayTooltip)的使用方式。

问题背景

一个常见需求是：表格里有一列描述文本，内容很长时用省略号显示；鼠标悬停时，只在文本被截断的情况下显示完整 tooltip。普通列上可以这样配置：

constgridOptions={tooltipShowMode:"whenTruncated",columnDefs:[{field:"description",tooltipField:"description"}]};

但当这一列改成自定义 renderer，尤其是通过cellRendererSelector动态选择 renderer 时，开发者可能会发现：即使内容没有截断，tooltip 仍然显示；或者tooltipShowMode像没有生效一样。

AG Grid issue #13779 讨论的就是这个现象。官方维护者给出的结论是：这不是单纯的回归 bug。列级别的tooltipShowMode: 'whenTruncated'是基于 Grid 自己渲染的单元格文本判断截断状态；当单元格内容由自定义 renderer 接管后，tooltip 应该由 renderer 通过setTooltip(value, shouldDisplayTooltip)自己注册。

官方回复要点

AG Grid 维护者说明：

1. tooltipShowMode: 'whenTruncated'依赖 Grid 自身的 cell text。
2. 自定义 cell renderer，包括由cellRendererSelector选出的 renderer，需要在 renderer 内部调用setTooltip。
3. setTooltip的第二个参数shouldDisplayTooltip是条件函数，适合放“当前内容是否被截断”的判断。
4. 如果使用enableBrowserTooltips，该条件回调不适用，因为浏览器原生 tooltip 不由 Grid 控制。

所以，正确思路不是继续在 column definition 上堆 tooltip 配置，而是让自定义 renderer 对自己渲染的 DOM 负责。

实现步骤

第一步，给自定义 renderer 的文本元素保留可测量的 DOM 引用。下面示例以 React cell renderer 为例：

import { useLayoutEffect, useRef } from "react"; import type { CustomCellRendererProps } from "ag-grid-react"; type RowData = { id: number; description: string; kind: "short" | "long"; }; export function DescriptionRenderer( props: CustomCellRendererProps<RowData, string> ) { const textRef = useRef<HTMLSpanElement | null>(null); const tooltipValue = String(props.value ?? ""); const { setTooltip } = props; useLayoutEffect(() => { setTooltip(tooltipValue, () => { const el = textRef.current; return !!el && el.scrollWidth > el.clientWidth; }); }, [setTooltip, tooltipValue]); return ( <span ref={textRef} className="cell-ellipsis"> {tooltipValue} </span> ); }

对应样式要真正造成截断，否则scrollWidth > clientWidth永远不会成立：

.cell-ellipsis{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}

第二步，在列定义中使用该 renderer。即便全局仍保留tooltipShowMode: 'whenTruncated'，自定义 renderer 这列也要靠setTooltip自己判断。

constcolumnDefs=[{field:"id",width:100},{field:"description",cellRendererSelector:params=>{return{component:DescriptionRenderer,params:{emphasis:params.data?.kind==="long"}};}}];

第三步，确认没有启用浏览器原生 tooltip：

constgridOptions={enableBrowserTooltips:false,tooltipShowMode:"whenTruncated",columnDefs};

enableBrowserTooltips: true时，tooltip 行为交给浏览器，AG Grid 文档也说明setTooltip的条件回调不适用。想要“只在截断时显示”，应使用 Grid tooltip 机制。

排查清单

1. 确认这一列是否使用了cellRenderer或cellRendererSelector。如果是，优先检查 renderer 内部是否调用了setTooltip。
2. 检查用于测量的元素是否就是实际被截断的元素，而不是外层容器。
3. 检查 CSS 是否同时具备overflow: hidden、text-overflow: ellipsis和white-space: nowrap。
4. 确认enableBrowserTooltips没有被设为true。
5. 如果单元格内容会异步变化，确保变化后重新调用setTooltip或触发 renderer 刷新。
6. 如果 renderer 内有图标、按钮、标签等复杂结构，不要只根据字符串长度判断，要测量真实 DOM 宽度。

版本与注意事项

原 issue 的复现场景是 AG Grid35.3.0和 React。本文示例按当前 AG Grid React 文档中的CustomCellRendererProps与setTooltip机制整理。

示例未在当前工作区绑定对应版本的 AG Grid 依赖进行编译；不同主版本的类型导出位置、renderer props 命名可能略有差异，请以项目所用版本的 API 文档和 IntelliSense 为准。

此外，tooltipShowMode: 'whenTruncated'并不是“所有 tooltip 的全局截断判断器”。它适合 Grid 自己渲染文本的场景；当你接管单元格 DOM 后，就需要接管 tooltip 的显示条件。

总结

这个问题的关键不在于tooltipShowMode写错了，而在于单元格的渲染职责已经从 Grid 转移到了自定义 renderer。普通列可以让 Grid 判断文本是否截断；自定义 renderer 则应使用setTooltip注册 tooltip，并通过shouldDisplayTooltip测量自己的 DOM 是否溢出。这样才能让“只在截断时显示 tooltip”的规则和真实 UI 保持一致。

内容来源说明

• 官方问答来源：AG Grid GitHub issue #13779，维护者于 2026-06-19 给出解释并关闭 issue。
• API 核查来源：
  • https://github.com/ag-grid/ag-grid/issues/13779
  • https://www.ag-grid.com/react-data-grid/component-cell-renderer/#dynamic-tooltips
  • https://www.ag-grid.com/react-data-grid/tooltips/