docs(pattern): 添加pattern的文档 (#2798)

__tests__/unit/utils/pattern/util-spec.ts

@@ -52,11 +52,21 @@ describe('utils', () => {
   });
 
   it('transformMatrix', () => {
-    expect(transformMatrix(2, 45).toString()).toEqual(
-      'matrix(0.3535533905932738, 0.35355339059327373, -0.35355339059327373, 0.3535533905932738, 0, 0)'
-    );
-    expect(transformMatrix(1, 45).toString()).toEqual(
-      'matrix(0.7071067811865476, 0.7071067811865475, -0.7071067811865475, 0.7071067811865476, 0, 0)'
-    );
+    expect(transformMatrix(2, 45)).toEqual({
+      a: 0.3535533905932738,
+      b: 0.35355339059327373,
+      c: -0.35355339059327373,
+      d: 0.3535533905932738,
+      e: 0,
+      f: 0,
+    });
+    expect(transformMatrix(1, 45)).toEqual({
+      a: 0.7071067811865476,
+      b: 0.7071067811865475,
+      c: -0.7071067811865475,
+      d: 0.7071067811865476,
+      e: 0,
+      f: 0,
+    });
   });
 });

docs/api/plots/pie.en.md

@@ -91,6 +91,8 @@ Configure the end Angle of the coordinate system.
 
 `markdown:docs/common/color.en.md`
 
+`markdown:docs/common/pattern.en.md`
+
 #### pieStyle
 
 <description>**optional** _object_</description>

docs/api/plots/pie.zh.md

@@ -90,6 +90,8 @@ piePlot.render();
 
 `markdown:docs/common/color.zh.md`
 
+`markdown:docs/common/pattern.zh.md`
+
 #### statistic ✨
 
 <description>**optional** _object_</description>

docs/common/pattern.en.md

@@ -0,0 +1,93 @@
+#### pattern ✨
+
+<description>**optional** _object | Function_</description>
+
+Set the pattern style of the geometries.
+- PatternOption: consists of `type` and `cfg`, `type` includes: `dot`, `line`, `square`, `cfg` is optional.
+- Features: pattern will override the `style` of geometry (such as pieStyle, columnStyle, etc.).
+- Usage: You can set a uniform pattern style for all geometries of the chart by using configuration (`PatternOption`) or `CanvasPattern` object, and a `callback` is provided to set the pattern for each geometry.
+
+The type of pattern is defined as follows:
+```plain
+PatternAttr =
+  | CanvasPattern
+  | PatternOption
+  | ((datum: Datum, color: string /** inherit color */) => PatternOption | CanvasPattern);
+```
+
+Usage:
+```ts
+// set a uniform pattern style for all geometries
+{
+   pattern: {
+    type: 'dot',
+    cfg: {
+      size: 4,
+      padding: 4,
+      rotation: 0,
+      fill: '#FFF',
+      isStagger: true,
+    },
+  },
+}
+// set the pattern for each geometry
+{
+  pattern: ({type}, color) =>{
+    if(type ==='分类一') {
+      return { 
+        type: 'dot',
+        cfg: {
+          backgroundColor: color, // inherit color
+        }
+      }
+    } else if(type ==='分类二') {
+      return {
+         type: 'square',
+         cfg: {
+           backgroundColor: 'pink', // custom color
+         }
+       }
+    } else if(type ==='分类三') {
+      return { 
+        type: 'line' 
+      }
+    }
+  },
+}
+```
+<!--Configuration items for each pattern-->
+
+Common configuration(cfg) for all types of pattern:
+
+| Attribute        | Type            | Description            |
+| ------------- | --------------- | ---------------- |
+| backgroundColor   | _string_         | Background color of the pattern |
+| fill     | _string_         |  Fill color of the symbol in pattern  |
+| fillOpacity   |   _number_ | Transparency of the symbol in pattern  |
+| stroke   | _string_         | Stroke color of the symbol in pattern |
+| strokeOpacity       | _number_         | Stroke opacity of the symbol in pattern  |
+| lineWidth   | _number_         | The thickness of the symbol's stroke       |
+| opacity | _number_         | Overall transparency of the pattern              |
+| rotation    | _number_         | Rotation angle of the pattern   |
+
+Additional configuration for dotPattern
+
+| Attribute        | Type             | Description            |
+| ------------- | --------------- | ---------------- |
+| size          | _number_         | The size of the dot, default: `4`  |
+| padding          | _number_         | The distance between dots, default: `2` |
+| isStagger        | _boolean_         | Staggered dots. default: `true`    |
+
+Additional configuration for linePattern
+
+| Attribute        | Type             | Description           |
+| ------------- | --------------- | ---------------- |
+| spacing          | _number_         | The distance between the two lines, default: `5`  |
+
+Additional configuration for squarePattern
+
+| Attribute        | Type             | Description           |
+| ------------- | --------------- | ---------------- |
+| size          | _number_         | The size of the square, default: `4`  |
+| padding          | _number_         | The distance between squares, default:`0` |
+| isStagger        | _boolean_         | Staggered squares. default:`true`    |

docs/common/pattern.zh.md

@@ -0,0 +1,93 @@
+#### pattern ✨
+
+<description>**optional** _object | Function_</description>
+
+设置图形的贴图样式。
+- 配置项：由`type`和`cfg`组成，`type`目前包括三种类型：`dot`、`line`、`square`，`cfg`为可选项。
+- 特点：`pattern`会覆盖当前图形设置的`style`样式(如 pieStyle、columnStyle 等)。
+- 使用方式：可通过 配置项(PatternOption) 或传入 CanvasPattern 对象 的方式给图表的所有图形设置统一的贴图样式，还提供了 callback 的方式给对应的图形设置样式。
+
+pattern 的类型定义如下：
+```plain
+PatternAttr =
+  | CanvasPattern
+  | PatternOption
+  | ((datum: Datum, color: string /** inherit color */) => PatternOption | CanvasPattern);
+```
+
+具体用法：
+```ts
+// 给图形设置统一贴图
+{
+   pattern: {
+    type: 'dot',
+    cfg: {
+      size: 4,
+      padding: 4,
+      rotation: 0,
+      fill: '#FFF',
+      isStagger: true,
+    },
+  },
+}
+// 给图形分别设置贴图
+{
+  pattern: ({type}, color) =>{
+    if(type ==='分类一') {
+      return { 
+        type: 'dot',
+        cfg: {
+          backgroundColor: color, // 继承主题颜色
+        }
+      }
+    } else if(type ==='分类二') {
+      return {
+         type: 'square',
+         cfg: {
+           backgroundColor: 'pink', // 自定义颜色
+         }
+       }
+    } else if(type ==='分类三') {
+      return { 
+        type: 'line' 
+      }
+    }
+  },
+}
+```
+<!--各个 pattern 的配置项-->
+
+pattern 共有的 cfg 配置项
+
+| 属性名        | 类型            | 介绍                |
+| ------------- | --------------- | ---------------- |
+| backgroundColor   | _string_         | 贴图的背景色            |
+| fill     | _string_         | 贴图元素的填充色      |
+| fillOpacity   |   _number_ | 贴图元素填充的透明度 |
+| stroke   | _string_         | 贴图元素的描边色          |
+| strokeOpacity       | _number_         | 贴图元素的描边透明度色    |
+| lineWidth   | _number_         | 贴图元素的描边粗细        |
+| opacity | _number_         | 贴图整体的透明度              |
+| rotation    | _number_         | 贴图整体的旋转角度             |
+
+dotPattern 额外的 cfg 配置项
+
+| 属性名        | 类型            | 介绍                |
+| ------------- | --------------- | ---------------- |
+| size          | _number_         | 圆点的大小，默认为`4`  |
+| padding          | _number_         | 圆点之间的间隔，默认为`4` |
+| isStagger        | _boolean_         | 圆点之间是否交错，默认为`true`    |
+
+linePattern 额外的 cfg 配置项
+
+| 属性名        | 类型            | 介绍                |
+| ------------- | --------------- | ---------------- |
+| spacing          | _number_         | 两条线之间的距离，默认为`5`  |
+
+squarePattern 额外的 cfg 配置项
+
+| 属性名        | 类型            | 介绍                |
+| ------------- | --------------- | ---------------- |
+| size          | _number_         | 矩形的大小，默认为`4`  |
+| padding          | _number_         | 矩形之间的间隔，默认为`4` |
+| isStagger        | _boolean_         | 矩形之间是否交错，默认为`true`    |

src/types/pattern.ts

@@ -15,16 +15,14 @@ export type PatternCfg = {
   opacity?: number;
   /** 整个pattern 的旋转角度 */
   rotation?: number;
-  /** 贴图模式 */
-  mode?: 'repeat' | 'no-repeat' | 'repeat-x' | 'repeat-y';
 };
 
 /**
  * dot pattern
  */
 export type DotPatternCfg = PatternCfg & {
-  /** 点的半径大小, 默认: 4 */
-  radius?: number;
+  /** 点的大小, 默认: 4 */
+  size?: number;
   /** padding between dots, 默认: 4 */
   padding?: number;
   /** 是否交错，默认: true. 即 staggered dots. */

src/utils/pattern/dot.ts

@@ -6,8 +6,8 @@ import { getUnitPatternSize, initCanvas, drawBackground, getSymbolsPosition, tra
  * dotPattern的默认配置
  */
 export const defaultDotPatternCfg = {
-  radius: 4,
-  padding: 4,
+  size: 4,
+  padding: 2,
   backgroundColor: 'transparent',
   opacity: 1,
   rotation: 0,
@@ -16,7 +16,6 @@ export const defaultDotPatternCfg = {
   stroke: 'transparent',
   lineWidth: 0,
   isStagger: true,
-  mode: 'repeat',
 };
 
 /**
@@ -28,14 +27,14 @@ export const defaultDotPatternCfg = {
  * @param y 圆点中心坐标y
  */
 export function drawDot(context: CanvasRenderingContext2D, cfg: DotPatternCfg, x: number, y: number) {
-  const { radius, fill, lineWidth, stroke, fillOpacity } = cfg;
+  const { size, fill, lineWidth, stroke, fillOpacity } = cfg;
 
   context.beginPath();
   context.globalAlpha = fillOpacity;
   context.fillStyle = fill;
   context.strokeStyle = stroke;
   context.lineWidth = lineWidth;
-  context.arc(x, y, radius, 0, 2 * Math.PI, false);
+  context.arc(x, y, size / 2, 0, 2 * Math.PI, false);
   context.fill();
   if (lineWidth) {
     context.stroke();
@@ -52,10 +51,10 @@ export function drawDot(context: CanvasRenderingContext2D, cfg: DotPatternCfg, x
 export function createDotPattern(cfg?: DotPatternCfg): CanvasPattern {
   const dotCfg = deepAssign({}, defaultDotPatternCfg, cfg);
 
-  const { radius, padding, isStagger, rotation } = dotCfg;
+  const { size, padding, isStagger, rotation } = dotCfg;
 
   // 计算 画布大小，dots的位置
-  const unitSize = getUnitPatternSize(radius * 2, padding, isStagger);
+  const unitSize = getUnitPatternSize(size, padding, isStagger);
   const dots = getSymbolsPosition(unitSize, isStagger);
 
   // 初始化 patternCanvas
@@ -68,7 +67,7 @@ export function createDotPattern(cfg?: DotPatternCfg): CanvasPattern {
     drawDot(ctx, dotCfg, x, y);
   }
 
-  const pattern = ctx.createPattern(canvas, dotCfg.mode);
+  const pattern = ctx.createPattern(canvas, 'repeat');
 
   if (pattern) {
     const dpr = window?.devicePixelRatio || 2;

src/utils/pattern/line.ts

@@ -7,13 +7,12 @@ import { initCanvas, drawBackground, transformMatrix } from './util';
  */
 export const defaultLinePatternCfg = {
   rotation: 45,
-  spacing: 10,
+  spacing: 5,
   opacity: 1,
   backgroundColor: 'transparent',
   strokeOpacity: 1,
   stroke: '#FFF',
   lineWidth: 1,
-  mode: 'repeat',
 };
 
 /**
@@ -58,7 +57,7 @@ export function createLinePattern(cfg?: LinePatternCfg): CanvasPattern {
   drawBackground(ctx, lineCfg, width, height);
   drawLine(ctx, lineCfg, d);
 
-  const pattern = ctx.createPattern(canvas, lineCfg.mode);
+  const pattern = ctx.createPattern(canvas, 'repeat');
 
   if (pattern) {
     const dpr = window?.devicePixelRatio || 2;

src/utils/pattern/square.ts

@@ -7,7 +7,7 @@ import { getUnitPatternSize, initCanvas, drawBackground, getSymbolsPosition, tra
  */
 export const defaultSquarePatternCfg = {
   size: 4,
-  padding: 1,
+  padding: 0,
   isStagger: true,
   backgroundColor: 'transparent',
   opacity: 1,
@@ -16,7 +16,6 @@ export const defaultSquarePatternCfg = {
   fillOpacity: 1,
   stroke: 'transparent',
   lineWidth: 0,
-  mode: 'repeat',
 };
 
 /**
@@ -60,7 +59,7 @@ export function createSquarePattern(cfg?: SquarePatternCfg): CanvasPattern {
     drawSquare(ctx, squareCfg, x, y);
   }
 
-  const pattern = ctx.createPattern(canvas, squareCfg.mode);
+  const pattern = ctx.createPattern(canvas, 'repeat');
 
   if (pattern) {
     const dpr = window?.devicePixelRatio || 2;