README.md

# PI Tool Util 工具库文档

## 目录
- [功能概述](#功能概述)
- [特性](#特性)
- [核心数据结构](#核心数据结构)
- [核心方法](#核心方法)
- [风险提示](#风险提示)
- [QA](#qa)
- [使用示例](#使用示例)

## 功能概述
本工具库提供四大核心模块：
1. **基础工具模块**（index.ts）：包含数据类型处理、编解码、对象比较、函数调用等常用工具方法
2. **对象克隆模块**（clone.ts）：提供深度克隆实现及装饰器扩展，支持类级别的克隆方法生成  
3. **类型定义模块**（type.ts）：定义基础类型、比较函数、JSON类型等通用类型接口
4. **路径处理模块**（path.ts）：提供目录路径解析等文件路径操作工具
5. **数字格式化模块**（num_tool.ts）：处理数字格式化和变化的工具库
6. **时间格式化模块**（time_format.ts）：提供将特定格式时间字符串转换为标准日期时间格式的工具函数。

## 特性
- 支持UTF8编解码转换
- 提供深拷贝/浅拷贝多种克隆策略
- 包含类型检查与数据验证工具
- 支持对象差异比较（支持Map和普通对象）
- 提供装饰器驱动的克隆方法生成
- 完善的类型定义支持
- 提供跨平台路径处理能力（自动处理Windows/Unix路径差异）
- 支持目录路径规范化处理
- 自动处理路径结尾斜杠问题
- 提供数字自动变化的动画效果
- 支持千位分割显示（中文模式下支持“万、亿、兆”，英文模式下支持“k、m、g、t”）
- 提供灵活的初始显示字符数配置
- 支持处理特定格式时间字符串的格式化，例如将"20120901123000"转换为"2012-09-01 12:30:00"。

## 核心数据结构

### 来自 type.ts
```typescript
// 比较函数类型
export type Compare<T> = (el1: T, el2: T) => number;

// 克隆接口
export interface Clone {
    clone(): this;
}

// JSON数据类型定义
export type Json = any;

// 基础数值类型别名
export type i8 = number;
export type u8 = number;
// ...其他数值类型定义
```

## 核心方法

### 基础工具方法（index.ts）
**数据类型处理**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `isPrimaryDataType` | 判断基础数据类型 | 支持null/undefined/string/number/boolean |
| `objToPrimaryData` | 对象转基础数据类型 | 非字符串值自动JSON序列化 |

**编解码方法**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `utf8Decode` | UTF8解码 | 接受ArrayBuffer/Uint8Array |
| `ab2hex` | ArrayBuffer转十六进制字符串 | 支持Uint8Array输入 |
| `hex2ab` | 十六进制字符串转ArrayBuffer | 返回Uint8Array |

**对象操作**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `objDiff` | 对象差异比较 | 支持跳过_$开头的属性 |
| `deepCopy` | 深度拷贝 | 不支持循环引用 |
| `getValue` | 对象路径取值 | 支持.分隔符和数组路径 |
| `setValue` | 对象路径设值 | 自动创建中间对象/数组 |

**函数操作**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `call` | 安全函数调用 | 支持1-8个参数 |
| `objCall` | 对象方法调用 | 支持1-8个参数 |

**数组操作方法**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `arrDrop` | 高效删除数组元素 | 用最后一个元素填充空缺 |
| `arrInsert` | 安全插入元素 | 返回新数组不修改原数组 |
| `arrDelete` | 安全删除元素 | 返回新数组不修改原数组 |
| `arrayEqual` | 数组严格相等比较 | 顺序敏感型比较 |

**数据验证方法**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `validate` | 对象属性校验 | 校验属性类型和合法性 |

**实用工具**
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `randomString` | 生成随机字符串 | 可指定字符集和长度 |
| `upperFirst` | 首字母大写 | 支持普通字符串处理 |

### 克隆方法（clone.ts）
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `cloneObject` | 通用对象克隆 | 支持数组、Map、Set等类型 |
| `cloneAny` | 任意类型克隆 | 自动处理基础类型和对象 |
| `mapCopy` | Map浅拷贝 | 源Map到目标Map的条目复制 |

### 路径处理方法（path.ts）
**目录操作**
| 方法 | 功能 | 参数说明 | 返回值 |
|------|------|---------|--------|
| `dirname` | 提取路径中的目录 | path: 要处理的文件路径 | 不包含文件名的目录路径 |


### 数字格式化模块（num_tool.ts）
#### 配置变量
| 名称 | 类型 | 默认值 | 描述 |
|----|----|------|----|
| preShowCount | number | 5 | 初始显示字符个数（包含小数点） |
| afterShowCount | number | 5 | 缩减后显示字符个数（包含小数点） |
| language | 'zh-cn' | 'zh-cn' | 语言模式，支持 'zh-cn' 和 'en-us' |
| commaFilling | boolean | false | 英文模式下是否使用逗号填充 |

#### 核心方法
| 方法 | 功能 | 参数说明 |
|------|------|---------|
| `initData` | 初始化配置参数 |  |
| `parseNumber` | 处理数字并返回格式化字符串 |  |
| `changeNumber` | 处理数字的变化并提供动画效果 |  |


### 时间格式化方法（time_format.ts）

| 方法 | 功能 | 参数说明 | 返回值 |
|------|------|---------|--------|
| `getTimeString` | 将时间字符串转换为标准日期时间格式 | `num`: 时间字符串 | 格式化后的日期时间字符串 |



## 风险提示
1. **深拷贝性能**：`deepCopy`使用JSON序列化实现，处理大对象时可能有性能问题
2. **循环引用**：克隆方法不支持循环引用结构
3. **类型限制**：`objDiff`会跳过_$开头的属性
4. **Buffer处理**：ArrayBuffer使用slice实现克隆，共享内存时需注意
5. **路径规范化**：路径处理未自动转换路径分隔符（需确保输入统一使用/或\）
6. **相对路径**：处理以..开头的相对路径时需自行解析
7. **空路径处理**：空字符串路径会返回当前目录(.)
8. **性能影响**：频繁调用`changeNumber`方法可能会影响UI流畅度，建议合理控制调用频率。

## 注意事项
1. **依赖规范**：本工具库严格禁止引入任何外部依赖项，所有功能必须基于原生JavaScript/TypeScript实现
2. **模块纯净性**：保持各模块功能独立，禁止模块间产生不必要的耦合关系
3. **类型安全**：所有对外暴露的接口必须提供完整的类型定义
4. **兼容性**：需确保代码在ES6及以上环境能正常运行，不使用环境特定的API
5. **体积控制**：单个方法实现应保持精简，工具方法体积需控制在5KB以内

## QA
**Q1: 差异比较如何处理数组顺序？**  
A: 当前版本认为数组顺序不同即为不同

**Q2: 如何验证参数类型？**  
A: 使用`validate`方法进行类型校验

**Q3: 路径处理是否支持Windows反斜杠？**  
A: 当前版本要求统一使用正斜杠(/)作为路径分隔符，需调用方自行转换

**Q4: 处理空路径为什么返回"."？**  
A: 遵循POSIX标准，空路径表示当前工作目录

**Q5: 路径结尾带斜杠如何处理？**  
A: 自动去除结尾斜杠后再解析父目录（如"a/b/" 处理为"a/b"再解析父目录为"a"）

**Q6: 如何避免`changeNumber`方法对UI性能造成影响？**  
A: 建议合理控制`changeNumber`的调用频率，避免在UIheavy操作时频繁调用。此外，可以调整动画的时间参数，降低UI刷新频率。

## 使用示例

### 路径操作
```typescript
dirname("path/to/file.txt"); // 返回 "path/to"
dirname("/");               // 返回 "/" 
dirname("a/b");             // 返回 "a"
dirname("a");               // 返回 "."
dirname("a/b/");            // 返回 "a"
dirname("/a/b");            // 返回 "/a"
```

### UTF8编解码
```typescript
const encoded = utf8Encode("你好世界");
const decoded = utf8Decode(encoded); // 返回"你好世界"
```

### 数组操作
```typescript
// 安全删除元素
const arr = [1,2,3,4,5];
const newArr = arrDelete(arr, 2); // 返回[1,2,4,5]

// 高效删除
const arr2 = [1,2,3,4,5];
arrDrop(arr2, 3); // arr2变为[1,2,5,4]
```

### 数据验证
```typescript
validate(options, {
    timeout: 'number',
    retries: 'number'
}); // 校验options包含指定类型的属性
```

### 对象克隆
```typescript
// 普通对象深拷贝
const obj = { a: 1, b: new Map([['key', 'value']]) };
const clonedObj = cloneObject(obj);

// Map结构拷贝
const sourceMap = new Map([['id', 123]]);
const targetMap = new Map();
mapCopy(sourceMap, targetMap);
```

### 差异比较
```typescript
const diffCount = objDiff(objA, objB, (key, valA, valB) => {
    console.log(`差异字段 ${key}:`, valA, "=>", valB);
});
```


### 数字格式化
#### 1. 初始化配置
配置参数用于定义如何显示和变化数字。可以通过`initData`方法设置这些参数。
```typescript
// 初始化配置
NumberTool.initData(5, 5, 'zh-cn', false);
```
| 配置参数 | 描述 |
|----------|------|
| preShowCount: 5 | 初始显示字符个数（包含小数点） |
| afterShowCount: 5 | 缩减后显示字符个数（包含小数点） |
| language: 'zh-cn' | 语言模式，'zh-cn' 为中文，'en-us' 为英文 |
| commaFilling: false | 英文模式下是否用逗号填充 |

#### 2. 格式化数字
使用`parseNumber`方法处理数字，并返回格式化后的字符串。

##### 中文模式示例
```typescript
const result1 = NumberTool.parseNumber(123456789, 'zh-cn');
console.log(result1); // 输出：1.2亿
```

##### 英文模式示例
```typescript
const result2 = NumberTool.parseNumber(123456789, 'en-us');
console.log(result2); // 输出：123.456.789
```
注意：`commaFilling` 设置为 `true` 时，英文字号会自动添加逗号分隔。

#### 3. 数字变化动画效果
使用`changeNumber`方法实现数字的自动变化，并通过回调函数实时获取变化后的值。

```typescript
// 示例：数字从1000变化到5000
NumberTool.changeNumber(1000, 5000, (numStr) => {
    console.log(numStr); // 持续输出变化后的数字字符串
}, 1000); // 动画持续时间1000ms
```
此示例中，`changeNumber`方法会在1000ms内平滑地将数字1000变为5000，并在每一步向回调函数传递新的字符串值。

##### 复杂操作示例
```typescript
// 初始化配置
NumberTool.initData(5, 3, 'en-us', true);

// 数字变化并格式化显示
NumberTool.changeNumber(2500, 7500, (numStr) => {
    console.log("变化中的数值：", numStr);
    // 示例输出：
    // 变化中的数值：2.5k
    // 变化中的数值：2.6k
    // ... 其他变化值
    // 变化中的数值：7.5k
}, 2000); // 动画时间为2000ms
```
在这个例子中，数字从2500变化到7500，同时使用英文模式和逗号填充，变化效果会被平滑显示。

#### 4. 突变和平滑变化
可以通过多次调用`changeNumber`来实现多步变化：

```typescript
// 初始化配置
NumberTool.initData(5, 5, 'zh-cn', false);

//_unicode
NumberTool.changeNumber(1000, 5000, function(numStr) {
    console.log("第一步变化：", numStr);
}, 1000);

// warranty
NumberTool.changeNumber(5000, 10000, function(numStr) {
    console.log("第二步变化：", numStr);
}, 1000);
```

这将先将数字从1000增加到5000，然后再从5000增加到10000，形成一个连续的动画效果。

#### 5. 高级配置示例
配置不同的显示参数和语言，查看格式化结果的变化。

```typescript
// 初始配置为中文，不使用逗号填充
NumberTool.initData(5, 5, 'zh-cn', false);

// 使用默认配置格式化不同的数值
console.log(NumberTool.parseNumber(1234567)); // 输出：1.2千
console.log(NumberTool.parseNumber(123456789)); // 输出：1.2亿

// 修改配置为英文并启用逗号填充
NumberTool.initData(5, 5, 'en-us', true);
console.log(NumberTool.parseNumber(1234567)); // 输出：1,234.567
console.log(NumberTool.parseNumber(123456789)); // 输出：123,456,789
```
通过调整配置参数，可以实现不同的显示效果，适应不同的应用场景。

#### 6. 动态语言切换
在同一个应用中动态切换语言模式的示例：

```typescript
// 初始配置为中文
NumberTool.initData(5, 5, 'zh-cn', false);
console.log(NumberTool.parseNumber(123456789)); // 输出：1.2亿

// 切换到英文模式
NumberTool.initData(5, 5, 'en-us', true);
console.log(NumberTool.parseNumber(123456789)); // 输出：123,456,789
```

### 时间格式化
```typescript
const timeString = getTimeString("20120901123000"); // 输出 "2012-09-01 12:30:00"
```