refactor(facet): 添加了spacing属性，支持配置分面图之间的间距 (#3614)

* docs(column): 修正了字体颜色 strooke -> fill

* refactor(facet): 添加了spacing参数，支持配置分面图之间的间距

* refactor(facet): 完善了方法注释，规范了方法命名和文档描述;

* docs(facet): 更新了facet文档描述

* refactor(facet): 补充了单测

* refactor(facet): 完善了注释

Co-authored-by: yangtao.yangtao <[email protected]>

Author: Aarebecca

docs/common/facet-cfg.md

@@ -1,3 +1,12 @@
+#### FacetCfg.spacing
+
+<description> _[number | string, number | string]_ **optional**</description>
+
+分面子图之间的横向、纵向间隔大小，百分比形式表示占 view 宽高比例，数值形式表示像素值大小。支持百分比形式和数值形式混合表示，如：
+
+- [像素值, 像素值]: `[10, 20]`
+- [像素值, 百分比]: `[20, '50%']`
+
 #### FacetCfg.padding
 
 <description> _number | number[] | 'auto'_ **optional**</description>

examples/case/column/demo/column11.ts

@@ -58,7 +58,7 @@ chart
         return originData.value + '%';
       },
       style: {
-        stroke: '#fff'
+        fill: '#fff'
       }
     };
   });

src/facet/facet.ts

@@ -1,4 +1,4 @@
-import { deepMix, each, every, get, isNil } from '@antv/util';
+import { deepMix, each, every, get, isNil, isNumber } from '@antv/util';
 import { LAYER } from '../constant';
 import { IGroup } from '../dependents';
 import { AxisCfg, Condition, Datum, FacetCfg, FacetData, FacetDataFilter, Region } from '../interface';
@@ -153,11 +153,9 @@ export abstract class Facet<C extends FacetCfg<FacetData> = FacetCfg<FacetData>,
    */
   private createFacetViews(): View[] {
     // 使用分面数据 创建分面 view
-    return this.facets.map(
-      (facet): View => {
-        return this.facetToView(facet);
-      }
-    );
+    return this.facets.map((facet): View => {
+      return this.facetToView(facet);
+    });
   }
 
   /**
@@ -173,6 +171,31 @@ export abstract class Facet<C extends FacetCfg<FacetData> = FacetCfg<FacetData>,
     });
   }
 
+  /**
+   * 解析 spacing
+   */
+  private parseSpacing() {
+    /**
+     * @example
+     *
+     * // 仅使用百分比或像素值
+     * // 横向间隔为 10%，纵向间隔为 10%
+     * ['10%', '10%']
+     * // 横向间隔为 10px，纵向间隔为 10px
+     * [10, 10]
+     *
+     * // 同时使用百分比和像素值
+     * ['10%', 10]
+     * // 横向间隔为 10%，纵向间隔为 10px
+     */
+    const { width, height } = this.view.viewBBox;
+    const { spacing } = this.cfg;
+    return spacing.map((s: number, idx: number) => {
+      if (isNumber(s)) return s / (idx === 0 ? width : height);
+      else return parseFloat(s) / 100;
+    });
+  }
+
   // 其他一些提供给子类使用的方法
 
   /**
@@ -206,30 +229,37 @@ export abstract class Facet<C extends FacetCfg<FacetData> = FacetCfg<FacetData>,
    * @param yIndex y 方向 index
    */
   protected getRegion(rows: number, cols: number, xIndex: number, yIndex: number): Region {
-    // x, y 方向均分 100% 宽高
-    const xRatio = 1 / (cols === 0 ? 1 : cols);
-    const yRatio = 1 / (rows === 0 ? 1 : rows);
-
+    const [xSpacing, ySpacing] = this.parseSpacing();
+    // 每两个分面区域横向间隔xSPacing, 纵向间隔ySpacing
+    // 每个分面区域的横纵占比
+    /**
+     * ratio * num + spacing * (num - 1) = 1
+     * => ratio = (1 - (spacing * (num - 1))) / num
+     *          = (1 + spacing) / num - spacing
+     *
+     * num 对应 cols/rows
+     * spacing 对应 xSpacing/ySpacing
+     */
+    const xRatio = (1 + xSpacing) / (cols === 0 ? 1 : cols) - xSpacing;
+    const yRatio = (1 + ySpacing) / (rows === 0 ? 1 : rows) - ySpacing;
+
+    // 得到第 index 个分面区域百分比位置
     const start = {
-      x: xRatio * xIndex,
-      y: yRatio * yIndex,
+      x: (xRatio + xSpacing) * xIndex,
+      y: (yRatio + ySpacing) * yIndex,
     };
-
     const end = {
-      x: xRatio * (xIndex + 1),
-      y: yRatio * (yIndex + 1),
-    };
-
-    return {
-      start,
-      end,
+      x: start.x + xRatio,
+      y: start.y + yRatio,
     };
+    return { start, end };
   }
 
   protected getDefaultCfg() {
     return {
       eachView: undefined,
       showTitle: true,
+      spacing: [0, 0],
       padding: 10,
       fields: [],
     };

src/interface.ts

@@ -1665,6 +1665,8 @@ export interface FacetCfg<D> {
   readonly type?: string;
   /** view 创建回调。 */
   readonly eachView: (innerView: View, facet?: D) => any;
+  /** 分面 view 之间的间隔， 百分比或像素值 */
+  readonly spacing?: [number | string, number | string];
   /** facet view padding。 */
   readonly padding?: ViewPadding;
   /** 是否显示标题。 */

tests/unit/facet/list/index-spec.ts

@@ -46,7 +46,6 @@ describe('facet rect', () => {
       start: { x: 0, y: 1 / 2 },
       end: { x: 1 / 3, y: 1 },
     });
-
     // @ts-ignore
     const facetData0 = chart.facetInstance.facets[0] as ListData;
     expect(facetData0.total).toBe(5);

tests/unit/facet/mirror/index-spec.ts

@@ -169,6 +169,7 @@ describe('facet mirror transpose = true', () => {
     fields: ['gender'],
     transpose: true,
     padding: [0, 48, 0, 0],
+    spacing: ['10%', '10%'],
     eachView(view) {
       view.interval().position('age*total_percentage').color('gender', ['#1890ff', '#f04864']);
     },
@@ -237,6 +238,27 @@ describe('facet mirror transpose = true', () => {
     expect(facetInstance.destroyed).toBe(false);
   });
 
+  it('spacing', () => {
+    const {
+      start: { x: sx0, y: sy0 },
+      end: { x: ex0, y: ey0 },
+      // @ts-ignore
+    } = chart.views[0].region;
+    expect(sx0).toBeCloseTo(0);
+    expect(sy0).toBeCloseTo(0);
+    expect(ex0).toBeCloseTo(0.5 - 0.1 / 2);
+    expect(ey0).toBeCloseTo(1);
+    const {
+      start: { x: sx1, y: sy1 },
+      end: { x: ex1, y: ey1 },
+      // @ts-ignore
+    } = chart.views[1].region;
+    expect(sx1).toBeCloseTo(0.5 + 0.1 / 2);
+    expect(sy1).toBeCloseTo(0);
+    expect(ex1).toBeCloseTo(1);
+    expect(ey1).toBeCloseTo(1);
+  });
+
   it('clear', () => {
     // @ts-ignore
     const facetInstance = chart.facetInstance;