feat: add trigger parameter to tooltip interaction

__tests__/plots/animation/fruits-interval-stack-enter-x-color.ts

@@ -18,6 +18,11 @@ export function fruitsIntervalStackEnterXColor(): G2Spec {
         duration: 900,
       },
     },
+    interaction: {
+      tooltip: {
+        trigger: 'element'
+      }
+    }
   };
 }
 

__tests__/plots/api/chart-emit-show-tooltip-with-null.ts

@@ -46,6 +46,7 @@ export function chartEmitShowTooltipWithNull(context) {
     interaction: {
       tooltip: {
         shared: true,
+        trigger: 'element',
       },
       elementHighlight: {
         background: true,

__tests__/unit/api/interaction.spec.ts

@@ -89,3 +89,31 @@ describe('Clear EventEmitter', () => {
     expect(emitter?.getEvents()['legend:filter']).toBeUndefined();
   });
 });
+
+describe('Tooltip Trigger', () => {
+  it('should accept trigger: "plot"', async () => {
+    const chart = createChart();
+    chart.options({
+      interaction: {
+        tooltip: {
+          trigger: 'plot',
+        },
+      },
+    });
+    await chart.render();
+    expect(chart.getContext().canvas).toBeDefined();
+  });
+
+  it('should accept trigger: "element"', async () => {
+    const chart = createChart();
+    chart.options({
+      interaction: {
+        tooltip: {
+          trigger: 'element',
+        },
+      },
+    });
+    await chart.render();
+    expect(chart.getContext().canvas).toBeDefined();
+  });
+});

site/docs/manual/component/tooltip.en.md

@@ -356,7 +356,8 @@ When configuring `tooltip.items` for composite charts, you need to configure nod
 | sort          | Item sorter                                                                                                              | `(d: TooltipItemValue) => any`                                                                                         | -                             |                              |
 | trailing      | Whether to update tooltip at the end of time interval                                                                    | `boolean`                                                                                                              | `false`                       |                              |
 | wait          | Time interval for tooltip update in milliseconds                                                                         | `number`                                                                                                               | `50`                          |                              |
-| clickLock          | The toolyip is locked after a mouse click.   | `boolean`          | `false`|    |
+| clickLock     | The tooltip is locked after a mouse click                                                                               | `boolean`                                                                                                              | `false`                       |                              |
+| trigger       | Tooltip activation mode                                                                         | `'plot'` \| `'element'`                                                                                                | `'plot'`                      |                    |
 
 #### crosshairs
 

site/docs/manual/component/tooltip.zh.md

@@ -356,7 +356,8 @@ chart.options({
 | sort          | item 排序器                                                                                                       | `(d: TooltipItemValue) => any`                                                                                         | -                              |                      |
 | trailing      | 是否在时间间隔结束的时候更新提示信息                                                                              | `boolean`                                                                                                              | `false`                        |                      |
 | wait          | 提示信息更新的时间间隔，单位为毫秒                                                                                | `number`                                                                                                               | `50`                           |                      |
-| clickLock          | 鼠标点击后锁定 tooltip   | `boolean`          | `false`|    |
+| clickLock     | 鼠标点击后锁定 tooltip                                                                                          | `boolean`                                                                                                              | `false`                        |                      |
+| trigger       | 提示信息激活模式                                                                            | `'plot'` \| `'element'`                                                                                                | `'plot'`                       |                 |
 
 #### crosshairs
 

src/interaction/tooltip.ts

@@ -199,7 +199,10 @@ function destroyTooltip({ root, single }) {
 
 function showUndefined(item) {
   const { value } = item;
-  return { ...item, value: value === undefined ? 'undefined' : value };
+  // Handle undefined and null values to display them properly in tooltip
+  if (value === undefined) return { ...item, value: 'undefined' };
+  if (value === null) return { ...item, value: 'null' };
+  return item;
 }
 
 function heatmapItem(element) {
@@ -633,6 +636,7 @@ function findNearestElementIndex(scale, abstractX): number {
  * @param coordinate - The coordinate system of the chart (e.g., Cartesian, polar).
  * @param scale - The scale configurations (e.g., x, series scales).
  * @param shared - Whether the tooltip is shared among multiple elements (e.g., grouped bars).
+ * @param trigger - Trigger mode: 'plot' (default) for auto-finding nearest element, 'element' for only triggering on element hover.
  * @returns The matched display object or `undefined` if no element is found.
  * @description
  * - Handles bar charts by sorting elements and using bisector search for efficient lookup.
@@ -646,6 +650,7 @@ export function findSingleElement({
   coordinate,
   scale,
   shared,
+  trigger = 'plot',
 }): DisplayObject | undefined {
   const inInterval = (d) => d.markType === 'interval';
   const isBar = elements.every(inInterval) && !isPolar(coordinate);
@@ -687,6 +692,7 @@ export function findSingleElement({
 
   const element = isBar
     ? (event) => {
+        if (trigger === 'element') return findElementByTarget(event);
         const mouse = mousePosition(root, event);
         if (!mouse) return;
         const [abstractX] = coordinate.invert(mouse);
@@ -1220,6 +1226,7 @@ export function tooltip(
     preserve = false,
     css = {},
     clickLock = false,
+    trigger = 'plot',
   }: Record<string, any>,
 ) {
   const elements = elementsof(root);
@@ -1234,6 +1241,7 @@ export function tooltip(
         coordinate,
         scale,
         shared,
+        trigger,
       });
       if (!element) {
         hideTooltip({ root, single, emitter, event });
@@ -1385,6 +1393,7 @@ export function Tooltip(options) {
     name,
     item = () => ({}),
     facet = false,
+    trigger = 'plot',
     ...rest
   } = options;
 
@@ -1465,6 +1474,7 @@ export function Tooltip(options) {
       view,
       theme,
       shared,
+      trigger,
     });
   };
 }

src/spec/interaction.ts

@@ -197,6 +197,7 @@ export type TooltipInteraction = {
   enterable?: boolean;
   sort?: (d: TooltipItemValue) => any;
   filter?: (d: TooltipItemValue) => any;
+  trigger?: 'plot' | 'element';
   render?: (
     event, // @todo
     options: { title: 'string'; items: TooltipItemValue[] },