docs(word-cloud): update doc

antvis · Oct 27, 2020 · 2548f05 · 2548f05
1 parent f9d1e33
commit 2548f05
Show file tree

Hide file tree

Showing 5 changed files with 197 additions and 65 deletions.
diff --git a/docs/manual/plots/word-cloud.en.md b/docs/manual/plots/word-cloud.en.md
@@ -45,6 +45,30 @@ order: 0
 
 默认配置： 无
 
+#### random
+
+**可选**, _number | function_
+
+功能描述： 自定义所使用的随机函数，其值可以是一个 [0, 1) 区间中的值，也可以是一个返回该值的函数，当该值是一个固定的值时，每次渲染相同数据的词云图时，其对应的每个单词的布局坐标一致
+
+默认配置： 默认使用的是浏览器内置的 `Math.random`，也就是每次渲染，单词的位置都不一样
+
+#### spiral
+
+**可选**, _'archimedean' | 'rectangular'_
+
+功能描述：当设置为 `archimedean` 时，整个词云图接近于`椭圆`的形状，当设置为 `rectangular` 时，整个词云图接近于`矩形`的形状
+
+默认配置： _'archimedean'_
+
+#### customPlacement
+
+**可选**, _function_
+
+功能描述： 自定义每个词语的坐标，使用该选项时，应配合 `wordStyle` 中的其它选项同时使用
+
+默认配置： 无
+
 #### timeInterval
 
 **可选**, _number_
@@ -75,22 +99,31 @@ order: 0
 
 默认配置： 无
 
-| 细分配置      | 类型                           | 默认值    | 功能描述                                                        |
-| ------------- | ------------------------------ | --------- | --------------------------------------------------------------- |
-| fontFamily    | _string \| function_           | 'Verdana' | 词云的字体                                                      |
-| fontWeight    | _string \| number \| function_ | 'normal'  | 设置字体的粗细                                                  |
-| padding       | _number \| function_           | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
-| fontSize      | _number[] \| function_         | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
-| rotation      | _number[]_                     | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
-| rotationSteps | _number_                       | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
-| rotateRatio   | _number_                       | 0.5       | 旋转的比率 [0, 1]，默认是 0.5 也就是 50%可能发生旋转            |
-
-以上，某些属性可以设置为一个函数，其函数的参数是一个`object`，其属性如下
-
-| 细分配置 | 类型     | 功能描述       |
-| -------- | -------- | -------------- |
-| text     | _string_ | 文本内容       |
-| value    | _number_ | 该文本所占权重 |
+| 细分配置      | 类型                             | 默认值    | 功能描述                                                        |
+| ------------- | -------------------------------- | --------- | --------------------------------------------------------------- |
+| fontFamily    | _string \| function_             | 'Verdana' | 词云的字体                                                      |
+| fontWeight    | _string \| number \| function_   | 'normal'  | 设置字体的粗细                                                  |
+| padding       | _number \| function_             | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
+| fontSize      | _number[] \| number \| function_ | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
+| rotation      | _number[] \| number \| function_ | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
+| rotationSteps | _number_                         | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
+
+以上，某些属性可以设置为一个函数，其函数的参数如下：
+
+| 细分配置 | 类型     | 功能描述                       |
+| -------- | -------- | ------------------------------ |
+| word     | _Word_   | 每个文本的数据对象             |
+| index    | _number_ | 当前文本对象在总数据中的索引值 |
+| words    | _Word[]_ | 总的文本数据，是一个数组       |
+
+类型`Word`的配置如下：
+
+| 细分配置 | 类型     | 功能描述               |
+| -------- | -------- | ---------------------- |
+| text     | _string_ | 文本内容               |
+| value    | _number_ | 文本权重               |
+| color    | _any_    | 进行颜色映射的值       |
+| datum    | _object_ | 存储的所对应的原始数据 |
 
 `markdown:docs/common/color.en.md`
 

diff --git a/docs/manual/plots/word-cloud.zh.md b/docs/manual/plots/word-cloud.zh.md
@@ -45,6 +45,30 @@ order: 0
 
 默认配置： 无
 
+#### random
+
+**可选**, _number | function_
+
+功能描述： 自定义所使用的随机函数，其值可以是一个 [0, 1) 区间中的值，也可以是一个返回该值的函数，当该值是一个固定的值时，每次渲染相同数据的词云图时，其对应的每个单词的布局坐标一致
+
+默认配置： 默认使用的是浏览器内置的 `Math.random`，也就是每次渲染，单词的位置都不一样
+
+#### spiral
+
+**可选**, _'archimedean' | 'rectangular'_
+
+功能描述：当设置为 `archimedean` 时，整个词云图接近于`椭圆`的形状，当设置为 `rectangular` 时，整个词云图接近于`矩形`的形状
+
+默认配置： _'archimedean'_
+
+#### customPlacement
+
+**可选**, _function_
+
+功能描述： 自定义每个词语的坐标，使用该选项时，应配合 `wordStyle` 中的其它选项同时使用
+
+默认配置： 无
+
 #### timeInterval
 
 **可选**, _number_
@@ -75,22 +99,31 @@ order: 0
 
 默认配置： 无
 
-| 细分配置      | 类型                           | 默认值    | 功能描述                                                        |
-| ------------- | ------------------------------ | --------- | --------------------------------------------------------------- |
-| fontFamily    | _string \| function_           | 'Verdana' | 词云的字体                                                      |
-| fontWeight    | _string \| number \| function_ | 'normal'  | 设置字体的粗细                                                  |
-| padding       | _number \| function_           | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
-| fontSize      | _number[] \| function_         | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
-| rotation      | _number[]_                     | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
-| rotationSteps | _number_                       | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
-| rotateRatio   | _number_                       | 0.5       | 旋转的比率 [0, 1]，默认是 0.5 也就是 50%可能发生旋转            |
-
-以上，某些属性可以设置为一个函数，其函数的参数是一个`object`，其属性如下
-
-| 细分配置 | 类型                                | 功能描述                                             |
-| -------- | ----------------------------------- | ---------------------------------------------------- |
-| text     | _string_                            | 文本内容                                             |
-| value    | _number_                            | 该文本所占权重                                       |
+| 细分配置      | 类型                             | 默认值    | 功能描述                                                        |
+| ------------- | -------------------------------- | --------- | --------------------------------------------------------------- |
+| fontFamily    | _string \| function_             | 'Verdana' | 词云的字体                                                      |
+| fontWeight    | _string \| number \| function_   | 'normal'  | 设置字体的粗细                                                  |
+| padding       | _number \| function_             | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
+| fontSize      | _number[] \| number \| function_ | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
+| rotation      | _number[] \| number \| function_ | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
+| rotationSteps | _number_                         | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
+
+以上，某些属性可以设置为一个函数，其函数的参数如下：
+
+| 细分配置 | 类型     | 功能描述                       |
+| -------- | -------- | ------------------------------ |
+| word     | _Word_   | 每个文本的数据对象             |
+| index    | _number_ | 当前文本对象在总数据中的索引值 |
+| words    | _Word[]_ | 总的文本数据，是一个数组       |
+
+类型`Word`的配置如下：
+
+| 细分配置 | 类型     | 功能描述               |
+| -------- | -------- | ---------------------- |
+| text     | _string_ | 文本内容               |
+| value    | _number_ | 文本权重               |
+| color    | _any_    | 进行颜色映射的值       |
+| datum    | _object_ | 存储的所对应的原始数据 |
 
 `markdown:docs/common/color.zh.md`
 

diff --git a/examples/word-cloud/basic/API.en.md b/examples/word-cloud/basic/API.en.md
@@ -40,6 +40,30 @@
 
 默认配置： 无
 
+#### random
+
+**可选**, _number | function_
+
+功能描述： 自定义所使用的随机函数，其值可以是一个 [0, 1) 区间中的值，也可以是一个返回该值的函数，当该值是一个固定的值时，每次渲染相同数据的词云图时，其对应的每个单词的布局坐标一致
+
+默认配置： 默认使用的是浏览器内置的 `Math.random`，也就是每次渲染，单词的位置都不一样
+
+#### spiral
+
+**可选**, _'archimedean' | 'rectangular'_
+
+功能描述：当设置为 `archimedean` 时，整个词云图接近于`椭圆`的形状，当设置为 `rectangular` 时，整个词云图接近于`矩形`的形状
+
+默认配置： _'archimedean'_
+
+#### customPlacement
+
+**可选**, _function_
+
+功能描述： 自定义每个词语的坐标，使用该选项时，应配合 `wordStyle` 中的其它选项同时使用
+
+默认配置： 无
+
 #### timeInterval
 
 **可选**, _number_
@@ -70,22 +94,31 @@
 
 默认配置： 无
 
-| 细分配置      | 类型                           | 默认值    | 功能描述                                                        |
-| ------------- | ------------------------------ | --------- | --------------------------------------------------------------- |
-| fontFamily    | _string \| function_           | 'Verdana' | 词云的字体                                                      |
-| fontWeight    | _string \| number \| function_ | 'normal'  | 设置字体的粗细                                                  |
-| padding       | _number \| function_           | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
-| fontSize      | _number[] \| function_         | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
-| rotation      | _number[]_                     | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
-| rotationSteps | _number_                       | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
-| rotateRatio   | _number_                       | 0.5       | 旋转的比率 [0, 1]，默认是 0.5 也就是 50%可能发生旋转            |
-
-以上，某些属性可以设置为一个函数，其函数的参数是一个`object`，其属性如下
-
-| 细分配置 | 类型                                | 功能描述                                             |
-| -------- | ----------------------------------- | ---------------------------------------------------- |
-| text     | _string_                            | 文本内容                                             |
-| value    | _number_                            | 该文本所占权重                                       |
+| 细分配置      | 类型                             | 默认值    | 功能描述                                                        |
+| ------------- | -------------------------------- | --------- | --------------------------------------------------------------- |
+| fontFamily    | _string \| function_             | 'Verdana' | 词云的字体                                                      |
+| fontWeight    | _string \| number \| function_   | 'normal'  | 设置字体的粗细                                                  |
+| padding       | _number \| function_             | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
+| fontSize      | _number[] \| number \| function_ | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
+| rotation      | _number[] \| number \| function_ | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
+| rotationSteps | _number_                         | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
+
+以上，某些属性可以设置为一个函数，其函数的参数如下：
+
+| 细分配置 | 类型     | 功能描述                       |
+| -------- | -------- | ------------------------------ |
+| word     | _Word_   | 每个文本的数据对象             |
+| index    | _number_ | 当前文本对象在总数据中的索引值 |
+| words    | _Word[]_ | 总的文本数据，是一个数组       |
+
+类型`Word`的配置如下：
+
+| 细分配置 | 类型     | 功能描述               |
+| -------- | -------- | ---------------------- |
+| text     | _string_ | 文本内容               |
+| value    | _number_ | 文本权重               |
+| color    | _any_    | 进行颜色映射的值       |
+| datum    | _object_ | 存储的所对应的原始数据 |
 
 `markdown:docs/common/color.en.md`
 

diff --git a/examples/word-cloud/basic/API.zh.md b/examples/word-cloud/basic/API.zh.md
@@ -40,6 +40,30 @@
 
 默认配置： 无
 
+#### random
+
+**可选**, _number | function_
+
+功能描述： 自定义所使用的随机函数，其值可以是一个 [0, 1) 区间中的值，也可以是一个返回该值的函数，当该值是一个固定的值时，每次渲染相同数据的词云图时，其对应的每个单词的布局坐标一致
+
+默认配置： 默认使用的是浏览器内置的 `Math.random`，也就是每次渲染，单词的位置都不一样
+
+#### spiral
+
+**可选**, _'archimedean' | 'rectangular'_
+
+功能描述：当设置为 `archimedean` 时，整个词云图接近于`椭圆`的形状，当设置为 `rectangular` 时，整个词云图接近于`矩形`的形状
+
+默认配置： _'archimedean'_
+
+#### customPlacement
+
+**可选**, _function_
+
+功能描述： 自定义每个词语的坐标，使用该选项时，应配合 `wordStyle` 中的其它选项同时使用
+
+默认配置： 无
+
 #### timeInterval
 
 **可选**, _number_
@@ -70,22 +94,31 @@
 
 默认配置： 无
 
-| 细分配置      | 类型                           | 默认值    | 功能描述                                                        |
-| ------------- | ------------------------------ | --------- | --------------------------------------------------------------- |
-| fontFamily    | _string \| function_           | 'Verdana' | 词云的字体                                                      |
-| fontWeight    | _string \| number \| function_ | 'normal'  | 设置字体的粗细                                                  |
-| padding       | _number \| function_           | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
-| fontSize      | _number[] \| function_         | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
-| rotation      | _number[]_                     | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
-| rotationSteps | _number_                       | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
-| rotateRatio   | _number_                       | 0.5       | 旋转的比率 [0, 1]，默认是 0.5 也就是 50%可能发生旋转            |
-
-以上，某些属性可以设置为一个函数，其函数的参数是一个`object`，其属性如下
-
-| 细分配置 | 类型                                | 功能描述                                             |
-| -------- | ----------------------------------- | ---------------------------------------------------- |
-| text     | _string_                            | 文本内容                                             |
-| value    | _number_                            | 该文本所占权重                                       |
+| 细分配置      | 类型                             | 默认值    | 功能描述                                                        |
+| ------------- | -------------------------------- | --------- | --------------------------------------------------------------- |
+| fontFamily    | _string \| function_             | 'Verdana' | 词云的字体                                                      |
+| fontWeight    | _string \| number \| function_   | 'normal'  | 设置字体的粗细                                                  |
+| padding       | _number \| function_             | 1         | 每个单词所占的盒子的内边距，默认为 1。 越大单词之间的间隔越大。 |
+| fontSize      | _number[] \| number \| function_ | [20, 60]  | 字体的大小范围，比如 [10, 20] 表示最小字体是 10，最大 20        |
+| rotation      | _number[] \| number \| function_ | [0, 90]   | 旋转的最小角度和最大角度 默认 [0, 90]                           |
+| rotationSteps | _number_                         | 2         | 旋转实际的步数,越大可能旋转角度越小, 默认是 2                   |
+
+以上，某些属性可以设置为一个函数，其函数的参数如下：
+
+| 细分配置 | 类型     | 功能描述                       |
+| -------- | -------- | ------------------------------ |
+| word     | _Word_   | 每个文本的数据对象             |
+| index    | _number_ | 当前文本对象在总数据中的索引值 |
+| words    | _Word[]_ | 总的文本数据，是一个数组       |
+
+类型`Word`的配置如下：
+
+| 细分配置 | 类型     | 功能描述               |
+| -------- | -------- | ---------------------- |
+| text     | _string_ | 文本内容               |
+| value    | _number_ | 文本权重               |
+| color    | _any_    | 进行颜色映射的值       |
+| datum    | _object_ | 存储的所对应的原始数据 |
 
 `markdown:docs/common/color.zh.md`
 

diff --git a/src/plots/word-cloud/types.ts b/src/plots/word-cloud/types.ts
@@ -51,7 +51,7 @@ interface WordStyle {
    */
   readonly padding?: number | ((word: Word, index?: number, words?: Word[]) => number);
   /** 字体的大小范围,当为函数时，其参数是一个经过处理之后的数据元素的值 */
-  readonly fontSize?: [number, number] | ((word: Word, index?: number, words?: Word[]) => number);
+  readonly fontSize?: [number, number] | number | ((word: Word, index?: number, words?: Word[]) => number);
   /**
    * 旋转的最小角度和最大角度 默认 [0, 90]。
    *