1 | # `@antv/scale`
|
2 |
|
3 | > 0.3 版本不兼容之前 0.1.X,大体上兼容 0.2.x 版本,一些差异在最下面列出
|
4 |
|
5 | ## Description
|
6 |
|
7 | scale 有很多中文名,标度、度量、比例尺等等。它是数据空间到图形空间的转换桥梁,负责将数据从数据空间(定义域)转换为图形属性空间区域(值域),下文都称为度量。
|
8 |
|
9 | 例如:
|
10 |
|
11 | ![](https://www.oxxostudio.tw/img/articles/201411/20141112_1_04.png)
|
12 |
|
13 | 或者
|
14 |
|
15 | ![](https://www.oxxostudio.tw/img/articles/201411/20141112_1_05.png)
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ```ts
|
20 | import { getScale } from '@antv/scale';
|
21 |
|
22 | const Linear = getScale('linear');
|
23 |
|
24 | // 详情可参考单测用例
|
25 | const scale = new Linear({
|
26 | min: 0,
|
27 | max: 100,
|
28 | range: [0, 1],
|
29 | });
|
30 |
|
31 | scale.scale(30); // 0.3
|
32 | scale.invert(0.3); // 30
|
33 | scale.getText(30); // '30'
|
34 | ```
|
35 |
|
36 | ## API
|
37 |
|
38 | Scale 度量模块提供了下面 3 大类的度量
|
39 |
|
40 | - 分类度量:
|
41 | - cat: 分类度量
|
42 | - timeCat: 时间分类度量
|
43 | - 连续度量:
|
44 | - linear: 线性度量
|
45 | - time:连续的时间度量
|
46 | - log: log 度量
|
47 | - pow: pow 度量
|
48 | - quantize:分段度量,用户可以指定不均匀的分段
|
49 | - quantile: 等分度量,根据数据的分布自动计算分段
|
50 | - 常量度量
|
51 | - identity: 常量度量
|
52 | 这些度量的使用通过 getScale 方法来获取
|
53 |
|
54 | ```js
|
55 | import { getScale } from '@antv/scale';
|
56 |
|
57 | const Linear = getScale('linear');
|
58 | const TimeCat = getScale('timeCat');
|
59 | ```
|
60 |
|
61 | 度量的属性大部分一致,可以将属性分为:
|
62 |
|
63 | - 通用属性: 所有度量都适用的属性
|
64 | - 度量的专有属性:个别度量专有的属性,对其他度量无意义
|
65 |
|
66 | ### 通用属性
|
67 |
|
68 | | 名称 | 类型 | 说明 |
|
69 | | ---------- | ------------------ | -------------------------------------- |
|
70 | | type | string | 度量 类型 |
|
71 | | values | any[] | 定义域 |
|
72 | | min | any | 定义域的最小值,在分类型 度量 中为序号 |
|
73 | | max | any | 定义域的最大值 |
|
74 | | range | [number, number] | 值域的最小、最大值 |
|
75 | | tickCount | number | 期望的 tick 数量,非最终结果 |
|
76 | | formatter | func(value, index) | 格式化函数,用于 tooltip、tick 等展示 |
|
77 | | tickMethod | string/func(scale) | 计算 ticks 的方法 |
|
78 |
|
79 | #### tickMethod
|
80 |
|
81 | 这个属性用户设置计算 ticks 的方法,可以传入字符串或者回调函数,支持的字符串类型有:
|
82 |
|
83 | - `wilkinson-extended` :计算数字 ticks 的方法,linear 类型度量内置的计算方法
|
84 | - `r-pretty`: 计算数字 ticks 的方法, ticks 的 nice 效果很好,但是 tickCount 的精度太差
|
85 | - `time`: 时间 ticks 的计算方法,计算出一个 tickInterval,坐标刻度之间的间隔固定
|
86 | - `time-pretty`: 时间 ticks 的计算方法,会对年、月进行优化,time 类型度量内置的计算方法
|
87 | - `log`: 计算数字的 ticks 方法,按照 log 的函数来计算,生成 [0, 10, 100, 1000] 类似的 ticks
|
88 | - `pow`: 计算数字的 ticks 方法,按照 pow 的函数来计算,生成 [0, 4, 9, 16] 类似的 ticks
|
89 | - `quantile`: 计算数字的 ticks 方法,根据统计学上的 几分位 概念计算 ticks,表现的是数据的分布
|
90 |
|
91 | ### 通用的 Methods
|
92 |
|
93 | > 所有的 Scale 仅开放下面的方法,不提供任何其他方法
|
94 |
|
95 | | 名称 | 类型 | 说明 |
|
96 | | --------- | --------------------- | ---------------------------------- |
|
97 | | scale | (value: any): number | 将定义域的输入值转换为值域的输出值 |
|
98 | | invert | (scaled: number): any | 将值域的输入值转换为定义域的输出值 |
|
99 | | translate | (value: any): number | 分类型 度量 中,将定义域转化为序号 |
|
100 | | clone | (): void | 复制 度量 实例 |
|
101 | | getTicks | (): Tick[] | 获取所有 ticks 集合 |
|
102 | | getText | (value: any): string | 获取输入值的展示结果 |
|
103 | | change | (cfg) | 修改度量 |
|
104 |
|
105 | ### 专有属性
|
106 |
|
107 | 这里除了列举各个度量专有的属性,和一些属性适合的取值,例如 tickMethod 方法不同的度量适合的计算方式不一样,任意设置可能达不到想要的效果
|
108 |
|
109 | #### pow
|
110 |
|
111 | | 名称 | 类型 | 说明 |
|
112 | | exponent | number | 指数 |
|
113 |
|
114 | #### log
|
115 |
|
116 | | 名称 | 类型 | 说明 |
|
117 | | base | number | 对数底数 |
|
118 |
|
119 | #### quantize
|
120 |
|
121 | 这是一种分段度量,scale 按照用户设置的 ticks 进行计算 scale,如果未设置 ticks ,则使用 `r-pretty` 计算默认的 ticks
|
122 |
|
123 | #### quantile
|
124 |
|
125 | 这是一种按照数据密度自动分段的度量,按照设置的 values 计算 ticks,进行 scale 时按照 ticks 计算,而非均匀计算,使用 `tickMethod: quantile` 计算 ticks
|
126 |
|
127 | ## 与 2.x 的兼容性问题
|
128 |
|
129 | ### 新增的特性
|
130 |
|
131 | - tickMethod:2.x 计算 ticks 的算法都是固定在各个度量内部,3.x 中提供了用户改变计算 ticks 算法的接口
|
132 | - min, max:3.x 中 cat、timeCat 类型的 min, max 可以指定
|
133 | - 新增两种 scale: quantize, quantile
|
134 |
|
135 | ### 不再支持的属性(暂时不支持)
|
136 |
|
137 | - tickInterval, minTickInterval:在 linear、log、pow 度量中不再支持
|
138 | - transform:3.x 中移除这个函数,大多数度量中使用不到
|