antvis · hustcc · Jun 16, 2025 · Jun 5, 2025 · Jun 5, 2025 · Jun 16, 2025
diff --git a/README.md b/README.md
@@ -1,265 +1,91 @@
-# util
+<h1 align="center">@antv/util</h1>
 
-> AntV 底层依赖的工具库，不建议在自己业务中使用。
+<div align="center">
+
+AntV 底层依赖的工具库，包含有所有的 util 纯函数，**不建议在自己业务中使用**，避免因为迭代过程的 Break Change 给您带来维护成本。
 
 [![Build Status](https://github.com/antvis/util/workflows/build/badge.svg)](https://github.com/antvis/util/actions)
 [![npm Version](https://img.shields.io/npm/v/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
 [![npm Download](https://img.shields.io/npm/dm/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
 [![npm License](https://img.shields.io/npm/l/@antv/util.svg)](https://www.npmjs.com/package/@antv/util)
 
-## Usage
-
-```ts
-import { gradient } from '@antv/util';
-```
-
-## 原则
+</div>
 
-- util 只有一个 npm 包，按照目录来组织不同类型的方法，避免 monorepo 互相依赖
-- 内容和 AntV 强相关，避免做和 lodash 等相同的工具库
-- 不使用的方法，及时删除，并保持新增方法可以按需引入
-- 旧版本的不维护，如果 AntV 技术栈的旧版本需要迭代，请升级到 v3
 
-## API
+## ✨ 特性
 
-提供以下 Path 工具方法，包含转换、几何计算等。
+- **轻量级**：按需实现代码逻辑，尽可能的减少包大小，目前约 `12kb`；在 lodash 未优化包大小之前，不要在 AntV 中使用 lodash。
+- **工具丰富**：包含了不同类别的函数上百种。
+- **可视化**：特化工具可视化中使用的颜色、形状、路径、向量、矩阵等方向的功能。
 
-### path2String
 
-将 PathArray 转换成字符串形式，不会对原始定义中的命令进行修改：
+## 📦 安装
 
-```js
-const str: PathArray = [
-  ['M', 10, 10],
-  ['L', 100, 100],
-  ['l', 10, 10],
-  ['h', 20],
-  ['v', 20],
-];
-expect(path2String(str)).toEqual('M10 10L100 100l10 10h20v20');
-```
-
-### path2Array
-
-将 PathArray 转换成数组，不会对原始定义中的命令进行修改：
-
-```js
-const str = 'M10 10L100 100l10 10h20v20';
-expect(path2Array(str)).toEqual([
-  ['M', 10, 10],
-  ['L', 100, 100],
-  ['l', 10, 10],
-  ['h', 20],
-  ['v', 20],
-]);
+```bash
+$ npm install @antv/util
 ```
 
-### path2Absolute
-
-将定义中的相对命令转换成绝对命令，例如：
+## 🔨 上手
 
-- l -> L
-- h -> H
-- v -> V
-
-完整方法签名如下：
-
-```js
-path2Absolute(pathInput: string | PathArray): AbsoluteArray;
-```
+```ts
+import { path2String, path2Array } from '@antv/util';
 
-```js
-const str: PathArray = [
+path2String([
   ['M', 10, 10],
   ['L', 100, 100],
   ['l', 10, 10],
   ['h', 20],
   ['v', 20],
-];
-const arr = path2Absolute(str);
-expect(arr).toEqual([
-  ['M', 10, 10],
-  ['L', 100, 100],
-  ['L', 110, 110],
-  ['H', 130],
-  ['V', 130],
-]);
-```
-
-### path2Curve
-
-将部分命令转曲，例如 L / A 转成 C 命令，借助 cubic bezier 易于分割的特性用于实现形变动画。
-该方法内部会调用 [path2Absolute](#path2Absolute)，因此最终返回的 PathArray 中仅包含 M 和 C 命令。
+]); 
+// ----> 'M10 10L100 100l10 10h20v20'
 
-完整方法签名如下：
-
-```js
-path2Curve(pathInput: string | PathArray): CurveArray;
+path2Array('M10 10L100 100l10 10h20v20');
+/**
+ *  ------->
+ * [
+ *  ['M', 10, 10],
+ *  ['L', 100, 100],
+ *  ['l', 10, 10],
+ *  ['h', 20],
+ *  ['v', 20],
+ * ]
+ */
 ```
 
-```js
-expect(
-  path2Curve([
-    ['M', 0, 0],
-    ['L', 100, 100],
-  ]),
-).toEqual([
-  ['M', 0, 0],
-  ['C', 44.194173824159215, 44.194173824159215, 68.75, 68.75, 100, 100],
-]);
-```
 
-### clonePath
+## 📎 API
 
-复制路径：
+- [color（颜色）](./docs/api/color.md) - 颜色格式转化、g 渐变转化 css 渐变等
+- [dom（元素）](./docs/api/dom.md) - 基础和 css 添加
+- [math（数学）](./docs/api/math.md) - 基础数学计算，包含判断点是否在两个点的线段上、判断点十分在多变形内等
+- [matrix（矩阵）](./docs/api/matrix.md) - 向量及矩阵计算方法
+- [path（图形）](./docs/api/path.md) - 图形绘画计算方法，包含转换、几何计算等
+- [lodash（通用方法）](./docs/api/lodash.md) - util 内置 lodash 通用方法，并添加了更多针对 AntV 的方法工具。
 
-```js
-const cloned = clonePath(pathInput);
-```
-
-### reverseCurve
-
-```js
-const pathArray: CurveArray = [
-  ['M', 170, 90],
-  ['C', 150, 90, 155, 10, 130, 10],
-  ['C', 105, 10, 110, 90, 90, 90],
-  ['C', 70, 90, 75, 10, 50, 10],
-  ['C', 25, 10, 30, 90, 10, 90],
-];
-
-const reversed = reverseCurve(pathArray);
-```
 
-### getPathBBox
+## 🚥 原则
 
-获取几何定义下的包围盒，形如：
-
-```js
-export interface PathBBox {
-  width: number;
-  height: number;
-  x: number;
-  y: number;
-  x2: number;
-  y2: number;
-  cx: number;
-  cy: number;
-  cz: number;
-}
-```
-
-```js
-const bbox = getPathBBox([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']]);
-
-expect(bbox).toEqual({ cx: 50, cy: 50, cz: 150, height: 100, width: 100, x: 0, x2: 100, y: 0, y2: 100 });
-```
+- util 只有一个 npm 包，按照目录来组织不同类型的方法，避免 monorepo 互相依赖。
+- 内容和 AntV 强相关，避免做和 lodash 等相同的工具库。
+- 不使用的方法，及时删除，并保持新增方法可以按需引入。
+- 保持单元测试、文档的完整性。
+- 旧版本不维护，如果 AntV 技术栈的旧版本需要迭代，请升级到 v3。
 
-### getTotalLength
 
-获取路径总长度。
+## 📮 贡献
 
-```js
-const length = getTotalLength([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']]);
-
-expect(length).toEqual(400);
-```
-
-### getPointAtLength
-
-获取路径上从起点出发，到指定距离的点。
-
-```js
-const point = getPointAtLength([['M', 0, 0], ['L', 100, 0], ['L', 100, 100], ['L', 0, 100], ['Z']], 0);
-expect(point).toEqual({ x: 0, y: 0 });
-```
-
-### getPathArea
-
-计算路径包围的面积。内部实现中首先通过 [path2Curve](#path2Curve) 转曲，再计算 cubic curve 面积，[详见](https://stackoverflow.com/a/15845996)。
-
-方法签名如下：
-
-```js
-function getPathArea(path: PathArray): number;
-```
-
-### isPointInStroke
-
-判断一个点是否在路径上，仅通过几何定义计算，不考虑其他样式属性例如线宽、lineJoin、miter 等。
-
-方法签名如下：
-
-```js
-isPointInStroke(pathInput: string | PathArray, point: Point): boolean;
-```
-
-```js
-const result = isPointInStroke(segments, { x: 10, y: 10 });
-```
-
-### distanceSquareRoot
-
-计算两点之间的距离。
-
-方法签名如下：
-
-```js
-distanceSquareRoot(a: [number, number], b: [number, number]): number;
-```
-
-### equalizeSegments
-
-将两条路径处理成段数相同，用于形变动画前的分割操作。
-
-```js
-const [formattedPath1, formattedPath2] = equalizeSegments(path1, path2);
-```
-
-### isPointInPolygon
-
-判断一个点是否在多边形内。多边形形如：
-
-```js
-const polygon = [
-  [0, 0],
-  [0, 100],
-  [30, 100],
-  [30, 0],
-];
-
-// [0, 0] 在多边形的边上
-isPointInPolygon(polygon, 0, 0); // true
-```
-
-### isPolygonsIntersect
-
-判断两个多边形是否相交：
-
-```js
-isPolygonsIntersect(polygon1, polygon2);
-```
+```bash
+$ git clone git@github.com:antvis/util.git
 
-## Benchmarks
+$ cd util
 
-Build first.
+$ npm i
 
-```bash
-yarn run benchmarks
-```
+$ npm t
+```📁
 
-We can get the following output in the console, it can be seen that the same method from 5.0 is ~3 times faster than 4.0.
+写完代码之后，提交 PR 即可。
 
-```js
-// logs
-// Path2String#4.0 x 14,795 ops/sec ±3.35% (79 runs sampled)
-// Path2String#5.0 x 51,710 ops/sec ±2.05% (85 runs sampled)
-// Fastest is Path2String#5.0
-
-// Path2Absolute#4.0 x 14,524 ops/sec ±2.55% (80 runs sampled)
-// Path2Absolute#5.0 x 35,120 ops/sec ±3.10% (81 runs sampled)
-// Fastest is Path2Absolute#5.0
-```
 
 ## License