feat(word-cloud): add customPlacement opiton

Author: zhangzhonghe

src/plots/word-cloud/types.ts

@@ -42,23 +42,23 @@ export type Tag = Word & {
 /** 词云字体样式 */
 interface WordStyle {
   /** 词云的字体, 当为函数时，其参数是一个经过处理之后的数据元素的值 */
-  readonly fontFamily?: string | ((word: Word) => string);
+  readonly fontFamily?: string | ((word: Word, index?: number, words?: Word[]) => string);
   /** 设置字体的粗细, 当为函数时，其参数是一个经过处理之后的数据元素的值 */
-  readonly fontWeight?: FontWeight | ((word: Word) => FontWeight);
+  readonly fontWeight?: FontWeight | ((word: Word, index?: number, words?: Word[]) => FontWeight);
   /**
    * 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。
    * 当为函数时，其参数是一个经过处理之后的数据元素的值
    */
-  readonly padding?: number | ((word: Word) => number);
+  readonly padding?: number | ((word: Word, index?: number, words?: Word[]) => number);
   /** 字体的大小范围,当为函数时，其参数是一个经过处理之后的数据元素的值 */
-  readonly fontSize?: [number, number] | ((word: Word) => number);
+  readonly fontSize?: [number, number] | ((word: Word, index?: number, words?: Word[]) => number);
   /**
    * 旋转的最小角度和最大角度 默认 [0, 90]。
    *
    * 注意：如果值是 number 或者 function ，则
    * `rotationSteps` 选项将失效。
    */
-  readonly rotation?: [number, number] | number | ((word: Word) => number);
+  readonly rotation?: [number, number] | number | ((word: Word, index?: number, words?: Word[]) => number);
   /**
    * 旋转实际的步数,越大可能旋转角度越小, 默认是 2。
    *
@@ -93,6 +93,10 @@ export interface WordCloudOptions extends Options {
    * 默认是 `archimedean`。
    */
   readonly spiral?: 'archimedean' | 'rectangular';
-  /** 文字样式配置 */
+  /**
+   * 自定义每个词语的坐标。
+   * 注意：使用该选项时，应配合 `wordStyle` 中的其它选项同时使用。
+   */
+  readonly customPlacement?: (word: Word, index?: number, words?: Word[]) => { x: number; y: number };
   readonly wordStyle?: WordStyle;
 }

src/plots/word-cloud/utils.ts

@@ -3,16 +3,27 @@ import { isArray, isFunction, isNumber, isString } from '@antv/util';
 import { Params } from '../../core/adaptor';
 import { Datum } from '../../types';
 import { log, LEVEL, getContainerSize } from '../../utils';
-import { wordCloud } from '../../utils/transform/word-cloud';
+import { functor, wordCloud } from '../../utils/transform/word-cloud';
 import { Tag, Word, WordCloudOptions } from './types';
 
 /**
  * 用 DataSet 转换词云图数据
  * @param params
  */
 export function transform(params: Params<WordCloudOptions>): Tag[] {
-  const { options } = params;
-  const { data, imageMask, wordField, weightField, colorField, wordStyle, timeInterval, random, spiral } = options;
+  const { options: rawOptions } = params;
+  const {
+    data,
+    imageMask,
+    wordField,
+    weightField,
+    colorField,
+    wordStyle,
+    timeInterval,
+    random,
+    spiral,
+    customPlacement,
+  } = rawOptions;
   if (!data || !data.length) {
     return [];
   }
@@ -30,20 +41,36 @@ export function transform(params: Params<WordCloudOptions>): Tag[] {
     })
   );
 
-  // 数据准备在外部做，wordCloud 单纯就是做布局
-  return wordCloud(words, {
+  const options = {
     imageMask: imageMask as HTMLImageElement,
     font: fontFamily,
-    fontSize: getFontSize(options, range),
+    fontSize: getFontSize(rawOptions, range),
     fontWeight: fontWeight,
     // 图表宽高减去 padding 之后的宽高
     size: getSize(params as any),
     padding: padding,
     timeInterval,
     random,
     spiral,
-    rotate: getRotate(options),
-  });
+    rotate: getRotate(rawOptions),
+  };
+
+  // 自定义布局函数
+  if (isFunction(customPlacement)) {
+    return words.map((word: Word, index: number, words: Word[]) => ({
+      hasText: !!word.text,
+      font: functor(options.font)(word, index, words),
+      weight: functor(options.fontWeight)(word, index, words),
+      rotate: functor(options.rotate)(word, index, words),
+      size: functor(options.fontSize)(word, index, words),
+      style: 'normal',
+      ...word,
+      ...customPlacement(word, index, words),
+    }));
+  }
+
+  // 数据准备在外部做，wordCloud 单纯就是做布局
+  return wordCloud(words, options);
 }
 
 /**

src/utils/transform/word-cloud.ts

@@ -1,15 +1,15 @@
-import { isNil, assign } from '@antv/util';
+import { isNil, isFunction, assign } from '@antv/util';
 import { Tag, Word } from '../../plots/word-cloud/types';
 
 type FontWeight = number | 'normal' | 'bold' | 'bolder' | 'lighter';
 
 export interface Options {
   size: [number, number];
-  font?: string | ((row: Word) => string);
-  fontSize?: number | ((row: Word) => number);
-  fontWeight?: FontWeight | ((row: Word) => FontWeight);
-  rotate?: number | ((row: Word) => number);
-  padding?: number | ((row: Word) => number);
+  font?: string | ((row: Word, index?: number, words?: Word[]) => string);
+  fontSize?: number | ((row: Word, index?: number, words?: Word[]) => number);
+  fontWeight?: FontWeight | ((row: Word, index?: number, words?: Word[]) => FontWeight);
+  rotate?: number | ((row: Word, index?: number, words?: Word[]) => number);
+  padding?: number | ((row: Word, index?: number, words?: Word[]) => number);
   spiral?: 'archimedean' | 'rectangular' | ((size: [number, number]) => (t: number) => number[]);
   random?: number | (() => number);
   timeInterval?: number;
@@ -305,8 +305,8 @@ function cloudCanvas() {
   return document.createElement('canvas');
 }
 
-function functor(d) {
-  return typeof d === 'function'
+export function functor(d) {
+  return isFunction(d)
     ? d
     : function () {
         return d;
@@ -327,7 +327,7 @@ function tagCloud() {
     padding = cloudPadding,
     spiral = archimedeanSpiral,
     random = Math.random,
-    words: any = [],
+    words = [],
     timeInterval = Infinity;
 
   const text = cloudText;
@@ -342,14 +342,14 @@ function tagCloud() {
       n = words.length,
       tags = [],
       data = words
-        .map(function (d, i) {
-          d.text = text.call(this, d, i);
-          d.font = font.call(this, d, i);
-          d.style = fontStyle.call(this, d, i);
-          d.weight = fontWeight.call(this, d, i);
-          d.rotate = rotate.call(this, d, i);
-          d.size = ~~fontSize.call(this, d, i);
-          d.padding = padding.call(this, d, i);
+        .map(function (d, i, data) {
+          d.text = text.call(this, d, i, data);
+          d.font = font.call(this, d, i, data);
+          d.style = fontStyle.call(this, d, i, data);
+          d.weight = fontWeight.call(this, d, i, data);
+          d.rotate = rotate.call(this, d, i, data);
+          d.size = ~~fontSize.call(this, d, i, data);
+          d.padding = padding.call(this, d, i, data);
           return d;
         })
         .sort(function (a, b) {