docs(gauge): 仪表盘文档 (#2261)

docs/api/plots/gauge.zh.md

@@ -52,24 +52,28 @@ order: 22
 | ticks  | _number[]_ | 辅助圆弧显示数字数组                 |
 | color  | _string \|string[]_ | 辅助圆弧的颜色色板，按照色板顺序取值; 当设置 ticks 时，color 无法使用回调的方式 |
 
-<playground rid="gauge" path="progress-plots/gauge/demo/basic.ts"></playground>
+<playground rid="gauge" path="progress-plots/gauge/demo/custom-color.ts"></playground>
+
+### 图表组件
 
 #### axis
 
 <description>**optional** _object_</description>
 
 指标辅助轴样式。
+- 💡 在仪表盘中，axis 组件可以使用的配置有：`label`, `tickLine`, `subTickLine`, 其他配置项不建议在仪表盘中使用。
+- 💡 关于 `tick` 的设置, 可以直接在 `range.ticks` 中进行配置。
 
 `markdown:docs/common/axis.zh.md`
 
 #### indicator
 
 <description>**optional** _object_</description>
 
-仪表盘指示器样式配置。按照组件分成为：
+仪表盘**指示器**样式配置。按照组件分成为：
 
-- `pointer`：指示器中的指针样式配置
-- `pin`：指示器中的圆盘样式配置
+- `pointer`：指示器中的**指针**样式配置
+- `pin`：指示器中的**圆盘**样式配置
 
 他们都有以下配置项：
 

docs/common/axis.zh.md

@@ -4,7 +4,7 @@
 
 适用于直角坐标系，设置坐标轴的位置。
 
-#### label
+##### label
 
 <description> _AxisLabelCfg | null_ **optional** </description>
 

docs/common/shape-style.en.md

@@ -3,6 +3,7 @@
 | Properties    | Type            | Description                                                                                                                                                                              |
 | ------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | fill          | _string_        | Fill color of the shape                                                                                                                                                                  |
+| r          | _number_         | used in `point`, means the radius of geometry |
 | fillOpacity   | _number_        | Fill opacity of the shape                                                                                                                                                                |
 | stroke        | _string_        | Stroke color of the shape                                                                                                                                                                |
 | lineWidth     | _number_        | The width of the stroke of the shape                                                                                                                                                     |

docs/common/shape-style.zh.md

@@ -3,6 +3,7 @@
 | 属性名        | 类型            | 介绍                                                                                                         |
 | ------------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
 | fill          | _string_         | 图形的填充色                                                                                                 |
+| r          | _number_         | 用于 `point`, 代表图形的半径大小 |
 | fillOpacity   | _number_         | 图形的填充透明度                                                                                             |
 | stroke        | _string_         | 图形的描边                                                                                                   |
 | lineWidth     | _number_         | 图形描边的宽度                                                                                               |

docs/manual/plots/gauge.en.md

@@ -0,0 +1,97 @@
+---
+title: Gauge
+order: 6
+---
+
+<div class="manual-docs">
+
+ <div data-card-type="block" data-lake-card="table" id="pLwYV" class="">
+    <table class="lake-table" style="width: 100%; outline: none; border-collapse: collapse;">
+      <colgroup>
+        <col width="425" span="1">
+        <col width="340" span="1">
+      </colgroup>
+      <tbody>
+        <tr style="height: 33px;">
+          <td colspan="1" rowspan="4" style="background:#fff">
+            <playground path='progress-plots/gauge/demo/basic.ts'></playground>
+          </td>
+          <td class="style1">
+          <p><strong>定义</strong></p>
+            <p><span class="lake-fontsize-12">仪表盘(Gauge)是一种拟物化的图表，刻度表示度量，指针表示维度，指针角度表示数值。仪表盘图表就像汽车的速度表一样，有一个圆形的表盘及相应的刻度，有一个指针指向当前数值。目前很多的管理报表或报告上都是用这种图表，以直观的表现出某个指标的进度或实际情况。</span></p>
+            <p><span class="lake-fontsize-12">仪表盘的好处在于它能跟人们的常识结合，使大家马上能理解看什么、怎么看。拟物化的方式使图标变得更友好更人性化，正确使用可以提升用户体验。</span></p>
+          </td>
+        </tr>
+        <tr style="height: 33px;">
+          <td colspan="1">
+            <p><strong>数据准备</strong></p>
+            <p><span class="lake-fontsize-12">1 个百分比数值</span></p>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+
+## Design Guide
+
+### 用法建议
+
+为了视觉上的不拥挤且符合常识，我们建议指针的数量不超过 3 根。
+
+## 快速上手
+
+<div class='sign'>
+
+```ts
+import { Gauge } from '@antv/g2plot';
+
+const gauge = new Gauge('container', {
+  percent: 0.75,
+  range: {
+    color: '#5B8FF9',
+  },
+  statistic: {
+    content: {
+      formatter: ({ percent }) => `Rate: ${(percent * 100).toFixed(0)}%`,
+    },
+  },
+});
+
+gauge.render();
+```
+
+</div>
+
+📊 查看更多<a href="/zh/examples/progress-plots/gauge" target='blank'>示例</a>.
+
+🎨 仪表盘详细的配置参考 [API 文档](/zh/docs/api/plots/gauge).
+
+</div>
+
+## 图表特性
+
+### 自定义指示器的样式
+
+通过设置 `indicator` 来自定义指示器的样式，指示器包含指针 `pointer` 和 指针针头样式。
+
+> 目前暂不支持指示器的形状自定义。
+
+<playground path="progress-plots/gauge/demo/basic.ts" rid="rect1"></playground>
+
+### 自定义辅助圆弧的样式
+
+通过设置 `range` 的 `'ticks''` 和 `'color'` 来自定义辅助圆弧的样式
+
+Example:
+
+```ts
+// 代表着，0 - 1/3: #F4664A, 1/3 - 2/3: #FAAD14, 2/3 - 1: #30BF78
+{
+  range: {
+    ticks: [0, 1 / 3, 2 / 3, 1],
+    color: ['#F4664A', '#FAAD14', '#30BF78'],
+  },
+}
+```
+
+<playground path="progress-plots/gauge/demo/custom-color.ts" rid="rect2"></playground>

docs/manual/plots/gauge.zh.md

@@ -0,0 +1,97 @@
+---
+title: 仪表盘
+order: 6
+---
+
+<div class="manual-docs">
+
+ <div data-card-type="block" data-lake-card="table" id="pLwYV" class="">
+    <table class="lake-table" style="width: 100%; outline: none; border-collapse: collapse;">
+      <colgroup>
+        <col width="425" span="1">
+        <col width="340" span="1">
+      </colgroup>
+      <tbody>
+        <tr style="height: 33px;">
+          <td colspan="1" rowspan="4" style="background:#fff">
+            <playground path="progress-plots/gauge/demo/complex.ts" rid="rect0"></playground>
+          </td>
+          <td class="style1">
+          <p><strong>定义</strong></p>
+            <p><span class="lake-fontsize-12">仪表盘(Gauge)是一种拟物化的图表，刻度表示度量，指针表示维度，指针角度表示数值。仪表盘图表就像汽车的速度表一样，有一个圆形的表盘及相应的刻度，有一个指针指向当前数值。目前很多的管理报表或报告上都是用这种图表，以直观的表现出某个指标的进度或实际情况。</span></p>
+            <p><span class="lake-fontsize-12">仪表盘的好处在于它能跟人们的常识结合，使大家马上能理解看什么、怎么看。拟物化的方式使图标变得更友好更人性化，正确使用可以提升用户体验。</span></p>
+          </td>
+        </tr>
+        <tr style="height: 33px;">
+          <td colspan="1">
+            <p><strong>数据准备</strong></p>
+            <p><span class="lake-fontsize-12">1 个百分比数值</span></p>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+
+## 设计指引
+
+### 用法建议
+
+为了视觉上的不拥挤且符合常识，我们建议指针的数量不超过 3 根。
+
+## 快速上手
+
+<div class='sign'>
+
+```ts
+import { Gauge } from '@antv/g2plot';
+
+const gauge = new Gauge('container', {
+  percent: 0.75,
+  range: {
+    color: '#5B8FF9',
+  },
+  statistic: {
+    content: {
+      formatter: ({ percent }) => `Rate: ${(percent * 100).toFixed(0)}%`,
+    },
+  },
+});
+
+gauge.render();
+```
+
+</div>
+
+📊 查看更多<a href="/zh/examples/progress-plots/gauge" target='blank'>示例</a>.
+
+🎨 仪表盘详细的配置参考 [API 文档](/zh/docs/api/plots/gauge).
+
+</div>
+
+## 图表特性
+
+### 自定义指示器的样式
+
+通过设置 `indicator` 来自定义指示器的样式，指示器包含指针 `pointer` 和 指针针头样式。
+
+> 目前暂不支持指示器的形状自定义。
+
+<playground path="progress-plots/gauge/demo/basic.ts" rid="rect1"></playground>
+
+### 自定义辅助圆弧的样式
+
+通过设置 `range` 的 `'ticks''` 和 `'color'` 来自定义辅助圆弧的样式
+
+Example:
+
+```ts
+// 代表着，0 - 1/3: #F4664A, 1/3 - 2/3: #FAAD14, 2/3 - 1: #30BF78
+{
+  range: {
+    ticks: [0, 1 / 3, 2 / 3, 1],
+    color: ['#F4664A', '#FAAD14', '#30BF78'],
+  },
+}
+```
+
+<playground path="progress-plots/gauge/demo/custom-color.ts" rid="rect2"></playground>

examples/dynamic-plots/basic/demo/dynamic-gauge.ts

@@ -0,0 +1,56 @@
+import { Gauge } from '@antv/g2plot';
+
+const color = ['#F4664A', '#FAAD14', '#30BF78'];
+const getColor = (percent) => {
+  return percent < 0.4 ? color[0] : percent < 0.6 ? color[1] : color[2];
+};
+const gauge = new Gauge('container', {
+  percent: 0.2,
+  range: {
+    color: getColor(0.2),
+  },
+  indicator: {
+    pointer: {
+      style: {
+        stroke: '#D0D0D0',
+      },
+    },
+    pin: {
+      style: {
+        stroke: '#D0D0D0',
+      },
+    },
+  },
+  axis: {
+    label: {
+      formatter(v) {
+        return Number(v) * 100;
+      },
+    },
+    subTickLine: {
+      count: 3,
+    },
+  },
+  statistic: {
+    content: {
+      formatter: ({ percent }) => `Rate: ${(percent * 100).toFixed(0)}%`,
+    },
+    style: {
+      fontSize: 60,
+    },
+  },
+  animation: false,
+});
+
+gauge.render();
+
+let data = 0.2;
+const interval = setInterval(() => {
+  if (data >= 0.85) {
+    clearInterval(interval);
+  } else {
+    data += 0.001;
+    gauge.changeData(data);
+    gauge.update({ range: { color: getColor(data) } });
+  }
+}, 100);

examples/dynamic-plots/basic/demo/meta.json

@@ -27,6 +27,14 @@
         "en": "Area updating with dynamic"
       },
       "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/ld0NQtdLO0/mianjitugengxinshuju-after.gif"
+    },
+    {
+      "filename": "dynamic-gauge.ts",
+      "title": {
+        "zh": "动态更新的仪表盘",
+        "en": "Gauge updating with dynamic"
+      },
+      "screenshot": "https://gw.alipayobjects.com/mdn/rms_d314dd/afts/img/A*O2aDSImbWDgAAAAAAAAAAAAAARQnAQ"
     }
   ]
 }

examples/progress-plots/gauge/demo/basic.ts

@@ -1,13 +1,9 @@
 import { Gauge } from '@antv/g2plot';
 
-const color = ['#F4664A', '#FAAD14', '#30BF78'];
-const getColor = (percent) => {
-  return percent < 0.4 ? color[0] : percent < 0.6 ? color[1] : color[2];
-};
 const gauge = new Gauge('container', {
-  percent: 0.2,
+  percent: 0.75,
   range: {
-    color: getColor(0.2),
+    color: '#30BF78',
   },
   indicator: {
     pointer: {
@@ -39,18 +35,6 @@ const gauge = new Gauge('container', {
       fontSize: 60,
     },
   },
-  animation: false,
 });
 
 gauge.render();
-
-let data = 0.2;
-const interval = setInterval(() => {
-  if (data >= 0.85) {
-    clearInterval(interval);
-  } else {
-    data += 0.001;
-    gauge.changeData(data);
-    gauge.update({ range: { color: getColor(data) } });
-  }
-}, 100);

examples/progress-plots/gauge/demo/complex.ts

@@ -51,11 +51,11 @@ const gauge = new Gauge('container', {
 });
 
 gauge.render();
-let data = 0;
+let data = 0.7;
 const interval = setInterval(() => {
-  if (data >= 1) {
+  if (data >= 1.5) {
     clearInterval(interval);
   }
-  data += 0.01;
-  gauge.changeData(data);
-}, 400);
+  data += 0.005;
+  gauge.changeData(data > 1 ? data - 1 : data);
+}, 100);