# 公共工具箱 Tools

- [公共工具箱 Tools](#公共工具箱-tools)
  - [功能说明](#功能说明)
  - [引用方法](#引用方法)
  - [使用方法](#使用方法)
  - [方法列表](#方法列表)
    - [`toast()`](#toast)
    - [`getUrlParam(name, search)`](#geturlparamname-search)
    - [`createGUID()`](#createguid)
    - [`getRandomString(long)`](#getrandomstringlong)
    - [`isNumber(data)`](#isnumberdata)
    - [`isString(data)`](#isstringdata)
    - [`isBoolean(data)`](#isbooleandata)
    - [`isObject(data)`](#isobjectdata)
    - [`isArray(data)`](#isarraydata)
    - [`isFunction(data)`](#isfunctiondata)
    - [`isUndefined(data)`](#isundefineddata)
    - [`isNull(data)`](#isnulldata)
  - [部分功能详解](#部分功能详解)
    - [momentFormat 时间格式化](#momentformat-时间格式化)
    - [debounce、throttle 防抖和节流](#debouncethrottle-防抖和节流)

## 功能说明

Tools 是一个工具类，是一个处理类型判断、字符格式化等各种常见的编程任务的工具箱，它所有的方法都是静态方法

## 引用方法

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

## 使用方法

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

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

## 方法列表

### `toast()`
**功能**  
显示消息提示。

**参数**  
- `msg` (String)：需要显示的消息内容。  
- `duration` (Number，可选，默认值 `2000`)：消息显示的时长，单位为毫秒。  
- `mask` (Boolean，可选，默认值 `false`)：是否显示遮罩层。

**返回值**  
无

**示例**  
```javascript
Tools.toast('操作成功');
```

---

### `getUrlParam(name, search)`
**功能**  
解析 URL 参数。

**参数**  
- `name` (String)：需要解析的参数名。  
- `search` (String，可选)：自定义的查询字符串，默认为当前页面的 `window.location.search`。

**返回值**  
- `String`: 解析后的参数值。  
- `Null`: 如果参数不存在或在小程序环境中，返回 `null`。

**示例**  
```javascript
const userId = Tools.getUrlParam('userId');
```

**注意事项**  
- 该方法仅适用于浏览器环境，在小程序环境中，该方法直接返回 `null`  

---

### `createGUID()`
**功能**  
生成一个全局唯一标识符（GUID）。

**参数**  
无

**返回值**
- `String`：返回一个符合 GUID 格式的字符串。

**示例**
```javascript
const guid = Tools.createGUID();
console.log(guid); // 输出类似 "3b9f1a2c-4e5f-4d3a-8b2c-1a2b3c4d5e6f"
```

**注意事项**
- 生成的 GUID 是基于随机数的，虽然概率极低，但不能保证绝对唯一，因此不适于永久存储的业务。
  
---

### `getRandomString(long)`
**功能**  
生成一个指定长度的随机字符串。

**参数**
- `long` (Number，可选)：生成的字符串长度，默认为 32。

**返回值**：
- (String)：返回一个随机字符串。

**示例**
```javascript
const randomString = Tools.getRandomString(16);
console.log(randomString); // 输出类似 "aB3dEfGhIjKlMnOp"
```

**注意事项**：
- 生成的字符串仅包含指定的字符集，不包含容易混淆的字符（如 `1`, `l`, `0`, `O` 等）。

---

### `isNumber(data)`
**功能**：判断传入的数据是否为数值类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是数值类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isNumber(123)); // true
console.log(Tools.isNumber('123')); // false
```

---

### `isString(data)`
**功能**：判断传入的数据是否为字符串类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是字符串类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isString('hello')); // true
console.log(Tools.isString(123)); // false
```

---

### `isBoolean(data)`
**功能**：判断传入的数据是否为布尔类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是布尔类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isBoolean(true)); // true
console.log(Tools.isBoolean('true')); // false
```

---

### `isObject(data)`
**功能**：判断传入的数据是否为普通对象类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是普通对象类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isObject({})); // true
console.log(Tools.isObject([])); // false
```
---

### `isArray(data)`
**功能**：判断传入的数据是否为数组类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是数组类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isArray([])); // true
console.log(Tools.isArray({})); // false
```

---

### `isFunction(data)`
**功能**：判断传入的数据是否为函数类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是函数类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isFunction(() => {})); // true
console.log(Tools.isFunction({})); // false
```

---

### `isUndefined(data)`
**功能**：判断传入的数据是否为 `undefined`。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是 `undefined`，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isUndefined(undefined)); // true
console.log(Tools.isUndefined(null)); // false
```

---

### `isNull(data)`
**功能**：判断传入的数据是否为 `null`。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是 `null`，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isNull(null)); // true
console.log(Tools.isNull(undefined)); // false
```

---


## 部分功能详解

### 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);
```