知识库添加文档，公共工具箱

Tevin

2025-03-04 c40e7ce5519f6caa14dc11c13612f37d7b914646

知识库添加文档，公共工具箱

 @framework/210-公共工具箱Tools.md

New file
@@ -0,0 +1,357 @@
# 公共工具箱 Tools

用于处理各种常见的编程任务的工具箱

## 引用方法

```js
import {
    Tools
} from '@components/common/Tools';
```

## 使用方法

由于本工具箱全都是静态方法，无需实例化，可直接调用

```js
Tools.isNumber(12);
```

## 方法列表

```JS
export class Tools {
    /**
     * 显示消息
     * @param {string} msg - 消息内容
     * @param {number} [duration=2000] - 显示时长，默认2000毫秒
     * @param {boolean} [mask=false] - 是否显示透明蒙层，防止触摸穿透，默认false
     */
    static toast(msg, duration = 2000, mask = false) {}

    /**
     * URL参数解析
     * @param {string} name - 参数名
     * @param {string} [search] - URL查询字符串，默认当前页面URL
     * @return {string|null} 返回参数值或null
     */
    static getUrlParam(name, search) {}

    /**
     * 生成 GUID
     * @return {string} 返回生成的GUID
     */
    static createGUID() {}

    /**
     * 获取随机字符串
     * @param {number} [long] - 字符串长度，默认32
     * @return {string} 返回生成的随机字符串
     */
    static getRandomString(long = 32) {}

    /**
     * 判断是否是数字
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为数字
     */
    static isNumber(data) {}

    /**
     * 判断是否是字符串
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为字符串
     */
    static isString(data) {}

    /**
     * 判断是否为布尔值
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为布尔值
     */
    static isBoolean(data) {}

    /**
     * 判断是否是普通对象
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为普通对象
     */
    static isObject(data) {}

    /**
     * 判断是否是数组
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为数组
     */
    static isArray(data) {}

    /**
     * 判断是否是函数
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为函数
     */
    static isFunction(data) {}

    /**
     * 判断是否为未定义
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为未定义
     */
    static isUndefined(data) {}

    /**
     * 判断是否为 null
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为 null
     */
    static isNull(data) {}

    /**
     * 是否为空对象
     * @param {*} obj - 要判断的对象
     * @return {boolean} 返回是否为空对象
     */
    static isEmptyObject(obj) {}

    /**
     * 判断对象是否在属性上相等
     * @param {Object} a - 对象a
     * @param {Object} b - 对象b
     * @return {boolean} 返回对象是否相等
     */
    static isObjValEqual(a, b) {}

    /**
     * 统计字符串占位宽度（汉字占两位）
     * @param {string} string - 要统计的字符串
     * @return {number} 返回字符串占位宽度
     */
    static countStringLength(string) {}

    /**
     * 获取字符串基于字节长度的剪切点
     * @param {string} string - 要剪切的字符串
     * @param {number} byteLength - 字节长度
     * @return {number} 返回剪切点位置
     */
    static getStringCutIndex(string, byteLength) {}

    /**
     * 限制数值范围，超出边界返回边界值
     * @param {number|string} num - 数值
     * @param {[number, number]} range - 数值范围
     * @return {number} 返回限制后的数值
     */
    static limitNumberRange(num, range) {}

    /**
     * 深拷贝
     * @param {Object} source - 源对象
     * @return {Object|Array} 返回深拷贝后的对象或数组
     */
    static deepCopy(source) {}

    /**
     * 深合并
     * @param {Object|Array} target - 目标对象或数组
     * @param {Object|Array} source - 源对象或数组
     * @return {Object|Array} 返回合并后的对象或数组
     */
    static deepCombine(target, source) {}

    /**
     * 数组元素交换位置
     * @param {Array} arr - 数组
     * @param {number} fromIndex - 要交换项目的位置
     * @param {number} toIndex - 被交换项目的位置
     * @return {Array} 返回交换后的数组
     */
    static swapArray(arr, fromIndex, toIndex) {}

    /**
     * 使用 moment.js 格式化时间戳
     * @param {number|string} timestamp - 时间戳
     * @param {string} [type='date'] - 格式化类型
     * @return {string} 返回格式化后的时间字符串
     */
    static momentFormat(timestamp, type = 'date') {}

    /**
     * 数值转换为时长描述
     * @param {number} timestamp - 时间戳
     * @return {string} 返回时长描述
     */
    static durationFormat(timestamp) {}

    /**
     * 数值转换为金钱格式
     * @param {number|string} number - 数值
     * @param {string} [forRead=''] - 便于阅读财务金额模式
     * @return {string} 返回格式化后的金钱字符串
     */
    static moneyFormat(number, forRead = '') {}

    /**
     * 数值转换为千分位格式
     * @param {number|string} number - 数值
     * @param {string} decimalFormat - 处理小数的方式，有 notRetain、keepTwo、keepThree 三个值
     * @return {string} 返回格式化后的字符串
     */
    static thousandFormat(number, decimalFormat = 'keepTwo') {}

    /**
     * 加法函数，用来得到精确的加法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回加法结果
     */
    static accAdd(num1, num2) {}

    /**
     * 减法函数，用来得到精确的减法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回减法结果
     */
    static accSub(num1, num2) {}

    /**
     * 乘法函数，用来得到精确的乘法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回乘法结果
     */
    static accMul(num1, num2) {}

    /**
     * 除法函数，用来得到精确的除法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回除法结果
     */
    static accDiv(num1, num2) {}

    /**
     * 求小数点后的数据长度
     * @param {number|string} num - 数值
     * @return {number} 返回小数点后的数据长度
     */
    static getDecimalLength(num) {}

    /**
     * 判断是否为手机号码
     * @param {number|string} phone - 手机号码
     * @return {boolean} 返回是否为手机号码
     */
    static isPhone(phone) {}

    /**
     * 转换周数到日期
     * @param {number} year - 年份
     * @param {number} week - 周数
     * @param {number} weekDay - 需要输出星期几对应的日期 (1~7)
     * @return {string} 返回对应的日期
     */
    static transWeekIndexToDate(year, week, weekDay) {}

    /**
     * 防抖函数（一段时间周期内，仅执行最后一次回调）
     * @param {Function} fnc - 回调函数
     * @param {number} wait - 等待时间，默认200毫秒
     * @return {Function} 返回防抖函数
     * @tutorial Tools.debounce(<fnc>, <wait>)(<DebounceKey>)
     */
    static debounce(fnc, wait = 200) {}

    /**
     * 节流函数（本段时间内，仅执行第一次回调）
     * @param {Function} fnc - 回调函数
     * @param {number} wait - 等待时间，默认200毫秒
     * @return {Function} 返回节流函数
     * @tutorial Tools.throttle(<fnc>, <wait>)(<ThrottleKey>)
     */
    static throttle(fnc, wait = 200) {}

    /**
     * 精确保留小数点几位数，自动补零，修复 toFixed 四舍五入和后端不一致的问题
     * @param {number|string} num - 数值
     * @param {number} [digit=0] - 小数点后位数
     * @return {string|NaN} 返回保留小数点后的数值或NaN
     */
    static accFixed(num, digit = 0) {}
}
```

## 部分功能详解

### momentFormat 时间格式化

**参数**
* timestamp: 要格式化的时间戳，可以是数字或字符串，可以自动识别如下类型输入：
    - 毫秒时间戳字符串或数值，例如 1741077968000
    - 秒时间戳字符串或数值，例如：1741077968
    - 8位无符号日期字符串或数值，例如：20250101
    - 14位无符号日期时间字符串，例如：20250101221655
    - 有连接符日期时间字符串，例如：2025/01/02 12:30
* type: 格式化类型，可选值包括：
    - `'date'`: 默认值，返回格式为 `YYYY-MM-DD` 的日期字符串。
    - `'dateTime'`: 返回格式为 `YYYY-MM-DD HH:mm` 的日期时间字符串。
    - `'dateTimeShort'`: 返回格式为 `MM-DD HH:mm` 的日期时间字符串（不包含年份）。
    - `'dateTimeFull'`: 返回格式为 `YYYY-MM-DD HH:mm:ss` 的完整日期时间字符串。

例如：

```js
Tools.momentFormat(1617187200000); // 输出: '2021-03-31'

Tools.momentFormat(1617187200000, 'dateTime'); // 输出: '2021-03-31 00:00'

Tools.momentFormat(1617187200000, 'dateTimeShort'); // 输出: '03-31 00:00'

Tools.momentFormat(1617187200000, 'dateTimeFull'); // 输出: '2021-03-31 00:00:00'

Tools.momentFormat(1741077968); // 输出：'2025-03-04'

Tools.momentFormat(20250101); // 输出：'2025-01-01'

Tools.momentFormat('20250101'); // 输出：'2025-01-01'

Tools.momentFormat('20250101221655', 'dateTimeFull'); // 输出：'2025-01-01 22:16:55'

Tools.momentFormat('2025/01/01 12:30', 'dateTimeFull'); // 输出：'2025-01-01 12:30:00'
```

### debounce、throttle 防抖和节流

**debounce** 
防抖的目的是在一段时间内只执行最后一次函数调用，避免频繁触发函数，也就是说，如果在这个时间内再次触发调用，就重新计算时间

**throttle**
节流和防抖类似，区别是一段时间内只执行第一次函数调用，如果这个时间内再次触发，则忽略，直到下一个时间段开心才允许再次调用

**额外说明**
因为静态方法全局共享的原因，加了一层封装，需要二次执行并填写唯一名称，以避免多个防抖或节流相互干扰

用法示例：

```js
// 公司名称输入的防抖
Tools.debounce(() => {
    // 处理输入事件
    // some code
}, 1000)('companyNameInput');
```

```js
setInterval(() => {
    // 每次执行的事件
    // some code A

    // 绘图操作中的节流
    Tools.throttle(() => {
        // 不需要每次都执行的功能，节约性能开销
        // some code B
    }, 1000)('drawImgResult');
}, 10);
```

 @framework/210-公共工具集合.md