js_ryl_v3 1.0.0

package/README.md

@@ -0,0 +1,775 @@
+# js_ryl_v3
+
+常用 JavaScript 工具函数集合，包含日期处理、数字运算、正则验证、Cookie 操作等。基于 TypeScript 开发，提供完整的类型声明。
+
+## 安装
+
+```bash
+npm install js_ryl_v3
+```
+
+## 使用
+
+```javascript
+// 按需引入
+import { cookie, time, reg, num } from 'js_ryl_v3';
+
+// 全量引入
+import * as utils from 'js_ryl_v3';
+```
+
+---
+
+## 方法列表
+
+### 1. cookie - Cookie 操作
+
+浏览器 Cookie 的增删改查操作。
+
+#### 方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `cookie.set(key, val, ops?)` | 设置 Cookie | `key: string` - Cookie名称<br>`val: string` - Cookie值<br>`ops?: CookieSetOptions` - 配置项 | `void` |
+| `cookie.get(name)` | 获取 Cookie | `name: string` - Cookie名称 | `string \| null` |
+| `cookie.remove(key, ops?)` | 删除 Cookie | `key: string` - Cookie名称<br>`ops?: CookieOptions` - 配置项 | `void` |
+
+#### CookieSetOptions 配置项
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `path` | `string` | Cookie 路径，默认当前路径 |
+| `domain` | `'domain' \| string` | Cookie 域名，传 `'domain'` 则自动设置为根域名 |
+| `expires` | `number \| Date` | 过期时间，10位时间戳或 Date 对象 |
+
+#### 示例
+
+```javascript
+import { cookie } from 'js_ryl_v3';
+
+// 设置Cookie
+cookie.set('token', 'abc123');
+cookie.set('user', 'zhangsan', { 
+  path: '/', 
+  domain: 'domain', 
+  expires: Date.now() + 7 * 24 * 3600 * 1000 
+});
+
+// 获取Cookie
+const token = cookie.get('token');
+
+// 删除Cookie
+cookie.remove('token');
+cookie.remove('user', { path: '/', domain: 'domain' });
+```
+
+---
+
+### 2. copy - 复制文本
+
+复制指定文本到剪贴板。
+
+#### 方法
+
+```typescript
+copy(content: string, callback: (result: CopyResult) => void): void
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `content` | `string` | 要复制的文本内容 |
+| `callback` | `(result: CopyResult) => void` | 复制完成后的回调 |
+
+#### CopyResult
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `code` | `number` | 状态码，200 成功，100 失败 |
+| `msg` | `string` | 状态信息 |
+
+#### 示例
+
+```javascript
+import { copy } from 'js_ryl_v3';
+
+copy('Hello World', (res) => {
+  if (res.code === 200) {
+    console.log('复制成功');
+  } else {
+    console.log('复制失败:', res.msg);
+  }
+});
+```
+
+---
+
+### 3. deepCopy - 深拷贝
+
+深拷贝对象或数组，支持 null、undefined、数组、普通对象。
+
+#### 方法
+
+```typescript
+deepCopy<T>(obj: T, tar?: Record<string, any>): T
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `obj` | `T` | 目标对象（拷贝结果会合并到此对象） |
+| `tar` | `Record<string, any>` | 要拷贝的源对象 |
+
+#### 示例
+
+```javascript
+import { deepCopy } from 'js_ryl_v3';
+
+const obj = { a: 1, b: { c: 2, d: [3, 4] } };
+const copyObj = deepCopy({}, obj);
+
+copyObj.b.c = 999;
+console.log(obj.b.c); // 2 - 原对象不受影响
+```
+
+---
+
+### 4. downExcel - 导出 Excel
+
+导出数据为 Excel 文件。
+
+#### 方法
+
+```typescript
+downExcel(data: ExcelData[], fileName?: string, sheetName?: string): void
+```
+
+#### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `data` | `ExcelData[]` | - | 要导出的数据数组 |
+| `fileName` | `string` | `'列表'` | 下载的文件名称（不含后缀） |
+| `sheetName` | `string` | `'Sheet1'` | 工作表名称 |
+
+#### 示例
+
+```javascript
+import { downExcel } from 'js_ryl_v3';
+
+const data = [
+  { 姓名: '张三', 年龄: 25, 城市: '北京' },
+  { 姓名: '李四', 年龄: 30, 城市: '上海' }
+];
+
+downExcel(data, '人员列表', '员工表');
+```
+
+---
+
+### 5. emoji - Unicode 转 Emoji
+
+将字符串中的 Unicode 编码转换为 Emoji 表情。
+
+支持格式：`U+xxxx`, `[u+xxxx]`, `\u{xxxx}`
+
+#### 方法
+
+```typescript
+emoji(str: string): string
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `str` | `string` | 包含 Unicode 编码的字符串 |
+
+#### 示例
+
+```javascript
+import { emoji } from 'js_ryl_v3';
+
+emoji('你好 U+1F600');       // '你好 😀'
+emoji('你好 [u+1f600]');     // '你好 😀'
+emoji('你好 \\u{1F600}');   // '你好 😀'
+```
+
+---
+
+### 6. emojiToUnicode - Emoji 转 Unicode
+
+将字符串中的 Emoji 表情转换为 Unicode 编码格式 `[u+xxxx]`。
+
+#### 方法
+
+```typescript
+emojiToUnicode(msg: string): string
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `msg` | `string` | 包含 Emoji 的字符串 |
+
+#### 示例
+
+```javascript
+import { emojiToUnicode } from 'js_ryl_v3';
+
+emojiToUnicode('你好😀世界🌍');
+// '你好[u+1f600]世界[u+1f30d]'
+```
+
+---
+
+### 7. filterTable - 表格空值过滤
+
+将表格数据中的空值、null、undefined 替换为指定占位符。
+
+#### 方法
+
+```typescript
+filterTable(data: TableData[], params?: string, more?: (string | undefined | null)[]): TableData[]
+```
+
+#### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `data` | `TableData[]` | - | 表格数据数组 |
+| `params` | `string` | `'--'` | 空值替换为的占位符 |
+| `more` | `(string \| undefined \| null)[]` | - | 额外需要替换为空的值 |
+
+#### 示例
+
+```javascript
+import { filterTable } from 'js_ryl_v3';
+
+const data = [
+  { name: '张三', age: 25, email: '' },
+  { name: null, age: undefined, email: 'test@test.com' }
+];
+
+const result = filterTable(data, '--');
+// [{ name: '张三', age: 25, email: '--' }, { name: '--', age: '--', email: 'test@test.com' }]
+
+// 自定义额外的空值
+const result2 = filterTable(data, '-', [0, false]);
+```
+
+---
+
+### 8. flyToCart - 飞入购物车动画
+
+实现商品图片飞入购物车的抛物线动画效果。
+
+#### 方法
+
+```typescript
+flyToCart(event: MouseEvent, image: string, targets: HTMLElement, callback?: () => void): void
+```
+
+#### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `event` | `MouseEvent` | - | 点击事件对象（起点位置） |
+| `image` | `string` | - | 飞行的图片 URL（可用 base64） |
+| `targets` | `HTMLElement` | - | 目标元素（购物车位置） |
+| `callback` | `() => void` | `() => {}` | 动画结束回调 |
+
+#### 示例
+
+```javascript
+import { flyToCart } from 'js_ryl_v3';
+
+document.getElementById('add-btn').addEventListener('click', (e) => {
+  const cart = document.getElementById('cart');
+  flyToCart(e, '/images/goods.jpg', cart, () => {
+    console.log('飞入完成');
+  });
+});
+```
+
+---
+
+### 9. fun - 节流 & 防抖
+
+函数节流和防抖工具。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `fun.throole(fn, delay?)` | 节流函数：规定时间内只让第一次触发生效 |
+| `fun.debounce(fn, delay?)` | 防抖函数：规定时间内只让最后一次触发生效 |
+
+#### 节流 (throole)
+
+```typescript
+fun.throole<T extends (...args: any[]) => any>(fn: T, delay?: number): ThrottleFunction<T>
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fn` | `Function` | - | 要节流的函数 |
+| `delay` | `number` | `500` | 节流时间（毫秒） |
+
+#### 防抖 (debounce)
+
+```typescript
+fun.debounce<T extends (...args: any[]) => any>(fn: T, delay?: number): DebounceFunction<T>
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fn` | `Function` | - | 要防抖的函数 |
+| `delay` | `number` | `500` | 防抖时间（毫秒） |
+
+#### 示例
+
+```javascript
+import { fun } from 'js_ryl_v3';
+
+// 节流 - 滚动事件
+const handleScroll = fun.throole(() => {
+  console.log('滚动事件触发');
+}, 300);
+window.addEventListener('scroll', handleScroll);
+
+// 防抖 - 搜索输入
+const handleSearch = fun.debounce((e) => {
+  console.log('搜索:', e.target.value);
+}, 500);
+input.addEventListener('input', handleSearch);
+```
+
+---
+
+### 10. getMonthDays - 获取月份天数
+
+获取指定年份中指定月份的天数。
+
+#### 方法
+
+```typescript
+getMonthDays(year: number, month: number): number
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `year` | `number` | 年份 |
+| `month` | `number` | 月份（1-12） |
+
+#### 示例
+
+```javascript
+import { getMonthDays } from 'js_ryl_v3';
+
+getMonthDays(2024, 2); // 29 - 闰年2月
+getMonthDays(2023, 2); // 28 - 平年2月
+getMonthDays(2024, 1); // 31 - 1月
+```
+
+---
+
+### 11. getParamsUtil - URL 参数处理
+
+URL 查询参数的解析、构建、合并、移除工具。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `getParamsUtil.getParam(name, url?, defaultValue?, type?)` | 获取单个参数 |
+| `getParamsUtil.getParams(url?)` | 获取所有参数 |
+| `getParamsUtil.buildQueryString(params)` | 构建查询字符串 |
+| `getParamsUtil.joinParams(url, params)` | 合并参数到 URL |
+| `getParamsUtil.removeParams(url, keys)` | 移除 URL 中的参数 |
+
+#### getParam
+
+```typescript
+getParam<T = any>(
+  name: string,
+  url?: string,
+  defaultValue?: T,
+  type?: 'string' | 'number' | 'boolean' | 'object'
+): T
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | 参数名 |
+| `url` | `string` | 指定 URL，默认当前页面 URL |
+| `defaultValue` | `any` | 默认值 |
+| `type` | `'string' \| 'number' \| 'boolean' \| 'object'` | 返回值类型 |
+
+#### getParams
+
+```typescript
+getParams(url?: string): ParamsObject
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | 指定 URL，默认当前页面 URL |
+
+#### buildQueryString
+
+```typescript
+buildQueryString(params: Record<string, any>): string
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `params` | `Record<string, any>` | 参数对象 |
+
+#### joinParams
+
+```typescript
+joinParams(url: string, params: Record<string, any>): string
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | 原始 URL |
+| `params` | `Record<string, any>` | 要合并的参数 |
+
+#### removeParams
+
+```typescript
+removeParams(url: string, keys: string | string[]): string
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | 原始 URL |
+| `keys` | `string \| string[]` | 要移除的参数名 |
+
+#### 示例
+
+```javascript
+import { getParamsUtil } from 'js_ryl_v3';
+
+// 获取所有参数
+const params = getParamsUtil.getParams('https://example.com?name=张三&age=25');
+// { name: '张三', age: '25' }
+
+// 获取单个参数
+const name = getParamsUtil.getParam('name');
+const age = getParamsUtil.getParam('age', undefined, 0, 'number');
+
+// 构建查询字符串
+const query = getParamsUtil.buildQueryString({ name: '张三', age: 25 });
+// 'name=%E5%BC%A0%E4%B8%89&age=25'
+
+// 合并参数
+const newUrl = getParamsUtil.joinParams('https://example.com?a=1', { b: 2, c: 3 });
+// 'https://example.com?a=1&b=2&c=3'
+
+// 移除参数
+const cleanUrl = getParamsUtil.removeParams('https://example.com?a=1&b=2&c=3', ['a', 'c']);
+// 'https://example.com?b=2'
+```
+
+---
+
+### 12. highlight - 搜索高亮
+
+将文本中匹配的关键词用高亮标签包裹。
+
+#### 方法
+
+```typescript
+highlight(searchName: string, backText: string, className: string): string
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `searchName` | `string` | 搜索关键词 |
+| `backText` | `string` | 原始文本 |
+| `className` | `string` | 高亮元素的 class 名 |
+
+#### 示例
+
+```javascript
+import { highlight } from 'js_ryl_v3';
+
+const result = highlight('测试', '这是一个测试文本', 'highlight');
+// '这是一个<span class="highlight">测试</span>文本'
+```
+
+```css
+.highlight {
+  background: yellow;
+  color: red;
+}
+```
+
+---
+
+### 13. num - 数字精度计算
+
+解决 JavaScript 浮点数加减乘除精度丢失问题。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `num.add(num1, num2)` | 加法 |
+| `num.sub(num1, num2)` | 减法 |
+| `num.mul(num1, num2)` | 乘法 |
+| `num.div(num1, num2)` | 除法 |
+| `num.NumFilter(v)` | 数字过滤（保留2位小数） |
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `num1` | `number \| string` | 第一个数字 |
+| `num2` | `number \| string` | 第二个数字 |
+
+#### 示例
+
+```javascript
+import { num } from 'js_ryl_v3';
+
+// 加法
+num.add(0.1, 0.2);    // 0.3 （普通运算结果: 0.30000000000000004）
+
+// 减法
+num.sub(1, 0.9);      // 0.1 （普通运算结果: 0.09999999999999998）
+
+// 乘法
+num.mul(0.1, 0.2);    // 0.02 （普通运算结果: 0.020000000000000004）
+
+// 除法
+num.div(1, 0.1);      // 10 （普通运算结果: 9.999999999999998）
+
+// 数字过滤
+num.NumFilter(1.234); // 1.23
+```
+
+---
+
+### 14. reg - 正则验证
+
+常用正则表达式验证。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `reg.Phone(value)` | 手机号验证 |
+| `reg.Email(value)` | 邮箱验证 |
+| `reg.IdCard(value)` | 身份证号验证 |
+| `reg.Common(value)` | 只能包含数字、字母、下划线 |
+| `reg.QQ(value)` | QQ号验证 |
+| `reg.Money(value)` | 金额验证 |
+| `reg.imgUrl(value)` | 是否为 base64 图片 |
+| `reg.verChinese(value)` | 是否包含中文 |
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `value` | `string` | 要验证的值 |
+
+#### 返回值
+
+`boolean` - `true` 验证通过，`false` 验证失败
+
+#### 示例
+
+```javascript
+import { reg } from 'js_ryl_v3';
+
+reg.Phone('13800138000');       // true
+reg.Email('test@example.com');  // true
+reg.IdCard('110101199001011234'); // true
+reg.Common('abc_123');          // true
+reg.QQ('123456');               // true
+reg.Money('123.45');            // true
+reg.imgUrl('data:image/png;base64,...'); // true
+reg.verChinese('你好');         // true
+```
+
+---
+
+### 15. time - 时间处理
+
+时间戳与日期格式转换、时间格式化工具。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `time.toDate(v, type?)` | 时间戳转日期 |
+| `time.toStamp(v?, len?)` | 日期转时间戳 |
+| `time.getNow()` | 获取当前时间 |
+| `time.timestampFormat(timestamp)` | 智能时间格式化 |
+
+#### toDate
+
+```typescript
+toDate(v: number | string, type?: DateFormatType): string
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `v` | `number \| string` | 时间戳（10位或13位） |
+| `type` | `DateFormatType` | 格式化类型 |
+
+DateFormatType 可选值：
+- `'yyyy-MM-dd'` - 年月日
+- `'yyyy-MM-dd HH:mm'` - 年月日 时:分
+- `'yyyy-MM-dd HH:mm:ss'` - 年月日 时:分:秒（默认）
+
+#### toStamp
+
+```typescript
+toStamp(v?: Date | string, len?: number): number
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `v` | `Date \| string` | `new Date()` | 日期字符串或 Date 对象 |
+| `len` | `number` | `10` | 返回时间戳位数（10或13） |
+
+#### timestampFormat
+
+```typescript
+timestampFormat(timestamp: number | string): string
+```
+
+智能格式化：
+- 今天 → `HH:mm`
+- 昨天 → `昨天 HH:mm`
+- 今年 → `MM/dd HH:mm`
+- 往年 → `yyyy/MM/dd HH:mm`
+
+#### 示例
+
+```javascript
+import { time } from 'js_ryl_v3';
+
+// 时间戳转日期
+time.toDate(1700000000);                   // '2023-11-14 13:33:20'
+time.toDate(1700000000, 'yyyy-MM-dd');     // '2023-11-14'
+time.toDate(1700000000, 'yyyy-MM-dd HH:mm'); // '2023-11-14 13:33'
+
+// 日期转时间戳
+time.toStamp('2023-11-14 13:33:20'); // 1700000000 (10位)
+time.toStamp('2023-11-14', 13);      // 13位时间戳
+
+// 获取当前时间
+time.getNow(); // '2024-01-01 12:00:00'
+
+// 智能格式化
+time.timestampFormat(Date.now() / 1000); // '12:00' (今天)
+```
+
+---
+
+### 16. verCode - 验证码倒计时
+
+手机验证码倒计时功能。
+
+#### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `verCode.PhoneCode(e, ss?, cc?)` | 开始倒计时 |
+| `verCode.PhoneCodeClear()` | 清除倒计时 |
+| `verCode.phoneCodeStatus()` | 获取倒计时状态 |
+
+#### PhoneCode
+
+```typescript
+PhoneCode(e: MouseEvent, ss?: number, cc?: string): void
+```
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `e` | `MouseEvent` | - | 点击事件对象 |
+| `ss` | `number` | `60` | 倒计时秒数 |
+| `cc` | `string` | `'后重新获取'` | 倒计时后缀文字 |
+
+#### 示例
+
+```javascript
+import { verCode } from 'js_ryl_v3';
+
+// HTML: <button id="code-btn">获取验证码</button>
+
+document.getElementById('code-btn').addEventListener('click', (e) => {
+  verCode.PhoneCode(e, 60, '秒后重新获取');
+});
+
+// 手动清除倒计时
+verCode.PhoneCodeClear();
+
+// 获取状态
+const isRunning = verCode.phoneCodeStatus(); // true/false
+```
+
+---
+
+### 17. base64Img - Base64 图片上传
+
+将 HTML 内容中的 base64 图片上传到服务器并替换为 URL。
+
+#### 方法
+
+```typescript
+base64Img(
+  content: string,
+  apiUrl: string,
+  token: string,
+  data?: Record<string, any>,
+  callback?: (original: string, error: string | Error) => void
+): Promise<string>
+```
+
+#### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `content` | `string` | 包含 base64 图片的 HTML 内容 |
+| `apiUrl` | `string` | 上传接口地址 |
+| `token` | `string` | 鉴权 token |
+| `data` | `Record<string, any>` | 额外上传参数 |
+| `callback` | `(original, error) => void` | 上传失败回调 |
+
+#### 返回值
+
+`Promise<string>` - 上传完成后替换好图片 URL 的 HTML 内容
+
+#### 示例
+
+```javascript
+import { base64Img } from 'js_ryl_v3';
+
+const htmlContent = '<img src="data:image/png;base64,...">';
+
+base64Img(htmlContent, '/api/upload', 'token123', { type: 'image' }, (original, err) => {
+  console.log('上传失败:', err);
+}).then(result => {
+  console.log('处理后的HTML:', result);
+});
+```
+
+---
+
+## License
+
+MIT