1 | # util
|
2 |
|
3 | > AntV 底层依赖的工具库,不建议在自己业务中使用。
|
4 |
|
5 | [![Build Status](https://github.com/antvis/util/workflows/build/badge.svg)](https://github.com/antvis/util/actions)
|
6 | [![npm Version](https://img.shields.io/npm/v/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
|
7 | [![npm Download](https://img.shields.io/npm/dm/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
|
8 | [![npm License](https://img.shields.io/npm/l/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
|
9 |
|
10 | ## Usage
|
11 |
|
12 | ```ts
|
13 | import { gradient } from '@antv/util';
|
14 | ```
|
15 |
|
16 | ## 原则
|
17 |
|
18 | - util 只有一个 npm 包,按照目录来组织不同类型的方法,避免 monorepo 互相依赖
|
19 | - 内容和 AntV 强相关,避免做和 lodash 等相同的工具库
|
20 | - 不使用的方法,及时删除,并保持新增方法可以按需引入
|
21 | - 旧版本的不维护,如果 AntV 技术栈的旧版本需要迭代,请升级到 v3
|
22 |
|
23 | ## API
|
24 |
|
25 | 提供以下 Path 工具方法,包含转换、几何计算等。
|
26 |
|
27 | ### path2String
|
28 |
|
29 | 将 PathArray 转换成字符串形式,不会对原始定义中的命令进行修改:
|
30 |
|
31 | ```js
|
32 | const str: PathArray = [
|
33 | ['M', 10, 10],
|
34 | ['L', 100, 100],
|
35 | ['l', 10, 10],
|
36 | ['h', 20],
|
37 | ['v', 20],
|
38 | ];
|
39 | expect(path2String(str)).toEqual('M10 10L100 100l10 10h20v20');
|
40 | ```
|
41 |
|
42 | ### path2Absolute
|
43 |
|
44 | 将定义中的相对命令转换成绝对命令,例如:
|
45 |
|
46 | - l -> L
|
47 | - h -> H
|
48 | - v -> V
|
49 |
|
50 | 完整方法签名如下:
|
51 |
|
52 | ```js
|
53 | path2Absolute(pathInput: string | PathArray): AbsoluteArray;
|
54 | ```
|
55 |
|
56 | ```js
|
57 | const str: PathArray = [
|
58 | ['M', 10, 10],
|
59 | ['L', 100, 100],
|
60 | ['l', 10, 10],
|
61 | ['h', 20],
|
62 | ['v', 20],
|
63 | ];
|
64 | const arr = path2Absolute(str);
|
65 | expect(arr).toEqual([
|
66 | ['M', 10, 10],
|
67 | ['L', 100, 100],
|
68 | ['L', 110, 110],
|
69 | ['H', 130],
|
70 | ['V', 130],
|
71 | ]);
|
72 | ```
|
73 |
|
74 | ### path2Curve
|
75 |
|
76 | 将部分命令转曲,例如 L / A 转成 C 命令,借助 cubic bezier 易于分割的特性用于实现形变动画。
|
77 | 该方法内部会调用 [path2Absolute](#path2Absolute),因此最终返回的 PathArray 中仅包含 M 和 C 命令。
|
78 |
|
79 | 完整方法签名如下:
|
80 |
|
81 | ```js
|
82 | path2Curve(pathInput: string | PathArray): CurveArray;
|
83 | ```
|
84 |
|
85 | ```js
|
86 | expect(
|
87 | path2Curve([
|
88 | ['M', 0, 0],
|
89 | ['L', 100, 100],
|
90 | ]),
|
91 | ).toEqual([
|
92 | ['M', 0, 0],
|
93 | ['C', 44.194173824159215, 44.194173824159215, 68.75, 68.75, 100, 100],
|
94 | ]);
|
95 | ```
|
96 |
|
97 | ### clonePath
|
98 |
|
99 | 复制路径:
|
100 |
|
101 | ```js
|
102 | const cloned = clonePath(pathInput);
|
103 | ```
|
104 |
|
105 | ### reverseCurve
|
106 |
|
107 | ```js
|
108 | const pathArray: CurveArray = [
|
109 | ['M', 170, 90],
|
110 | ['C', 150, 90, 155, 10, 130, 10],
|
111 | ['C', 105, 10, 110, 90, 90, 90],
|
112 | ['C', 70, 90, 75, 10, 50, 10],
|
113 | ['C', 25, 10, 30, 90, 10, 90],
|
114 | ];
|
115 |
|
116 | const reversed = reverseCurve(pathArray);
|
117 | ```
|
118 |
|
119 | ### getPathBBox
|
120 |
|
121 | 获取几何定义下的包围盒,形如:
|
122 |
|
123 | ```js
|
124 | export interface PathBBox {
|
125 | width: number;
|
126 | height: number;
|
127 | x: number;
|
128 | y: number;
|
129 | x2: number;
|
130 | y2: number;
|
131 | cx: number;
|
132 | cy: number;
|
133 | cz: number;
|
134 | }
|
135 | ```
|
136 |
|
137 | ```js
|
138 | const bbox = getPathBBox([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']]);
|
139 |
|
140 | expect(bbox).toEqual({ cx: 50, cy: 50, cz: 150, height: 100, width: 100, x: 0, x2: 100, y: 0, y2: 100 });
|
141 | ```
|
142 |
|
143 | ### getTotalLength
|
144 |
|
145 | 获取路径总长度。
|
146 |
|
147 | ```js
|
148 | const length = getTotalLength([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']]);
|
149 |
|
150 | expect(length).toEqual(400);
|
151 | ```
|
152 |
|
153 | ### getPointAtLength
|
154 |
|
155 | 获取路径上从起点出发,到指定距离的点。
|
156 |
|
157 | ```js
|
158 | const point = getPointAtLength([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']], 0);
|
159 | expect(point).toEqual({ x: 0, y: 0 });
|
160 | ```
|
161 |
|
162 | ### getPathArea
|
163 |
|
164 | 计算路径包围的面积。内部实现中首先通过 [path2Curve](#path2Curve) 转曲,再计算 cubic curve 面积,[详见](https://stackoverflow.com/a/15845996)。
|
165 |
|
166 | 方法签名如下:
|
167 |
|
168 | ```js
|
169 | function getPathArea(path: PathArray): number;
|
170 | ```
|
171 |
|
172 | ### isPointInStroke
|
173 |
|
174 | 判断一个点是否在路径上,仅通过几何定义计算,不考虑其他样式属性例如线宽、lineJoin、miter 等。
|
175 |
|
176 | 方法签名如下:
|
177 |
|
178 | ```js
|
179 | isPointInStroke(pathInput: string | PathArray, point: Point): boolean;
|
180 | ```
|
181 |
|
182 | ```js
|
183 | const result = isPointInStroke(segments, { x: 10, y: 10 });
|
184 | ```
|
185 |
|
186 | ### distanceSquareRoot
|
187 |
|
188 | 计算两点之间的距离。
|
189 |
|
190 | 方法签名如下:
|
191 |
|
192 | ```js
|
193 | distanceSquareRoot(a: [number, number], b: [number, number]): number;
|
194 | ```
|
195 |
|
196 | ### equalizeSegments
|
197 |
|
198 | 将两条路径处理成段数相同,用于形变动画前的分割操作。
|
199 |
|
200 | ```js
|
201 | const [formattedPath1, formattedPath2] = equalizeSegments(path1, path2);
|
202 | ```
|
203 |
|
204 | ### isPointInPolygon
|
205 |
|
206 | 判断一个点是否在多边形内。多边形形如:
|
207 |
|
208 | ```js
|
209 | const polygon = [
|
210 | [0, 0],
|
211 | [0, 100],
|
212 | [30, 100],
|
213 | [30, 0],
|
214 | ];
|
215 |
|
216 | // [0, 0] 在多边形的边上
|
217 | isPointInPolygon(polygon, 0, 0); // true
|
218 | ```
|
219 |
|
220 | ### isPolygonsIntersect
|
221 |
|
222 | 判断两个多边形是否相交:
|
223 |
|
224 | ```js
|
225 | isPolygonsIntersect(polygon1, polygon2);
|
226 | ```
|
227 |
|
228 | ## License
|
229 |
|
230 | MIT@[AntV](https://github.com/antvis).
|