npm package: @gbb/mx-utils
Description: 实用工具函数库
Author: mxbc
Latest version: 0.0.5

# mxUtils

一个功能丰富的 JavaScript 工具库，提供常用的工具函数，包括数据验证、文件下载、水印处理、MD5加密等功能。

## 📦 安装

```bash
npm install @mxbc/mx-utils
# 或
yarn add @mxbc/mx-utils
# 或
pnpm add @mxbc/mx-utils
```

## 🚀 快速开始

### ES6 模块导入

```javascript
import mxUtils from '@mxbc/mx-utils'

// 使用工具函数
const uuid = mxUtils.getUUID()
const isValidEmail = mxUtils.isEmail('test@example.com')
```

### 按需导入

```javascript
import { getUUID, isEmail, downloadImg } from '@mxbc/mx-utils'

const uuid = getUUID()
const isValidEmail = isEmail('test@example.com')
```

## 📚 API 文档

### 🔧 通用工具函数

#### `getUUID()`
生成唯一的 UUID 字符串。

```javascript
const uuid = mxUtils.getUUID()
// 输出: "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"
```

#### `isAuth(key)`
检查用户是否有指定权限。

```javascript
const hasPermission = mxUtils.isAuth('admin:read')
// 从 sessionStorage 中检查权限
```

#### `isFunction(value)`
检查值是否为函数类型。

```javascript
const isFn = mxUtils.isFunction(() => {})
// 输出: true
```

#### `isArray(value)`
检查值是否为数组类型。

```javascript
const isArr = mxUtils.isArray([1, 2, 3])
// 输出: true
```

#### `isObject(value)`
检查值是否为对象类型。

```javascript
const isObj = mxUtils.isObject({ name: 'test' })
// 输出: true
```

#### `parseObjToURL(obj, traditional)`
将对象转换为 URL 查询字符串。

```javascript
const params = { name: 'test', age: 25 }
const queryString = mxUtils.parseObjToURL(params)
// 输出: "name=test&age=25"
```

#### `unique(arr)`
数组去重。

```javascript
const uniqueArr = mxUtils.unique([1, 2, 2, 3, 3, 4])
// 输出: [1, 2, 3, 4]
```

#### `debounce(fn, wait)`
防抖函数。

```javascript
const debouncedFn = mxUtils.debounce(() => {
  console.log('防抖执行')
}, 300)
```

#### `pathFormat(path)`
格式化路径。

```javascript
const formattedPath = mxUtils.pathFormat('/api/users')
```

#### `combinationObject(obj, data)`
合并对象。

```javascript
const result = mxUtils.combinationObject({ a: 1 }, { b: 2 })
// 输出: { a: 1, b: 2 }
```

### 📧 数据验证

#### `isEmail(email)`
验证邮箱格式。

```javascript
const isValid = mxUtils.isEmail('test@example.com')
// 输出: true
```

#### `isMobile(phone)`
验证手机号码格式（中国大陆）。

```javascript
const isValid = mxUtils.isMobile('13800138000')
// 输出: true
```

#### `checkIdcard(idNumber)`
验证身份证号码。

```javascript
const isValid = mxUtils.checkIdcard('110101199001011234')
// 输出: true
```

#### `isPhone(phone)`
验证电话号码格式。

```javascript
const isValid = mxUtils.isPhone('010-12345678')
// 输出: true
```

### ⏰ 时间处理

#### `getMonth(type, months)`
获取指定月份的开始或结束时间。

```javascript
// 获取本月开始时间
const monthStart = mxUtils.getMonth('s', 0)

// 获取下月结束时间
const nextMonthEnd = mxUtils.getMonth('e', 1)
```

#### `formatTime(date, format)`
格式化时间。

```javascript
const formatted = mxUtils.formatTime(new Date(), 'YYYY-MM-DD HH:mm:ss')
// 输出: "2024-01-01 12:00:00"
```

#### `setTime(value)`
设置时间格式。

```javascript
const time = mxUtils.setTime('2024-01-01')
```

#### `setTimeTwo(value)`
设置时间格式（第二种方式）。

```javascript
const time = mxUtils.setTimeTwo('2024-01-01')
```

### 📥 文件下载

#### `downloadImg(url, fileName)`
下载图片文件。

```javascript
mxUtils.downloadImg('https://example.com/image.jpg', 'my-image.jpg')
```

### 🔐 MD5 加密

#### `createStrBeforeSign(data)`
生成签名前的字符串。

```javascript
const data = { name: 'test', age: 25 }
const signStr = mxUtils.createStrBeforeSign(data)
```

#### `getMd5Params(data)`
生成带 MD5 签名的参数。

```javascript
const data = { name: 'test', age: 25 }
const paramsWithSign = mxUtils.getMd5Params(data)
// 输出: { name: 'test', age: 25, sign: 'md5hash', s: 2, t: timestamp }
```

### 🎨 水印处理

#### `setWaterMark(text)`
添加水印到页面。

```javascript
mxUtils.setWaterMark('机密文件')
```

#### `removeWatermark()`
移除页面水印。

```javascript
mxUtils.removeWatermark()
```

## 📋 完整示例

```javascript
import mxUtils from '@mxbc/mx-utils'

// 生成 UUID
const uuid = mxUtils.getUUID()

// 验证数据
const isValidEmail = mxUtils.isEmail('user@example.com')
const isValidMobile = mxUtils.isMobile('13800138000')
const isValidIdCard = mxUtils.checkIdcard('110101199001011234')

// 数组去重
const uniqueArray = mxUtils.unique([1, 2, 2, 3, 3, 4])

// 对象转 URL 参数
const params = mxUtils.parseObjToURL({
  name: '张三',
  age: 25,
  hobbies: ['读书', '游泳']
})

// 下载图片
mxUtils.downloadImg('https://example.com/avatar.jpg', 'avatar.jpg')

// 添加水印
mxUtils.setWaterMark('内部文档')

// 防抖函数
const debouncedSearch = mxUtils.debounce((keyword) => {
  console.log('搜索:', keyword)
}, 500)

// MD5 签名
const apiParams = mxUtils.getMd5Params({
  userId: 123,
  action: 'getUserInfo'
})
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 🔗 相关链接