pit-docs-mcp 1.0.2

package/docs/pitBusinessUtils/utils.md

@@ -0,0 +1,762 @@
+# utils — 通用工具函数集合
+
+本模块是库中体量最大的工具集，涵盖时间格式化、URL 处理、字符串操作、DOM 类名操作、函数工具、文件下载、表格路由等多个类别，共约 30 个实用函数。
+
+## 引用方式
+
+```js
+import {
+  parseTime, formatTime, getQueryObject, param, param2Obj,
+  debounce, deepClone, downloadTemplate, formatFileSize,
+  handleRules, iterationArr, getPreviewUrl
+  // ... 更多按需引入
+} from 'pit-business-utils'
+```
+
+---
+
+## 一、时间格式化
+
+### `parseTime(time, cFormat)`
+
+全能时间解析与格式化，支持多种输入类型，对 Safari 的日期解析做了兼容处理。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `time` | `string \| number \| Object` | ✅ | 时间值，支持时间戳（秒/毫秒）、日期字符串、Date 对象 |
+| `cFormat` | `string` | — | 输出格式模板，默认 `"{y}-{m}-{d} {h}:{i}:{s}"`；占位符：`{y}`年、`{m}`月、`{d}`日、`{h}`时、`{i}`分、`{s}`秒、`{a}`星期 |
+
+| — | — |
+|---|---|
+| **返回值** | `string \| null`，格式化后的字符串；输入为空时返回 `null` |
+
+```js
+parseTime(1711036800000)                    // "2024-03-22 08:00:00"
+parseTime(1711036800, '{y}/{m}/{d}')        // "2024/03/22"（秒级时间戳自动 ×1000）
+parseTime('2024-03-22', '{y}年{m}月{d}日') // "2024年03月22日"
+parseTime(null)                             // null
+```
+
+---
+
+### `formatTime(time, option)`
+
+将时间戳转换为人性化的相对时间描述，适合消息列表、动态流等场景。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `time` | `number \| string` | ✅ | 毫秒时间戳 |
+| `option` | `string` | — | 超过一天时的自定义格式，传入则使用 `parseTime` 格式化，不传则显示 `"M月D日 H:i"` |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"刚刚"`、`"3分钟前"`、`"2小时前"`、`"1天前"`、`"03月22日 08:30"` |
+
+```js
+formatTime(Date.now() - 30 * 1000)          // "刚刚"
+formatTime(Date.now() - 5 * 60 * 1000)      // "5分钟前"
+formatTime(Date.now() - 25 * 3600 * 1000)   // "03月21日 08:00"
+```
+
+---
+
+### `handleDateStr(stamp)`
+
+将时间戳转为本地日期字符串 `yyyy-MM-dd HH:mm:ss`，兼容处理斜杠分隔问题。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `stamp` | `number \| string` | ✅ | 毫秒时间戳 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，格式 `yyyy-MM-dd HH:mm:ss` |
+
+```js
+handleDateStr(1711036800000) // "2024-03-22 08:00:00"
+```
+
+---
+
+## 二、URL 处理
+
+### `getQueryObject(url)`
+
+解析 URL 查询字符串为键值对对象。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | — | 待解析的 URL，默认为 `window.location.href` |
+
+| — | — |
+|---|---|
+| **返回值** | `Object`，键值对（值均为字符串类型） |
+
+```js
+getQueryObject('https://example.com?a=1&b=hello')
+// { a: '1', b: 'hello' }
+
+getQueryObject() // 解析当前页面 URL 参数
+```
+
+---
+
+### `param(json)`
+
+将对象序列化为 URL 查询字符串，值为 `undefined` 的属性会被跳过，值会进行 URL 编码。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `json` | `Object` | ✅ | 待序列化的键值对对象 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"name=%E5%BC%A0%E4%B8%89&age=28"` |
+
+```js
+param({ name: '张三', age: 28, empty: undefined })
+// "name=%E5%BC%A0%E4%B8%89&age=28"（undefined 被跳过）
+```
+
+---
+
+### `param2Obj(url)`
+
+将完整 URL 或查询字符串解析为对象，自动 decode 并将 `+` 替换为空格。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | ✅ | 完整 URL 或 `?` 开头的查询字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `Object` |
+
+```js
+param2Obj('https://example.com?name=John+Doe&age=28')
+// { name: 'John Doe', age: '28' }
+```
+
+---
+
+### `appendObjectToPath(path, object)`
+
+向路径字符串追加对象参数，用于构建带查询参数的 GET 请求 URL。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `path` | `string` | ✅ | 基础路径 |
+| `object` | `Object` | — | 需要追加的参数对象 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，拼接后的完整路径 |
+
+```js
+appendObjectToPath('/api/list', { page: 1, size: 10 })
+// "/api/list?page=1&size=10"
+```
+
+---
+
+## 三、字符串与数据处理
+
+### `byteLength(str)`
+
+计算字符串的 UTF-8 字节长度（中文等多字节字符各计为 3 字节）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `str` | `string` | ✅ | 待计算长度的字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `number`，UTF-8 字节长度 |
+
+```js
+byteLength('hello') // 5
+byteLength('你好')   // 6（每个汉字 3 字节）
+```
+
+---
+
+### `cleanArray(actual)`
+
+过滤数组中所有 falsy 值（`false`、`null`、`undefined`、`""`、`0`、`NaN`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `actual` | `Array` | ✅ | 原始数组 |
+
+| — | — |
+|---|---|
+| **返回值** | `Array`，过滤后的新数组 |
+
+```js
+cleanArray([1, null, 2, '', undefined, 3]) // [1, 2, 3]
+```
+
+---
+
+### `html2Text(val)`
+
+去除 HTML 标签，提取纯文本内容。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `val` | `string` | ✅ | 包含 HTML 标签的字符串 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，纯文本内容 |
+
+```js
+html2Text('<p>你好 <strong>世界</strong></p>') // "你好 世界"
+```
+
+---
+
+### `objectMerge(target, source)`
+
+深度合并两个对象或数组（数组直接浅拷贝替换，对象递归合并）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `target` | `Object \| Array` | ✅ | 目标对象 |
+| `source` | `Object \| Array` | ✅ | 源对象，其属性将合并到 target |
+
+| — | — |
+|---|---|
+| **返回值** | `Object \| Array`，合并后的新对象 |
+
+```js
+objectMerge({ a: 1, b: { x: 1 } }, { b: { y: 2 }, c: 3 })
+// { a: 1, b: { x: 1, y: 2 }, c: 3 }
+```
+
+---
+
+### `uniqueArr(arr)`
+
+数组去重（保留首次出现的元素）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `arr` | `Array` | ✅ | 原始数组 |
+
+| — | — |
+|---|---|
+| **返回值** | `Array`，去重后的新数组 |
+
+```js
+uniqueArr([1, 2, 2, 3, 1]) // [1, 2, 3]
+```
+
+---
+
+### `createUniqueString()`
+
+生成一个基于时间戳和随机数的唯一 ID 字符串（32 进制编码）。
+
+| — | — |
+|---|---|
+| **参数** | 无 |
+| **返回值** | `string`，唯一 ID |
+
+```js
+createUniqueString() // 如 "m8q3k1v7p2"
+```
+
+---
+
+### `amountThousandsConversion(number)`
+
+将数字格式化为千分位字符串（整数和小数部分分别处理）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `number` | `number \| string` | ✅ | 原始数字 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，千分位格式化后的字符串 |
+
+```js
+amountThousandsConversion(1234567.89) // "1,234,567.89"
+amountThousandsConversion(1000)       // "1,000"
+```
+
+---
+
+### `analyzeIDCard(IDCard)`
+
+通过 18 位身份证号码计算年龄。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `IDCard` | `string` | ✅ | 18 位居民身份证号码 |
+
+| — | — |
+|---|---|
+| **返回值** | `number \| ""`，计算得到的年龄；输入无效时返回 `""` |
+
+```js
+analyzeIDCard('110101199001011234') // 返回当前年龄（如 34）
+analyzeIDCard('invalid')           // ""
+```
+
+---
+
+## 四、DOM 类名操作
+
+### `hasClass(ele, cls)`
+
+判断元素是否包含指定类名。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `ele` | `HTMLElement` | ✅ | 目标 DOM 元素 |
+| `cls` | `string` | ✅ | 类名（不含 `.`） |
+
+| — | — |
+|---|---|
+| **返回值** | `boolean` |
+
+```js
+hasClass(document.getElementById('app'), 'active') // true / false
+```
+
+---
+
+### `addClass(ele, cls)`
+
+为元素添加类名（带错误保护）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `ele` | `Element` | ✅ | 目标 DOM 元素 |
+| `cls` | `string` | ✅ | 类名 |
+
+```js
+addClass(document.body, 'loading')
+```
+
+---
+
+### `removeClass(ele, cls)`
+
+从元素上移除指定类名。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `ele` | `Element` | ✅ | 目标 DOM 元素 |
+| `cls` | `string` | ✅ | 类名 |
+
+```js
+removeClass(document.body, 'loading')
+```
+
+---
+
+### `toggleClass(element, className)`
+
+切换元素的指定类名（有则移除，无则添加）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `element` | `Element` | ✅ | 目标 DOM 元素 |
+| `className` | `string` | ✅ | 类名 |
+
+```js
+toggleClass(menuEl, 'is-active')
+```
+
+---
+
+## 五、函数工具
+
+### `debounce(func, wait, immediate)`
+
+函数防抖，在 `wait` 毫秒内连续调用只执行最后一次（或第一次）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `func` | `Function` | ✅ | 需要防抖的函数 |
+| `wait` | `number` | ✅ | 防抖等待时间（毫秒） |
+| `immediate` | `boolean` | — | `true` 表示立即执行（首次触发立刻执行，后续等待），默认 `false` |
+
+| — | — |
+|---|---|
+| **返回值** | `Function`，防抖包装后的函数 |
+
+```js
+const lazySearch = debounce(() => fetchData(), 300)
+input.addEventListener('input', lazySearch)
+```
+
+---
+
+### `deepClone(source)`
+
+递归深克隆对象或数组，返回与原对象完全独立的新对象。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `source` | `Object \| Array` | ✅ | 原始对象（不支持传入 `null`） |
+
+| — | — |
+|---|---|
+| **返回值** | `Object \| Array`，深克隆后的新对象 |
+
+```js
+const original = { a: { b: 1 } }
+const copy = deepClone(original)
+copy.a.b = 99
+console.log(original.a.b) // 1（互不影响）
+```
+
+---
+
+### `iteration(node, cb, key)`
+
+递归遍历单个树节点及其所有子节点，对每个节点执行回调。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `node` | `Object` | ✅ | 树节点对象 |
+| `cb` | `Function(node)` | — | 每个节点的处理回调，默认无操作 |
+| `key` | `string` | — | 子节点列表的属性名，默认 `"children"` |
+
+```js
+iteration(treeNode, (node) => {
+  node.checked = false
+})
+```
+
+---
+
+### `iterationArr(nodeArr, cb, key)`
+
+递归遍历树节点数组，对所有节点执行回调。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeArr` | `Array` | ✅ | 树节点数组 |
+| `cb` | `Function(node)` | ✅ | 每个节点的处理回调 |
+| `key` | `string` | — | 子节点列表的属性名，默认 `"children"` |
+
+```js
+iterationArr(menuList, (node) => {
+  node.expanded = true
+})
+```
+
+---
+
+### `iterationArrEnd(nodeArr, cb, key)`
+
+带终止条件的树遍历：当回调返回 falsy 值时，停止递归该节点的子节点。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeArr` | `Array` | ✅ | 树节点数组 |
+| `cb` | `Function(node) => boolean` | ✅ | 回调返回 `true` 继续遍历子节点，返回 falsy 则停止 |
+| `key` | `string` | — | 子节点列表的属性名，默认 `"children"` |
+
+```js
+// 找到目标节点后停止深入
+iterationArrEnd(tree, (node) => {
+  if (node.id === targetId) { /* 处理 */ return false }
+  return true
+})
+```
+
+---
+
+### `treeToArray(list, newArr)`
+
+将树形数据结构展平为扁平数组，**会清空每个节点的 `children` 属性**。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `list` | `Array` | ✅ | 树形节点数组 |
+| `newArr` | `Array` | — | 累加器数组，默认为空数组 |
+
+| — | — |
+|---|---|
+| **返回值** | `Array`，扁平化的节点数组（节点无 `children` 字段） |
+
+> ⚠️ 该操作会修改原始节点的 `children` 属性（清空），若需保留原树结构，请先 `deepClone`。
+
+```js
+const flatList = treeToArray(treeData)
+```
+
+---
+
+## 六、文件操作
+
+### `downloadTemplate(res, fileName)`
+
+从接口响应的文件流（Blob）触发浏览器下载。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `res` | `Blob \| { data: Blob }` | ✅ | 接口返回的文件流数据，支持直接传 Blob 或含 `data` 属性的响应对象 |
+| `fileName` | `string` | — | 下载文件名，默认 `"导入模板"` |
+
+```js
+// 接口调用后直接传入 response
+const res = await exportApi()
+downloadTemplate(res, '用户数据导出')
+```
+
+---
+
+### `downloadTemplateAddType(res, fileName)`
+
+从接口响应触发下载，文件名和扩展名从响应头 `content-disposition` 自动提取。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `res` | `Object` | ✅ | 完整的 axios 响应对象（含 `headers` 和 `data`） |
+| `fileName` | `string` | — | 备用文件名（解析不到响应头时使用） |
+
+```js
+const res = await exportExcelApi()
+downloadTemplateAddType(res, '备用文件名')
+```
+
+---
+
+### `downloadUrlFile(url, fileName, type)`
+
+通过 XHR 方式下载指定 URL 的文件，兼容 IE 的 `msSaveBlob`。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | ✅ | 文件下载地址 |
+| `fileName` | `string` | ✅ | 下载后的文件名 |
+| `type` | `string` | — | MIME 类型，默认 `"text/csv"` |
+
+```js
+downloadUrlFile('https://example.com/file.xlsx', '报表.xlsx', 'application/vnd.ms-excel')
+```
+
+---
+
+### `downloadFileFromOss(fileIds, _this)`
+
+批量从 OSS 下载文件。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fileIds` | `string[]` | ✅ | OSS 文件 ID 数组 |
+| `_this` | `Object` | ✅ | Vue 组件实例（用于弹出 `$message` 提示） |
+
+```js
+downloadFileFromOss(['file-id-1', 'file-id-2'], this)
+```
+
+---
+
+### `fileType(format)`
+
+根据文件后缀名判断文件所属类型分类。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `format` | `string` | ✅ | 文件扩展名（如 `"pdf"`、`"mp4"`、`"jpg"`） |
+
+| — | — |
+|---|---|
+| **返回值** | `"bimModel" \| "document" \| "video" \| "image" \| ""`，若无法识别返回空字符串 |
+
+```js
+fileType('pdf')   // "document"
+fileType('mp4')   // "video"
+fileType('jpg')   // "image"
+fileType('rvt')   // "bimModel"
+fileType('xxx')   // ""
+```
+
+---
+
+### `formatFileSize(bytes)`
+
+将字节数转换为人性化文件大小字符串，支持到 TB 级别。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `bytes` | `number` | ✅ | 文件大小（字节数） |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，如 `"2.50 MB"`、`"1.00 GB"` |
+
+```js
+formatFileSize(2621440) // "2.50 MB"
+formatFileSize(1024)    // "1.00 KB"
+```
+
+---
+
+### `getPreviewUrl(config, type)`
+
+获取文件预览 URL，支持 `fileId` 模式（调用 OSS 接口）和 `stream` 模式（直接拼接 token）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `config` | `Object` | ✅ | 预览配置对象，`fileId` 模式需含 `fileId`，`stream` 模式需含 `previewUrl` |
+| `type` | `"fileId" \| "stream"` | — | 获取方式，默认 `"fileId"` |
+
+| — | — |
+|---|---|
+| **返回值** | `Promise<string>`，预览 URL |
+
+```js
+// fileId 模式：通过 OSS 接口获取预览链接
+const url = await getPreviewUrl({ fileId: 'xxx-yyy' }, 'fileId')
+
+// stream 模式：直接拼接 token
+const url = await getPreviewUrl({ previewUrl: '/preview/xxx' }, 'stream')
+```
+
+---
+
+## 七、表单 / 表格工具
+
+### `formatFloat(val, i, max, min, negative)`
+
+数字输入框格式化，清除非法字符，限制小数位数和数值范围，常用于金额/数量输入。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `val` | `string \| number` | ✅ | 用户输入值 |
+| `i` | `number` | — | 允许的最大小数位数 |
+| `max` | `number` | — | 最大值限制 |
+| `min` | `number` | — | 最小值限制 |
+| `negative` | `boolean` | — | 是否允许负数 |
+
+| — | — |
+|---|---|
+| **返回值** | `string`，处理后的合法数字字符串 |
+
+```js
+// 在 el-input 的 @input 事件中使用
+handleInput(val) {
+  this.form.amount = formatFloat(val, 2, 9999999, 0)
+}
+```
+
+---
+
+### `handleRules(obj, other)`
+
+快速生成 Element UI 表单的 `required` 必填校验规则对象，避免手写重复的 rules 配置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `obj` | `Object` | ✅ | `{ 字段名: '必填提示语' }` 的映射对象 |
+| `other` | `Object` | — | 需要合并的额外 rules（如带 validator 的自定义规则） |
+
+| — | — |
+|---|---|
+| **返回值** | `Object`，Element UI `rules` 格式的校验规则对象 |
+
+```js
+this.rules = handleRules({
+  name: '请输入姓名',
+  phone: '请输入手机号'
+}, {
+  phone: [{ validator: phoneValidator, trigger: 'blur' }]
+})
+```
+
+---
+
+### `filterColumns(columns, hasFlow, addIndex, approvalStatusObj, approvalStatus)`
+
+根据是否启用审批流程，动态向表格列配置中添加或移除「审批状态」列。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `columns` | `Array` | ✅ | el-table 列配置数组 |
+| `hasFlow` | `boolean` | ✅ | 是否启用流程 |
+| `addIndex` | `number` | — | 审批状态列的插入位置索引 |
+| `approvalStatusObj` | `Object` | — | 审批状态枚举映射对象 |
+| `approvalStatus` | `string` | — | 列的 `prop` 字段名，默认 `"approvalStatus"` |
+
+| — | — |
+|---|---|
+| **返回值** | `Array`，处理后的列配置数组 |
+
+```js
+const columns = filterColumns(this.baseColumns, this.hasFlow, 2, approvalStatusDict)
+```
+
+---
+
+## 八、路由跳转
+
+### `goToRouteWithThePlatform(url, target, cb, timer)`
+
+在同一系统内部进行路由跳转，自动识别 hash/history 路由模式。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | ✅ | 跳转的相对路径（如 `/dashboard`） |
+| `target` | `string` | — | 同 `window.open` 的第二个参数，如 `"_blank"` |
+| `cb` | `Function` | — | 跳转完成后的回调 |
+| `timer` | `number` | — | 回调延迟时间（毫秒），默认 `1000` |
+
+```js
+goToRouteWithThePlatform('/project/detail?id=123')
+goToRouteWithThePlatform('/report', '_blank')
+```
+
+---
+
+### `goToRouteOutThePlatform(url, target, cb)`
+
+跳转到外部系统（延时 1000ms 后执行 `window.open`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | ✅ | 目标 URL（支持绝对/相对路径） |
+| `target` | `string` | — | 如 `"_blank"`，默认在新标签页打开 |
+| `cb` | `Function` | — | 打开后的回调 |
+
+```js
+goToRouteOutThePlatform('https://other-system.com/login?token=xxx', '_blank')
+```
+
+---
+
+### `checkImgIsVaild(imgurl)`
+
+检测图片 URL 是否有效（能否正常加载）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `imgurl` | `string` | ✅ | 图片 URL 地址 |
+
+| — | — |
+|---|---|
+| **返回值** | `Promise<boolean>`，图片可正常加载返回 `true`，否则 `false` |
+
+```js
+const isValid = await checkImgIsVaild('https://example.com/avatar.jpg')
+if (!isValid) {
+  this.avatar = defaultAvatar
+}
+```
+
+---
+
+## 注意事项
+
+- `downloadFileFromOss` 依赖 `window._store`（Vuex store）读取 token，宿主项目需提前注入。
+- `getPreviewUrl` 的 `stream` 模式会从 `window._store` 读取用户 token 并拼接到 URL 中，请注意 URL 安全性。
+- `treeToArray` 会**直接修改**传入节点的 `children` 属性为空数组，如需保留原数据，请先使用 `deepClone` 克隆后再调用。
+- `debounce` 返回的函数 `this` 上下文遵循原函数，在 Vue 组件中使用时注意绑定 `this`。