# guap-utils

**Repository Path**: xguap/guap-utils

## Basic Information

- **Project Name**: guap-utils
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: guap

## README

# guap-utils
📚 无框架依赖的 JavaScript 通用工具函数库，封装前端高频使用的工具方法，提升开发效率。

## 📦 guap 生态成员
本包是 guap 技术生态核心成员之一，生态全套产品：
- ✅ guap-utils：JavaScript 通用工具函数包（基础核心）
- ✅ guap-components-vue：Vue3 专属业务组件库（Vue3 技术栈）
- ✅ guap-components-uni：Uniapp 跨端组件库（多端适配）

## ✨ 核心特性
- 🚀 零依赖，体积小巧，按需引入
- 📌 覆盖数组、对象、字符串、时间、浏览器等全场景工具函数
- 🔨 兼容所有前端项目，Vue/React/Uniapp 均可使用
- 📦 纯 ES Module 支持，现代化开发体验

## 🚀 安装使用

```bash
npm install guap-utils --save
```

## 快速开始

> **注意**：本库仅支持 ES Module 导入方式，需要 Node.js >= 14.8.0 或使用现代打包工具（webpack、vite、rollup 等）

### 默认导入

```javascript
import utils from 'guap-utils';

// 使用示例
const ext = utils.guapFile.getExt('image.jpg'); // 'jpg'
const formatted = utils.guapTime.formatDate(new Date(), 'YYYY-MM-DD'); // '2024-01-01'
const hex = utils.guapColor.rgbToHex(255, 0, 0); // '#ff0000'
```

### 命名导入

```javascript
import { guapFile, guapTime, guapColor, guapData, guapValidate } from 'guap-utils';

// 直接使用
const ext = guapFile.getExt('image.jpg'); // 'jpg'
const formatted = guapTime.formatDate(new Date(), 'YYYY-MM-DD'); // '2024-01-01'
const hex = guapColor.rgbToHex(255, 0, 0); // '#ff0000'
```

### 按需导入单个函数

```javascript
// 从指定模块导入单个函数
import { getExt, compressImg } from 'guap-utils/lib/file.js';
import { formatDate, getRelativeTime } from 'guap-utils/lib/time.js';
import { rgbToHex, hexToRgb } from 'guap-utils/lib/color.js';

// 直接使用
const ext = getExt('image.jpg'); // 'jpg'
const formatted = formatDate(new Date(), 'YYYY-MM-DD'); // '2024-01-01'
```

## 功能模块

### 📁 文件工具 (guapFile)

#### 基础操作
- `getExt(filename)` - 获取文件扩展名
- `getNameNoExt(filepath)` - 获取文件名（不含扩展名）
- `getName(filepath)` - 获取文件名（含扩展名）

#### 文件大小
- `formatSize(bytes, decimals)` - 格式化文件大小
- `sizeToBytes(sizeStr)` - 将字符串大小转换为字节数（如 '10MB' → 字节数）
- `validateFileSize(fileOrSize, maxSize)` - 验证文件大小（支持 File/Blob 对象或字节数，最大大小支持字符串或字节数）

#### Base64 转换
- `toBase64(file)` - 文件转 base64（返回 Promise）
- `toBlob(dataUrl)` - base64 转 Blob（二进制）
- `toFile(dataUrl, fileName)` - base64 转 File 对象
- `calcBase64Size(base64)` - 计算 base64 字符串的大小（MB）

#### 图片处理
- `compressImg(fileOrBase64, maxWidth, quality, pngToJpeg)` - 压缩图片（支持 File/Blob 对象或 base64 字符串，返回 Promise）
  - `fileOrBase64`: 图片文件对象或 base64 字符串
  - `maxWidth`: 最大宽度，默认 1000
  - `quality`: 压缩质量（0-1），默认根据文件大小自动调整
  - `pngToJpeg`: PNG 是否转换为 JPEG（默认 false，保持 PNG 格式以支持透明度）
- `getImageSize(fileOrUrlOrBase64)` - 获取图片尺寸（宽高），支持 File/Blob 对象、URL 字符串或 base64 字符串，返回 Promise<{width: number, height: number}>

#### 文件下载与转换
- `downloadFile(file, fileName)` - 下载文件（支持 Blob/File 对象或 URL 字符串）
- `blobToFile(blob, fileName, mimeType)` - Blob 转 File 对象

#### 其他
- `genUniqueName(filename)` - 生成唯一文件名（添加时间戳）
- `getMime(filename)` - 获取文件的 MIME 类型

### ⏰ 时间工具 (guapTime)

#### 格式化
- `formatDate(date, format)` - 格式化日期时间
- `formatNum(numStr, type)` - 格式化数字字符串为日期时间（DT_NUM/TM_NUM/DTTM_NUM）
- `getRelativeTime(date)` - 获取相对时间（如：刚刚、5分钟前）
- `formatDuration(milliseconds)` - 格式化时长（毫秒转可读格式）

#### 时间戳
- `getTimestamp(date)` - 获取时间戳
- `timestampToDate(timestamp)` - 时间戳转日期对象

#### 日期范围
- `getTodayStart()` - 获取今天的开始时间
- `getTodayEnd()` - 获取今天的结束时间
- `getDateStart(date)` - 获取指定日期的开始时间
- `getDateEnd(date)` - 获取指定日期的结束时间
- `getMonthStart(date)` - 获取本月的第一天
- `getMonthEnd(date)` - 获取本月的最后一天
- `getYearStart(date)` - 获取本年的第一天
- `getYearEnd(date)` - 获取本年的最后一天
- `getMonthDates(date, format)` - 获取当月所有日期
- `getDateRange(date, days, format)` - 获取当前日期前或后多少天的所有日期

#### 日期计算
- `getDaysDiff(date1, date2)` - 计算两个日期之间的天数差
- `addDays(date, days)` - 添加天数
- `getPrevDay(date)` - 获取上一天时间
- `addHours(date, hours)` - 添加小时
- `addMinutes(date, minutes)` - 添加分钟
- `addMonths(date, months)` - 添加月份
- `addYears(date, years)` - 添加年份

#### 日期判断
- `isToday(date)` - 判断是否为今天
- `isYesterday(date)` - 判断是否为昨天
- `isTomorrow(date)` - 判断是否为明天
- `isWeekday(date)` - 判断是否为工作日（周一到周五）
- `isWeekend(date)` - 判断是否为周末（周六和周日）
- `isSameYear(date1, date2)` - 判断是否为同一年
- `isSameMonth(date1, date2)` - 判断是否为同一月

#### 信息获取
- `getWeekday(date)` - 获取星期几（中文）
- `getWeekdayEn(date, short)` - 获取星期几（英文）
- `getMonthName(date)` - 获取月份名称（中文）
- `getMonthNameEn(date, short)` - 获取月份名称（英文）
- `getQuarter(date)` - 获取季度（1-4）
- `calculateAge(birthDate, referenceDate)` - 计算年龄

### 🎨 颜色工具 (guapColor)

#### 颜色转换
- `rgbToHex(r, g, b)` - RGB 转十六进制
- `hexToRgb(hex)` - 十六进制转 RGB
- `rgbToHsl(r, g, b)` - RGB 转 HSL
- `hslToRgb(h, s, l)` - HSL 转 RGB
- `hexToHsl(hex)` - 十六进制转 HSL
- `hslToHex(h, s, l)` - HSL 转十六进制
- `hexToRgba(hex, alpha)` - 十六进制转 RGBA 格式
- `rgbaToHex(rgba, includeAlpha)` - RGBA 转十六进制

#### 颜色生成
- `randomLightColor()` - 生成随机亮色
- `randomDarkColor()` - 生成随机暗色
- `generateGradient(startColor, endColor, steps)` - 生成渐变色数组
- `getComplementaryColor(hex)` - 生成互补色
- `generateTriadicColors(hex)` - 生成三色配色方案
- `getFillColorFromStroke(hexColor, alpha)` - 根据描边颜色生成填充色（带透明度）

### 📊 数据工具 (guapData)

#### 数据结构处理
- `handleTree(data, id, parentId, children)` - 构造树型结构数据
- `groupBy(data, key, childDataKey = 'allData')` - 数组归类（按指定字段分组）
- `replaceTextWithSpan(str, replaceText, color = '#FF0000')` - 替换字符串中的指定文本为带有<span>标签的HTML格式

### ✅ 验证工具 (guapValidate)

#### 格式验证
- `isPhone(phone)` - 校验是否为手机号
- `isEmail(email)` - 校验是否为邮箱
- `isUrl(url)` - 校验是否为链接（URL）
- `isIdCard(idCard)` - 校验是否为身份证号（中国）
- `isNumeric(value)` - 校验是否为数字字符串

#### 值处理
- `toEmptyString(value)` - 将 undefined、null 转换为空字符串，其他值保持不变
- `isEmpty(value)` - 校验是否为空（包括 null、undefined、空字符串、空数组、空对象）

## 使用示例

### 文件操作

```javascript
// 获取文件信息
const ext = utils.guapFile.getExt('image.jpg'); // 'jpg'
const name = utils.guapFile.getName('/path/to/file.txt'); // 'file.txt'
const size = utils.guapFile.formatSize(1024000); // '1000 KB'

// 文件大小验证
const isValid = utils.guapFile.validateFileSize(file, '10MB'); // 验证文件是否小于10MB
const isValid2 = utils.guapFile.validateFileSize(file.size, 10 * 1024 * 1024); // 使用字节数
const bytes = utils.guapFile.sizeToBytes('5MB'); // 5242880 (字节)

// Base64 转换
const base64 = await utils.guapFile.toBase64(file);
const blob = utils.guapFile.toBlob(base64);
const fileObj = utils.guapFile.toFile(base64, 'image.jpg');

// 图片压缩（支持 File 对象或 base64 字符串）
const compressed1 = await utils.guapFile.compressImg(file, 1000, 0.8); // 传入 File 对象
const compressed2 = await utils.guapFile.compressImg(base64Image, 1000, 0.8); // 传入 base64 字符串

// PNG 压缩优化：如果 PNG 压缩后体积变大，可以转换为 JPEG（不需要透明度时）
const compressed3 = await utils.guapFile.compressImg(pngFile, 1000, 0.8, true); // PNG 转 JPEG，压缩效果更好

// 获取图片尺寸（支持 File、URL 或 base64）
const size1 = await utils.guapFile.getImageSize(file); // 传入 File 对象
const size2 = await utils.guapFile.getImageSize('https://example.com/image.jpg'); // 传入 URL
const size3 = await utils.guapFile.getImageSize(base64Image); // 传入 base64 字符串
console.log(size1); // { width: 1920, height: 1080 }

// 文件下载与转换
utils.guapFile.downloadFile(blob, 'download.jpg');
const fileFromBlob = utils.guapFile.blobToFile(blob, 'image.jpg', 'image/jpeg');
```

### 时间处理

```javascript
// 格式化
const date = utils.guapTime.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');
const numDate = utils.guapTime.formatNum('20240101', 'DT_NUM'); // '2024-01-01'
const relative = utils.guapTime.getRelativeTime(new Date(Date.now() - 3600000)); // '1小时前'

// 日期范围
const monthDates = utils.guapTime.getMonthDates(new Date(), 'YYYY-MM-DD');
const dateRange = utils.guapTime.getDateRange(new Date(), 7, 'YYYY-MM-DD');

// 日期计算
const prevDay = utils.guapTime.getPrevDay(new Date());
const nextWeek = utils.guapTime.addDays(new Date(), 7);
```

### 颜色处理

```javascript
// 颜色转换
const hex = utils.guapColor.rgbToHex(255, 0, 0); // '#ff0000'
const rgb = utils.guapColor.hexToRgb('#ff0000'); // { r: 255, g: 0, b: 0 }
const rgba = utils.guapColor.hexToRgba('#ff0000', 0.5); // 'rgba(255, 0, 0, 0.5)'
const hexFromRgba = utils.guapColor.rgbaToHex('rgba(255, 0, 0, 0.5)'); // '#ff0000'

// 颜色生成
const lightColor = utils.guapColor.randomLightColor(); // 随机亮色
const darkColor = utils.guapColor.randomDarkColor(); // 随机暗色
const gradient = utils.guapColor.generateGradient('#ff0000', '#0000ff', 10); // 渐变色数组
const complementary = utils.guapColor.getComplementaryColor('#ff0000'); // 互补色
const triadic = utils.guapColor.generateTriadicColors('#ff0000'); // 三色配色方案
const fillColor = utils.guapColor.getFillColorFromStroke('#ff0000', 0.2); // 填充色
```

### 数据转换

```javascript
// 构造树型结构
const flatData = [
  { id: 1, name: 'A', parentId: null },
  { id: 2, name: 'B', parentId: 1 },
  { id: 3, name: 'C', parentId: 1 }
];
const tree = utils.guapData.handleTree(flatData, 'id', 'parentId', 'children');

// 数组分组
const data = [
  { category: 'A', value: 1 },
  { category: 'B', value: 2 },
  { category: 'A', value: 3 }
];
const grouped = utils.guapData.groupBy(data, 'category');

const testSpan = utils.guapData.replaceTextWithSpan('text123text', '123');
```

### 数据验证

```javascript
// 格式验证
utils.guapValidate.isPhone('13800138000'); // true
utils.guapValidate.isEmail('test@example.com'); // true
utils.guapValidate.isUrl('https://www.example.com'); // true
utils.guapValidate.isIdCard('110101199003075678'); // true

// 值处理
utils.guapValidate.toEmptyString(null); // ''
utils.guapValidate.toEmptyString(undefined); // ''
utils.guapValidate.toEmptyString('hello'); // 'hello' (保持不变)
utils.guapValidate.isEmpty(null); // true
utils.guapValidate.isEmpty([]); // true
```

## 环境要求

- Node.js >= 14.8.0（如果直接运行）
- 或使用现代打包工具（webpack 5+、vite、rollup 等）

## License

MIT