# utils

**Repository Path**: lwj1426282929/utils

## Basic Information

- **Project Name**: utils
- **Description**: 一款数据类型处理的工具库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-02-03
- **Last Updated**: 2025-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Utils

#### 介绍

一款简单的数据处理工具库。

#### 安装

1. npm

```bash
npm i lwj-utils -D
```

2. browser

```js
<script src="https://unpkg.com/@lwjjs/utils/dist/index.umd.js"></script>
```

#### Array

##### unique

针对数组进行去重，可传入关键属性对对象元素进行过滤。返回过滤后的新数组。

###### 语法

```js
// 普通去重
unique();

// 针对对象元素某一属性进行去重以及为空过滤
unique(key);
```

###### 参数:

| 参数 | 类型   | 是否必须 | 可选值 | 说明                     |
| ---- | ------ | -------- | ------ | ------------------------ |
| key  | string | 否       | -      | 对象元素过滤的关键属性名 |

###### 返回值

返回过滤后的新数组。

###### 示例

```js
const arr = [
  1,
  1,
  2,
  "2",
  { id: 2, name: "name1" },
  { id: 2, name: "name2" },
  { id: "", name: "name3" },
];

// 不传参数时直接进行最基本的元素去重
arr.unique(); // [1, 2, '2', { id: 2, name: "name1" }, { id: 2, name: "name2" }, { id: "", name: "name3" },]

// 传入字符串id,当元素为对象时根据id进行去重过滤
arr.unique("id"); // [1, 2, '2', { id: 2, name: "name1" }]
```

#### Number

##### format

格式化数字，返回格式化后的字符串。

###### 语法

```js
// 按千分位进行分隔
format(separator);

// 固定小数位数
format(separator, decimals);
```

###### 参数:

| 参数      | 类型   | 是否必须 | 可选值 | 说明         |
| --------- | ------ | -------- | ------ | ------------ |
| separator | string | 否       | -      | 千分位分隔符 |
| decimals  | number | 否       | -      | 小数位数     |

###### 返回值

返回格式化后的字符串。

###### 示例

```js
const num = 1234567;

// 按千分位进行分隔
num.format(","); // 1,234,567

// 保留固定小数位数
num.format(",", 2); // 1,234,567.00
```

#### Date

##### format

针对日期进行格式化，返回满足格式的日期字符串，若日期格式错误，则返回`Invalid Date`。

###### 语法

```js
format(formatStr);
```

###### 参数:

| 参数      | 类型   | 是否必须 | 可选值 | 说明                         |
| --------- | ------ | -------- | ------ | ---------------------------- |
| formatStr | string | 否       | -      | 格式化占位符，支持如下字符： |

| 标识 | 示例             | 描述                 |
| ---- | ---------------- | -------------------- |
| YY   | 18               | 年，两位数           |
| YYYY | 2018             | 年，四位数           |
| Q    | 1-4              | 季度，一位数         |
| QQ   | 01-04            | 季度，两位数         |
| M    | 1-12             | 月份，从 1 开始      |
| MM   | 01-12            | 月份，两位数         |
| MMM  | Jan-Dec          | 月份，英文缩写       |
| MMMM | January-December | 月份，英文全称       |
| D    | 1-31             | 日期，从 1 开始      |
| DD   | 01-31            | 日期，两位数         |
| d    | 0-6              | 星期几，星期天是 0   |
| dd   | Su-Sa            | 最简写的星期几       |
| ddd  | Sun-Sat          | 简写的星期几         |
| dddd | Sunday-Saturday  | 星期几，英文全称     |
| H    | 0-23             | 小时，24h 制         |
| HH   | 00-23            | 小时，24h 制，两位数 |
| h    | 0-12             | 小时，12h 制         |
| hh   | 01-12            | 小时，12h 制，两位数 |
| m    | 0-59             | 分钟                 |
| mm   | 00-59            | 分钟，两位数         |
| s    | 00-59            | 秒                   |
| ss   | 00-59            | 秒，两位数           |
| S    | 0-9              | 毫秒（十），一位数   |
| SS   | 0-99             | 毫秒（百），两位数   |
| SSS  | 0-999            | 毫秒（千），三位数   |
| Z    | -05:00           | UTC 的偏移量，±HH:mm |
| ZZ   | -0500            | UTC 的偏移量，±HH:mm |
| A    | AM / PM          | 上/下午，大写        |
| a    | am / pm          | 上/下午，小写        |

###### 返回值

返回格式化后的字符串。

###### 示例

```js
const date = new Date("2023/01/01");

date.format("YYYY-MM-DD"); // 2023-01-01
date.format("YYYY-MM-DD HH:mm:ss"); // 2023-01-01 00:00:00
```

##### add

增加一定时间，返回增加后的日期对象。

###### 语法

```js
add(number, unit);
```

###### 参数

| 参数   | 类型   | 是否必须 | 可选值                                                             | 说明                             |
| ------ | ------ | -------- | ------------------------------------------------------------------ | -------------------------------- |
| number | number | 是       | -                                                                  | 需要增加的数量，若为负数代表减去 |
| unit   | string | 是       | year、quarter、month、week、day、hour、minute、second、millisecond | 需要增加的单位                   |

###### 返回值

返回增加后的日期对象。

###### 示例

```js
const date = new Date("2023/01/01");
date.add(1, "day"); // Mon Jan 02 2023 00:00:00 GMT+0800 (中国标准时间)
```

##### subtract

减去一定时间，返回减去后的日期对象。

###### 语法

```js
subtract(number, unit);
```

###### 参数

| 参数   | 类型   | 是否必须 | 可选值                                                             | 说明                             |
| ------ | ------ | -------- | ------------------------------------------------------------------ | -------------------------------- |
| number | number | 是       | -                                                                  | 需要增加的数量，若为负数代表增加 |
| unit   | string | 是       | year、quarter、month、week、day、hour、minute、second、millisecond | 需要增加的单位                   |

###### 返回值

返回减去后的日期对象。

###### 示例

```js
const date = new Date("2023/01/01");
date.subtract(1, "day"); // Sat Dec 31 2022 00:00:00 GMT+0800 (中国标准时间)
```

#####

返回指定单位下相对于另一个日期之间的差异。

###### 语法

```js
diff(date, unit);
```

###### 参数

| 参数 | 类型   | 是否必须 | 可选值                                                             | 说明         |
| ---- | ------ | -------- | ------------------------------------------------------------------ | ------------ |
| date | Date   | 是       | -                                                                  | 相比较的日期 |
| unit | string | 是       | year、quarter、month、week、day、hour、minute、second、millisecond | 差异单位     |

###### 返回值

返回差异的数量。

###### 示例

```js
new Date("2023/01/01").diff(new Date("2022/01/02"), "day"); // 364
```

##### startOf

`startOf()`方法用于设置一个时间的开始，并返回对应的开始时间。

###### 语法

```js
startOf(unit);
```

###### 参数

| 参数 | 类型   | 是否必须 | 可选值                                                             | 说明     |
| ---- | ------ | -------- | ------------------------------------------------------------------ | -------- |
| unit | string | 是       | year、quarter、month、week、day、hour、minute、second、millisecond | 开始单位 |

###### 返回值

返回对应的开始日期对象。

###### 示例

```js
new Date().startOf("year"); // Sun Jan 01 2023 00:00:00 GMT+0800 (中国标准时间)
```

##### endOf

`endOf()`方法用于设置一个时间的结束，并返回对应的结束时间。

###### 语法

```js
endOf(unit);
```

###### 参数

| 参数 | 类型   | 是否必须 | 可选值                                                             | 说明     |
| ---- | ------ | -------- | ------------------------------------------------------------------ | -------- |
| unit | string | 是       | year、quarter、month、week、day、hour、minute、second、millisecond | 结束单位 |

###### 返回值

返回对应的结束日期对象。

###### 示例

```js
new Date().endOf("year"); // Sun Dec 31 2023 23:59:59 GMT+0800 (中国标准时间)
```

##### getQuarter

根据本地时间，返回一个指定的日期对象为哪一个季度。

###### 语法

```js
getQuarter();
```

###### 参数

| 参数 | 类型 | 是否必须 | 可选值 | 说明 |
| ---- | ---- | -------- | ------ | ---- |
| -    | -    | -        | -      | -    |

###### 返回值

返回一个指定的日期对象为哪一个季度。1-4。

###### 示例

```js
new Date().getQuarter(); // 1
```

##### getMonthDays

返回一个指定的日期对象所在月份的天数。

###### 参数

| 参数 | 类型 | 是否必须 | 可选值 | 说明 |
| ---- | ---- | -------- | ------ | ---- |
| -    | -    | -        | -      | -    |

###### 返回值

返回一个指定的日期对象所在月份的天数。

###### 示例

```js
new Date().getMonthDays(); // 31
```