utils-toolkit-alone/README.md

一个功能丰富的JavaScript工具库，包含时间格式处理、金额格式化、电话号码处理、正则校验、字符串转换、localStorage、sessionStorage和Cookie操作等实用功能

# Utils Toolkit Alone

一个功能丰富的JavaScript/TypeScript工具库，包含时间格式处理、金额格式化、电话号码处理、正则校验、车牌验证、字符串转换、localStorage、sessionStorage和Cookie操作等实用功能。

## 特性

- 🕒 **时间格式处理** - 日期格式化、解析、相对时间等
- 💰 **金额格式处理** - 货币格式化、中文大写、税费计算等
- 📱 **电话号码处理** - 手机号/固话验证、格式化、隐藏等
- ✅ **正则校验** - 邮箱、身份证、URL、IP等常用验证
- 🚗 **车牌验证** - 中国车牌号验证、类型识别、省份解析等
- 🔤 **字符串转换** - 大小写转换、命名法转换、字符串处理等
- 💾 **localStorage操作** - 本地存储的增删改查、过期管理、加密存储等
- 🗂️ **sessionStorage操作** - 会话存储管理、数据迁移、批量操作等
- 🍪 **Cookie操作** - Cookie的设置、获取、删除、批量管理等

## 安装

```bash
npm install utils-toolkit-alone
```

## 使用方法

### ES6 模块导入

```javascript
// 导入特定功能
import { 
  formatDate, 
  formatCurrency, 
  isValidEmail, 
  validateLicensePlate,
  setLocalStorageItem,
  getCookie,
  setSessionStorageItem
} from 'utils-toolkit-alone';

// 或导入整个模块
import UtilsToolkit from 'utils-toolkit-alone';

// 或导入存储模块
import { LocalStorageUtils, SessionStorageUtils, CookieUtils } from 'utils-toolkit-alone';
```

### CommonJS 导入

```javascript
const { formatDate, formatCurrency, isValidEmail } = require('utils-toolkit-alone');
```

## API 文档

### 时间格式处理 (DateUtils)

#### formatDate(date, format)
格式化日期为指定格式

```javascript
import { formatDate } from 'utils-toolkit-alone';

formatDate(new Date(), 'YYYY-MM-DD'); // '2023-12-25'
formatDate(new Date(), 'YYYY年MM月DD日'); // '2023年12月25日'
formatDate(new Date(), 'HH:mm:ss'); // '15:30:45'
```

#### getRelativeTime(date)
获取相对时间描述

```javascript
import { getRelativeTime } from 'utils-toolkit-alone';

getRelativeTime(new Date(Date.now() - 60000)); // '1分钟前'
getRelativeTime(new Date(Date.now() - 3600000)); // '1小时前'
```

### 金额格式处理 (CurrencyUtils)

#### formatCurrency(amount, options)
格式化金额

```javascript
import { formatCurrency } from 'utils-toolkit-alone';

formatCurrency(1234.56); // '¥1,234.56'
formatCurrency(1234.56, { symbol: '$' }); // '$1,234.56'
formatCurrency(1234.56, { precision: 0 }); // '¥1,235'
```

#### toChinese(amount)
金额转换为中文大写

```javascript
import { toChinese } from 'utils-toolkit-alone';

toChinese(1234.56); // '壹仟贰佰叁拾肆元伍角陆分'
```

### 电话号码处理 (PhoneUtils)

#### isValidMobile(phone)
验证手机号码

```javascript
import { isValidMobile } from 'utils-toolkit-alone';

isValidMobile('13812345678'); // true
isValidMobile('12345678901'); // false
```

#### formatMobile(mobile, options)
格式化手机号码

```javascript
import { formatMobile } from 'utils-toolkit-alone';

formatMobile('13812345678'); // '138 1234 5678'
formatMobile('13812345678', { format: 'international' }); // '+86 138 1234 5678'
```

#### hideMobile(mobile)
隐藏手机号码中间四位

```javascript
import { hideMobile } from 'utils-toolkit-alone';

hideMobile('13812345678'); // '138****5678'
```

### 正则校验 (ValidationUtils)

#### isValidEmail(email)
验证邮箱地址

```javascript
import { isValidEmail } from 'utils-toolkit-alone';

isValidEmail('test@example.com'); // true
isValidEmail('invalid-email'); // false
```

#### isValidIdCard(idCard)
验证身份证号

```javascript
import { isValidIdCard } from 'utils-toolkit-alone';

isValidIdCard('110101199003077777'); // true (示例)
```

#### getPasswordStrength(password)
获取密码强度

```javascript
import { getPasswordStrength } from 'utils-toolkit-alone';

getPasswordStrength('123456'); // 'weak'
getPasswordStrength('Abc123!@#'); // 'strong'
```

### 车牌验证 (LicensePlateUtils)

#### validateLicensePlate(licensePlate)
验证车牌号并返回详细信息

```javascript
import { validateLicensePlate } from 'utils-toolkit-alone';

// 传统车牌（7位）
const result1 = validateLicensePlate('京A12345');
console.log(result1);
// {
//   isValid: true,
//   vehicleType: 'civilian',
//   energyType: 'traditional',
//   province: '北京',
//   cityCode: 'A',
//   originalPlate: '京A12345'
// }

// 新能源车牌（8位）
const result2 = validateLicensePlate('京AD12345');
console.log(result2);
// {
//   isValid: true,
//   vehicleType: 'civilian',
//   energyType: 'new_energy',
//   province: '北京',
//   cityCode: 'A',
//   originalPlate: '京AD12345'
// }
```

#### isTruckLicensePlate(licensePlate)
判断是否为货车车牌（简化规则下始终返回false）

```javascript
import { isTruckLicensePlate } from 'utils-toolkit-alone';

isTruckLicensePlate('京A12345'); // false
isTruckLicensePlate('粤B67890'); // false
```

#### isCivilianLicensePlate(licensePlate)
判断是否为民用车车牌

```javascript
import { isCivilianLicensePlate } from 'utils-toolkit-alone';

isCivilianLicensePlate('京A12345'); // true
isCivilianLicensePlate('粤BF67890'); // true
isCivilianLicensePlate('INVALID'); // false
```

#### isNewEnergyLicensePlate(licensePlate)
判断是否为新能源车牌（8位长度）

```javascript
import { isNewEnergyLicensePlate } from 'utils-toolkit-alone';

isNewEnergyLicensePlate('京AD12345'); // true (8位)
isNewEnergyLicensePlate('粤BF67890'); // true (8位)
isNewEnergyLicensePlate('京A12345'); // false (7位)
```

#### isTraditionalLicensePlate(licensePlate)
判断是否为传统燃油车牌（7位长度）

```javascript
import { isTraditionalLicensePlate } from 'utils-toolkit-alone';

isTraditionalLicensePlate('京A12345'); // true (7位)
isTraditionalLicensePlate('粤B1234A'); // true (7位)
isTraditionalLicensePlate('京AD12345'); // false (8位)
```

#### getLicensePlateProvince(licensePlate)
获取车牌所属省份

```javascript
import { getLicensePlateProvince } from 'utils-toolkit-alone';

getLicensePlateProvince('京A12345'); // '北京'
getLicensePlateProvince('粤B67890'); // '广东'
getLicensePlateProvince('沪C12345'); // '上海'
getLicensePlateProvince('INVALID'); // ''
```

### 字符串转换 (StringUtils)

#### 大小写转换

```javascript
import { 
  toUpperCase, 
  toLowerCase, 
  capitalize, 
  toTitleCase 
} from 'utils-toolkit-alone';

toUpperCase('hello world'); // 'HELLO WORLD'
toLowerCase('HELLO WORLD'); // 'hello world'
capitalize('hello world'); // 'Hello world'
toTitleCase('hello world'); // 'Hello World'
```

#### 命名法转换

```javascript
import { 
  toCamelCase, 
  toPascalCase, 
  toSnakeCase, 
  toKebabCase 
} from 'utils-toolkit-alone';

toCamelCase('hello world'); // 'helloWorld'
toPascalCase('hello world'); // 'HelloWorld'
toSnakeCase('hello world'); // 'hello_world'
toKebabCase('hello world'); // 'hello-world'
```

### localStorage 操作 (LocalStorageUtils)

#### 基础操作

```javascript
import { 
  isLocalStorageSupported,
  setLocalStorageItem,
  getLocalStorageItem,
  removeLocalStorageItem,
  clearLocalStorage
} from 'utils-toolkit-alone';

// 检查浏览器支持
isLocalStorageSupported(); // true/false

// 设置项目
setLocalStorageItem('username', 'john');
setLocalStorageItem('user', { name: 'John', age: 30 }); // 自动序列化对象

// 获取项目
getLocalStorageItem('username'); // 'john'
getLocalStorageItem('user'); // { name: 'John', age: 30 }

// 删除项目
removeLocalStorageItem('username');

// 清空所有
clearLocalStorage();
```

#### 高级功能

```javascript
import { 
  setLocalStorageItem,
  getLocalStorageItem,
  setMultipleLocalStorageItems,
  getMultipleLocalStorageItems,
  clearExpiredLocalStorageItems,
  getLocalStorageSize,
  hasLocalStorageKey
} from 'utils-toolkit-alone';

// 设置带过期时间的项目
setLocalStorageItem('temp_data', 'value', { 
  expires: new Date(Date.now() + 3600000) // 1小时后过期
});

// 设置加密存储
setLocalStorageItem('secret', 'sensitive_data', { 
  encrypt: true 
});

// 批量设置
setMultipleLocalStorageItems({
  'key1': 'value1',
  'key2': { data: 'object' }
});

// 批量获取
getMultipleLocalStorageItems(['key1', 'key2']);

// 检查键是否存在
hasLocalStorageKey('username'); // true/false

// 获取存储大小
getLocalStorageSize(); // 返回已使用的字节数

// 清理过期项目
clearExpiredLocalStorageItems();
```

### sessionStorage 操作 (SessionStorageUtils)

#### 基础操作

```javascript
import { 
  isSessionStorageSupported,
  setSessionStorageItem,
  getSessionStorageItem,
  removeSessionStorageItem,
  clearSessionStorage
} from 'utils-toolkit-alone';

// 检查浏览器支持
isSessionStorageSupported(); // true/false

// 设置项目
setSessionStorageItem('temp_user', { id: 1, name: 'John' });

// 获取项目
getSessionStorageItem('temp_user'); // { id: 1, name: 'John' }

// 删除项目
removeSessionStorageItem('temp_user');

// 清空所有
clearSessionStorage();
```

#### 数据迁移功能

```javascript
import { 
  migrateSessionStorageToLocalStorage,
  restoreSessionStorageFromLocalStorage
} from 'utils-toolkit-alone';

// 将sessionStorage数据迁移到localStorage
migrateSessionStorageToLocalStorage('user_session');

// 从localStorage恢复到sessionStorage
restoreSessionStorageFromLocalStorage('user_session');
```

### Cookie 操作 (CookieUtils)

#### 基础操作

```javascript
import { 
  isCookieSupported,
  setCookie,
  getCookie,
  removeCookie,
  hasCookie
} from 'utils-toolkit-alone';

// 检查Cookie支持
isCookieSupported(); // true/false

// 设置Cookie
setCookie('username', 'john');
setCookie('preferences', { theme: 'dark', lang: 'zh' }); // 自动序列化对象

// 获取Cookie
getCookie('username'); // 'john'
getCookie('preferences'); // { theme: 'dark', lang: 'zh' }

// 检查Cookie是否存在
hasCookie('username'); // true/false

// 删除Cookie
removeCookie('username');
```

#### Cookie选项设置

```javascript
import { setCookie, setObjectCookie } from 'utils-toolkit-alone';

// 设置带选项的Cookie
setCookie('session_id', 'abc123', {
  expires: new Date(Date.now() + 86400000), // 24小时后过期
  path: '/',
  domain: '.example.com',
  secure: true,
  httpOnly: false,
  sameSite: 'Strict'
});

// 设置对象Cookie
setObjectCookie('user_settings', {
  theme: 'dark',
  notifications: true
}, {
  expires: new Date(Date.now() + 7 * 86400000) // 7天后过期
});
```

#### 批量操作

```javascript
import { 
  setMultipleCookies,
  getMultipleCookies,
  removeMultipleCookies,
  getAllCookies,
  clearAllCookies
} from 'utils-toolkit-alone';

// 批量设置Cookie
setMultipleCookies({
  'key1': 'value1',
  'key2': 'value2'
}, {
  path: '/',
  expires: new Date(Date.now() + 86400000)
});

// 批量获取Cookie
getMultipleCookies(['key1', 'key2']); // { key1: 'value1', key2: 'value2' }

// 批量删除Cookie
removeMultipleCookies(['key1', 'key2']);

// 获取所有Cookie
getAllCookies(); // { key1: 'value1', key2: 'value2', ... }

// 清空所有Cookie
clearAllCookies();
```

## 模块化使用

你也可以按模块导入：

```javascript
import { 
  DateUtils, 
  CurrencyUtils, 
  PhoneUtils, 
  ValidationUtils, 
  StringUtils,
  LocalStorageUtils,
  SessionStorageUtils,
  CookieUtils
} from 'utils-toolkit-alone';

// 使用特定模块
DateUtils.formatDate(new Date(), 'YYYY-MM-DD');
CurrencyUtils.formatCurrency(1234.56);
PhoneUtils.isValidMobile('13812345678');
ValidationUtils.isValidEmail('test@example.com');
ValidationUtils.validateLicensePlate('京A12345'); // 车牌验证
StringUtils.toUpperCase('hello');

// 使用存储模块
LocalStorageUtils.setItem('user', { name: 'John' });
SessionStorageUtils.setItem('temp', 'data');
CookieUtils.setCookie('session', 'abc123');
```

## TypeScript 支持

本库完全支持 TypeScript，包含完整的类型定义。

```typescript
import { formatDate, CurrencyFormatOptions } from 'utils-toolkit-alone';

const options: CurrencyFormatOptions = {
  symbol: '$',
  precision: 2
};
```

## 浏览器兼容性

- Chrome >= 60
- Firefox >= 60
- Safari >= 12
- Edge >= 79

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### 1.1.0
- 🆕 新增localStorage操作模块
  - 支持基础的增删改查操作
  - 支持对象自动序列化/反序列化
  - 支持数据加密存储
  - 支持过期时间管理
  - 支持批量操作
  - 支持存储空间监控
- 🆕 新增sessionStorage操作模块
  - 包含localStorage的所有功能
  - 支持与localStorage之间的数据迁移
  - 支持会话数据恢复
- 🆕 新增Cookie操作模块
  - 支持Cookie的设置、获取、删除
  - 支持Cookie选项配置（过期时间、路径、域名等）
  - 支持对象Cookie的序列化存储
  - 支持批量Cookie操作
  - 支持Cookie监听和解析
- 📝 完善文档和类型定义

### 1.0.2
- 新增车牌验证功能
- 支持中国车牌号验证、类型识别、省份解析
- 支持新能源车牌和传统车牌识别
- 简化验证规则，提高性能

### 1.0.1
- 优化代码结构
- 修复已知问题

### 1.0.0
- 初始版本发布
- 包含时间、金额、电话、校验、字符串处理功能