feat(gauge): add statistic, demo, docs (#1653)

Author: hustcc

__tests__/unit/plots/gauge/index-spec.ts

@@ -34,6 +34,11 @@ describe('gauge', () => {
           count: 3,
         },
       },
+      statistic: {
+        content: {
+          formatter: ({ percent }) => `分数：${percent * 100}`,
+        },
+      },
     });
 
     gauge.render();
@@ -79,6 +84,12 @@ describe('gauge', () => {
     expect(v2.getCoordinate().radius).toEqual(gauge.options.radius);
     expect(v2.getCoordinate().innerRadius).toEqual(gauge.options.innerRadius);
 
+    // statistic
+    const annotations = gauge.chart.getComponents();
+    expect(annotations.length).toBe(1);
+    expect(annotations[0].extra.position).toEqual(['50%', '100%']);
+    expect(annotations[0].extra.content).toBe('分数：75');
+
     // @ts-ignore
     expect(v2.options.axes).toEqual(undefined);
 

examples/gauge/basic/API.en.md

@@ -0,0 +1 @@
+## 配置属性

examples/gauge/basic/API.zh.md

@@ -0,0 +1,94 @@
+## 配置属性
+
+### 图表容器
+
+`markdown:docs/common/chart-options.zh.md`
+
+### 数据映射
+
+#### percent 📌
+
+**必选**, _number_
+
+功能描述： 指标比例
+
+默认配置： 无
+
+#### radius
+
+**可选**, _number_
+
+功能描述： 圆盘的外半径， 0 ~ 1 。
+
+默认配置： `0.95`
+
+#### innerRadius
+
+**可选**, _number_
+
+功能描述： 圆盘的内半径， 0 ~ 1 。
+
+默认配置： `0.9`
+
+#### startAngle
+
+**可选**, _number_
+
+功能描述： 圆盘的起始角度。
+
+默认配置： `(-7 / 6) * Math.PI`
+
+#### endAngle
+
+**可选**, _number_
+
+功能描述： 圆盘的终止角度。
+
+默认配置： `(1 / 6) * Math.PI`
+
+### 图形样式
+
+#### range
+
+**可选**, _object_
+
+功能描述： 仪表盘辅助圆弧的样式。
+
+| 配置项  | 类型                   | 描述     |
+| ------- | ---------------------- | -------- |
+| ticks  | number[] | 辅助圆弧显示数字数组     |
+| color | string[] | 辅助圆弧的颜色色板，按照色板顺序取值 |
+
+#### indicator
+
+**可选**, _object_
+
+功能描述： 仪表盘指示器样式配置。按照组件分成为：
+
+ - `pointer`：指示器中的指针样式配置
+ - `pin`：指示器中的圆盘样式配置
+
+| 配置项    | 类型     | 描述                 |
+| --------- | -------- | -------------------- |
+| style     | object   | 组件样式配置       |
+
+#### statistic
+
+**可选**, _object_
+
+功能描述： 指标文本组件 。
+
+默认配置： 无
+
+`markdown:docs/common/statistic.zh.md`
+
+#### axis
+
+**可选**, _object_
+
+功能描述： 指标辅助轴样式 。
+
+默认配置： 无
+
+`markdown:docs/common/axis.zh.md`
+

examples/gauge/basic/demo/basic.ts

@@ -0,0 +1,10 @@
+import { Gauge } from '@antv/g2plot';
+
+const gauge = new Gauge('container', {
+  percent: 0.65,
+  range: {
+    color: ['l(0) 0:#5d7cef 1:#e35767'],
+  },
+});
+
+gauge.render();

examples/gauge/basic/demo/complex.ts

@@ -0,0 +1,38 @@
+import { Gauge } from '@antv/g2plot';
+
+const gauge = new Gauge('container', {
+  percent: 0.75,
+  range: {
+    ticks: [0, 0.2, 0.4, 0.75, 1],
+    color: ['red', 'yellow', 'green'],
+  },
+  indicator: {
+    pointer: {
+      style: {
+        stroke: 'pink',
+      },
+    },
+    pin: {
+      style: {
+        stroke: 'blue',
+      },
+    },
+  },
+  axis: {
+    label: {
+      formatter(v: string) {
+        return Number(v) * 100;
+      },
+    },
+    subTickLine: {
+      count: 3,
+    },
+  },
+  statistic: {
+    content: {
+      formatter: ({ percent }) => `分数：${percent * 100}`,
+    },
+  },
+});
+
+gauge.render();

examples/gauge/basic/demo/meta.json

@@ -0,0 +1,24 @@
+{
+  "title": {
+    "zh": "中文分类",
+    "en": "Category"
+  },
+  "demos": [
+    {
+      "filename": "basic.ts",
+      "title": {
+        "zh": "仪表盘",
+        "en": "Gauge chart"
+      },
+      "screenshot": "https://gw.alicdn.com/tfs/TB1peOutYr1gK0jSZFDXXb9yVXa-484-468.png"
+    },
+    {
+      "filename": "complex.ts",
+      "title": {
+        "zh": "自定义配置的仪表盘",
+        "en": "Gauge chart - custom style"
+      },
+      "screenshot": "https://gw.alicdn.com/tfs/TB1IICyt4D1gK0jSZFyXXciOVXa-517-474.png"
+    }
+  ]
+}

examples/gauge/basic/design.en.md

@@ -0,0 +1,5 @@
+---
+title: 设计规范
+---
+
+设计规范

examples/gauge/basic/design.zh.md

@@ -0,0 +1,5 @@
+---
+title: 设计规范
+---
+
+设计规范

examples/gauge/basic/index.en.md

@@ -0,0 +1,4 @@
+---
+title: 仪表盘
+order: 1
+---

examples/gauge/basic/index.zh.md

@@ -0,0 +1,4 @@
+---
+title: 仪表盘
+order: 1
+---

gatsby-config.js

@@ -112,6 +112,14 @@ module.exports = {
           en: 'Scatter Charts',
         },
       },
+      {
+        slug: 'gauge',
+        icon: 'gauge',
+        title: {
+          zh: '仪表盘',
+          en: 'Gauge Charts',
+        },
+      },
       {
         slug: 'histogram',
         icon: 'histogram',

src/plots/gauge/adaptor.ts

@@ -1,4 +1,4 @@
-import { isString, isArray } from '@antv/util';
+import { isString, isArray, isFunction } from '@antv/util';
 import { interaction, animation, theme, scale } from '../../adaptor/common';
 import { Params } from '../../core/adaptor';
 import { Data } from '../../types';
@@ -74,6 +74,35 @@ function meta(params: Params<GaugeOptions>): Params<GaugeOptions> {
   )(params);
 }
 
+/**
+ * 统计指标文档
+ * @param params
+ */
+function statistic(params: Params<GaugeOptions>): Params<GaugeOptions> {
+  const { chart, options } = params;
+  const { statistic, percent } = options;
+
+  const { title, content } = statistic;
+
+  // annotation title 和 content 分别使用一个 text
+  [title, content].forEach((annotation) => {
+    if (annotation) {
+      const { formatter, style, offsetX, offsetY, rotate } = annotation;
+      chart.annotation().text({
+        top: true,
+        position: ['50%', '100%'],
+        content: isFunction(formatter) ? formatter({ percent }) : `${percent}`,
+        style: isFunction(style) ? style({ percent }) : style,
+        offsetX,
+        offsetY,
+        rotate,
+      });
+    }
+  });
+
+  return params;
+}
+
 /**
  * other 配置
  * @param params
@@ -97,6 +126,7 @@ export function adaptor(params: Params<GaugeOptions>) {
   return flow(
     geometry,
     meta,
+    statistic,
     interaction,
     animation,
     theme,

src/plots/gauge/index.ts

@@ -61,6 +61,19 @@ export class Gauge extends Plot<GaugeOptions> {
           },
         },
       },
+      statistic: {
+        title: false,
+        content: {
+          formatter: ({ percent }) => `${(percent * 100).toFixed(2)}%`,
+          style: {
+            opacity: 0.75,
+            fontSize: 30,
+            textAlign: 'center',
+            textBaseline: 'bottom',
+          },
+          offsetY: -16,
+        },
+      },
       meta: {
         // 两个 view 的 scale 同步到 v 上
         [RANGE_VALUE]: {