feat(conversion-tag): 转化分析 tag 添加 elements 信息,方便业务上使用 (#2441)

* feat(conversion-tag): 转化分析 tag 添加 elements 信息,方便业务上使用

* docs(conversion-tag): 转化率标签组件的事件交互 文档以及demo说明

* docs: 修改文案

Author: visiky

__tests__/unit/adaptor/conversion-tag-spec.ts

@@ -4,6 +4,7 @@ import { Column, ColumnOptions, Bar, BarOptions } from '../../../src';
 import { createDiv } from '../../utils/dom';
 import { delay } from '../../utils/delay';
 import { near } from '../../utils/number';
+import { dispatchEvent } from '../../utils/event';
 import { subSalesByArea } from '../../data/sales';
 
 const DATA = [
@@ -66,19 +67,27 @@ describe('column conversion tag', () => {
         expect(texts[idx - 1].attr('text')).toBe(((DATA[idx].y / DATA[idx - 1].y) * 100).toFixed(2) + '%');
       }
     });
+    texts.forEach((text, idx) => {
+      // origin info
+      expect(text.get('origin').element).toBe(plot.chart.geometries[0].elements[idx]);
+      expect(text.get('origin').nextElement).toBe(plot.chart.geometries[0].elements[idx + 1]);
+    });
 
     // 箭头
     const arrows = group.findAllByName('conversion-tag-arrow');
     const arrowIds = arrows.map((arrow) => arrow.get('id')) as string[];
     // 每一个都有唯一的 ID
     expect(uniq(arrowIds)).toHaveLength(DATA.length - 1);
     expect(arrows).toHaveLength(DATA.length - 1);
-    arrows.forEach((arrow) => {
+    arrows.forEach((arrow, idx) => {
       const bbox = arrow.getBBox();
       // spacing: 8
       expect(near(bbox.width, totalWidth - 8 * 2)).toBeTruthy();
       // size: 32
       expect(near(bbox.height, 32)).toBeTruthy();
+      // origin info
+      expect(arrow.get('origin').element).toBe(plot.chart.geometries[0].elements[idx]);
+      expect(arrow.get('origin').nextElement).toBe(plot.chart.geometries[0].elements[idx + 1]);
     });
   });
 
@@ -604,3 +613,45 @@ describe('conversion tag disabled with seriesField', () => {
     expect(group).toBeUndefined();
   });
 });
+
+describe('conversion tag listent to events', () => {
+  const container = createDiv();
+
+  const options: ColumnOptions = {
+    data: DATA,
+    autoFit: false,
+    width: 600,
+    height: 400,
+    xField: 'x',
+    yField: 'y',
+    conversionTag: {},
+    animation: false,
+  };
+  const plot = new Column(container, options);
+
+  it('events', async () => {
+    plot.render();
+    let c;
+    plot.on('conversion-tag-group:mouseenter', (evt) => {
+      c = evt?.target;
+    });
+
+    await delay(100);
+
+    const foreground = plot.chart.foregroundGroup;
+    const group: IGroup = foreground.findAllByName('conversion-tag-group')[0] as IGroup;
+    // 箭头
+    const arrows = group.findAllByName('conversion-tag-arrow');
+    const texts = group.findAllByName('conversion-tag-text');
+
+    const canvas = plot.chart.getCanvas();
+    const bbox = arrows[0].getCanvasBBox();
+    dispatchEvent(bbox, canvas, 'mouseenter');
+
+    await delay(100);
+
+    expect(c?.get('id')).toBe(texts[0].get('id'));
+    expect(c?.get('origin').element).toBe(plot.chart.geometries[0].elements[0]);
+    expect(c?.get('origin').nextElement).toBe(plot.chart.geometries[0].elements[1]);
+  });
+});

__tests__/utils/event.ts

@@ -1,4 +1,4 @@
-import { IElement } from '@antv/g2/lib/dependents';
+import { BBox, ICanvas, IElement } from '@antv/g2/lib/dependents';
 
 // 触发 Canvas 上元素的鼠标事件
 export const simulateMouseEvent = (element: IElement, event: string, cfg = {}) => {
@@ -15,3 +15,17 @@ export const simulateMouseEvent = (element: IElement, event: string, cfg = {}) =
   });
   canvas.get('el').dispatchEvent(mouseEvent);
 };
+
+// 触发鼠标事件
+export const dispatchEvent = (bbox: BBox, canvas: ICanvas, event: string, cfg = {}) => {
+  // 设置位置信息为 element 中央
+  const x = bbox.x + bbox.width / 2;
+  const y = bbox.y + bbox.height / 2;
+  const client = canvas.getClientByPoint(x, y);
+  const mouseEvent = new MouseEvent(event, {
+    clientX: client.x,
+    clientY: client.y,
+    ...cfg,
+  });
+  canvas.get('el').dispatchEvent(mouseEvent);
+};

docs/api/components/annotations.en.md

@@ -1,6 +1,6 @@
 ---
-title: Annotation
-order: 4
+title: Annotations
+order: 6
 ---
 
 `markdown:docs/styles/component.md`
@@ -45,12 +45,12 @@ annotations: [
 
 #### Configurations（_AnnotationCfg_）
 
-> ❕ means: _required_
+> ❗️ means: _required_
 
 | Properties    | Type       | Description                               | Apply to             |
 | --- | --- | --- | --- |
-| type ❕| _string_ | 图形标注类型. |
-| position ❕  | _object_ | 标注位置. |
+| type ❗️| _string_ | 图形标注类型. |
+| position ❗️  | _object_ | 标注位置. |
 | animate | _boolean_ | 是否进行动画. |
 | autoAdjust | _boolean_ | 文本超出绘制区域时，是否自动调节文本方向. |
 | start | _array_ | 起始位置. | <tag color="green" text="line"> Line </tag> <tag color="green" text="region"> Region </tag> 

docs/api/components/annotations.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 图表标注
-order: 4
+title: 图表标注 - Annotations
+order: 6
 ---
 
 `markdown:docs/styles/component.md`
@@ -46,12 +46,12 @@ annotations: [
 
 #### 配置项（_AnnotationCfg_）
 
-> ❕ 代表 _必选_
+> ❗️ 代表 _必选_
 
 |   **属性**   |     **类型**        |      **描述** |       **用于**              |
 | --- | --- | --- | --- |
-| type ❕ | _string_ | 图形标注类型. |
-| position ❕  | _object_ | 标注位置. |
+| type ❗️ | _string_ | 图形标注类型. |
+| position ❗️  | _object_ | 标注位置. |
 | animate | _boolean_ | 是否进行动画. |
 | autoAdjust | _boolean_ | 文本超出绘制区域时，是否自动调节文本方向. |
 | start | _array_ | 起始位置. | <tag color="green" text="line"> Line </tag> <tag color="green" text="region"> Region </tag> 

docs/api/components/axis.en.md

@@ -1,6 +1,6 @@
 ---
 title: Axis
-order: 0
+order: 1
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/axis.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 坐标轴
-order: 0
+title: 坐标轴 - Axis
+order: 1
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/conversion-tag.en.md

@@ -0,0 +1,29 @@
+---
+title: ConversionTag
+order: 8
+---
+
+Applicable to base bar charts and base bar charts, the Conversion Rate component allows the user to focus on the rate of change in the data.
+
+#### _ConversionTagCfg_
+
+`markdown:docs/common/conversion-tag.en.md`
+
+#### Events and interactions
+
+<playground path='general/events/demo/conversion-tag-with-link.ts' rid='conversion-tag-events'></playground>
+
+转化标签的图形组成包含 `conversion-tag-arrow` 和 `conversion-tag-text`。同一个图表的转化标签组件都放置于一个 group 下，也就是 `conversion-tag-group`，我们可以通过监听 `conversion-tag-group` 事件来进行一些定制交互。
+
+转化标签携带的原始数据信息包含：上一个图形元素（element）和下一个图形元素（nextElement），可通过下列方式获取：
+
+```ts
+plot.on('conversion-tag-group:mouseenter', (evt) => {
+  const { element, nextElement } = evt.target?.get('origin');
+  // custom by yourself. details of element API, see: https://g2.antv.vision/en/docs/api/general/element
+});
+```
+
+Example：
+
+<playground path='general/events/demo/conversion-tag-with-link.ts' rid='conversion-tag-events'></playground>

docs/api/components/conversion-tag.zh.md

@@ -0,0 +1,27 @@
+---
+title: 转化标签 - ConversionTag
+order: 8
+---
+
+适用于基础柱形图和基础条形图，转化率组件可以让用户关注到数据的变化比例。
+
+#### 配置项
+
+`markdown:docs/common/conversion-tag.zh.md`
+
+#### 事件交互
+
+转化标签的图形组成包含 `conversion-tag-arrow` 和 `conversion-tag-text`。同一个图表的转化标签组件都放置于一个 group 下，也就是 `conversion-tag-group`，我们可以通过监听 `conversion-tag-group` 事件来进行一些定制交互。
+
+转化标签携带的原始数据信息包含：上一个图形元素（element）和下一个图形元素（nextElement），可通过下列方式获取：
+
+```ts
+plot.on('conversion-tag-group:mouseenter', (evt) => {
+  const { element, nextElement } = evt.target?.get('origin');
+  // 自定义业务逻辑，element 的详细 API，见：https://g2.antv.vision/zh/docs/api/general/element
+});
+```
+
+示例：
+
+<playground path='general/events/demo/conversion-tag-with-link.ts' rid='conversion-tag-events'></playground>

docs/api/components/label.en.md

@@ -1,6 +1,6 @@
 ---
 title: Label
-order: 1
+order: 4
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/label.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 数据标签
-order: 1
+title: 数据标签 - Label
+order: 4
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/legend.en.md

@@ -1,6 +1,6 @@
 ---
 title: Legend
-order: 2
+order: 0
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/legend.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 图例
-order: 2
+title: 图例 - Legend
+order: 0
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/scrollbar.en.md

@@ -1,6 +1,6 @@
 ---
 title: Scrollbar
-order: 7
+order: 3
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/scrollbar.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 滚动条
-order: 7
+title: 滚动条 - Scrollbar
+order: 3
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/slider.en.md

@@ -1,6 +1,6 @@
 ---
 title: Slider
-order: 6
+order: 2
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/slider.zh.md

@@ -1,6 +1,6 @@
 ---
-title: 缩略轴
-order: 6
+title: 缩略轴 - Slider
+order: 2
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/tooltip.en.md

@@ -1,6 +1,6 @@
 ---
 title: Tooltip
-order: 3
+order: 5
 ---
 
 `markdown:docs/styles/component.md`

docs/api/components/tooltip.zh.md

@@ -1,6 +1,6 @@
 ---
-title: Tooltip
-order: 3
+title: 悬浮提示 - Tooltip
+order: 5
 ---
 
 `markdown:docs/styles/component.md`

docs/api/plots/bar.en.md

@@ -87,6 +87,8 @@ The ratio of spacing between columns in groups( Range:[0-1] ), only for Grouped
 
 #### Conversion Tag
 
+Applicable to base bar charts and base bar charts, the Conversion Rate component allows the user to focus on the rate of change in the data.
+
 `markdown:docs/common/conversion-tag.en.md`
 
 #### Connected Area

docs/api/plots/bar.zh.md

@@ -89,7 +89,9 @@ order: 3
 
 `markdown:docs/common/slider.zh.md`
 
-#### 转化率
+#### 转化标签
+
+适用于基础柱形图和基础条形图，转化率组件可以让用户关注到数据的变化比例。
 
 `markdown:docs/common/conversion-tag.zh.md`
 

docs/api/plots/column.en.md

@@ -91,6 +91,8 @@ The spacing between columns in a grouping [0-1] applies only to grouping columns
 
 #### Conversion Tag
 
+Applicable to base bar charts and base bar charts, the Conversion Rate component allows the user to focus on the rate of change in the data.
+
 `markdown:docs/common/conversion-tag.en.md`
 
 #### Connected Area

docs/api/plots/column.zh.md

@@ -91,7 +91,9 @@ order: 2
 
 `markdown:docs/common/slider.zh.md`
 
-#### 转化率
+#### 转化标签
+
+适用于基础柱形图和基础条形图，转化率组件可以让用户关注到数据的变化比例。
 
 `markdown:docs/common/conversion-tag.zh.md`