eoss 0.1.0-alpha.4 → 0.1.0-alpha.6

package/src/utils/util.js

@@ -13,14 +13,38 @@ import { formatDate } from './date';
 
 const publicKey = 'abcdefghijklmnopqrstuvwxyz12345678';
 
-export function noop() { };
+/**
+ * 空函数
+ * @desc 不执行任何操作的空函数
+ * @return {undefined}
+ **/
+export const noop = () => {};
 
-export function hasOwn(obj, key) {
+/**
+ * 检查对象是否拥有指定属性
+ * @desc 检查对象自身是否包含指定的属性（不包括原型链上的属性）
+ * @param {Object} obj - 要检查的对象
+ * @param {string} key - 要检查的属性名
+ * @return {boolean} 是否拥有该属性
+ **/
+export const hasOwn = (obj, key) => {
+  if (!isObject(obj) && typeof obj !== 'object') {
+    return false;
+  }
   return hasOwnProperty.call(obj, key);
 };
 
-export function toObject(arr) {
+/**
+ * 将数组转换为对象
+ * @desc 将对象数组合并为一个对象
+ * @param {Array} [arr=[]] - 对象数组
+ * @return {Object} 合并后的对象
+ **/
+export const toObject = (arr = []) => {
   var res = {};
+  if (!Array.isArray(arr)) {
+    return res;
+  }
   for (let i = 0; i < arr.length; i++) {
     if (arr[i]) {
       extend(res, arr[i]);
@@ -29,6 +53,13 @@ export function toObject(arr) {
   return res;
 };
 
+/**
+ * 根据路径获取对象属性值
+ * @desc 根据点分隔的路径字符串获取对象中的属性值
+ * @param {Object} object - 源对象
+ * @param {string} prop - 属性路径（如 'a.b.c'）
+ * @return {*} 获取到的属性值，如果路径不存在则返回null
+ **/
 export const getValueByPath = function (object, prop) {
   if (Object.prototype.toString.call(object).toLowerCase() !== '[object object]') {
     return object;
@@ -50,7 +81,22 @@ export const getValueByPath = function (object, prop) {
   return result;
 };
 
-export function getPropByPath(obj, path, strict) {
+/**
+ * 获取属性路径信息
+ * @desc 获取对象属性路径的详细信息，包括父对象、属性名和属性值
+ * @param {Object} obj - 源对象
+ * @param {string} path - 属性路径（如 'a.b.c' 或 'a[0].b'）
+ * @param {boolean} [strict=false] - 是否严格模式，严格模式下路径不存在会抛出错误
+ * @return {Object} 包含父对象(o)、属性名(k)和属性值(v)的对象
+ **/
+export const getPropByPath = (obj, path, strict = false) => {
+  if (!isObject(obj) && typeof obj !== 'object') {
+    return { o: null, k: '', v: null };
+  }
+  if (!isString(path)) {
+    return { o: obj, k: '', v: null };
+  }
+
   let tempObj = obj;
   path = path.replace(/\[(\w+)\]/g, '.$1');
   path = path.replace(/^\./, '');
@@ -76,10 +122,22 @@ export function getPropByPath(obj, path, strict) {
   };
 };
 
+/**
+ * 生成随机ID
+ * @desc 生成一个1-9999之间的随机整数作为ID
+ * @return {number} 随机ID
+ **/
 export const generateId = function () {
   return Math.floor(Math.random() * 10000);
 };
 
+/**
+ * 检查两个数组是否值相等
+ * @desc 深度比较两个数组是否包含相同的元素（严格相等比较）
+ * @param {Array} a - 第一个数组
+ * @param {Array} b - 第二个数组
+ * @return {boolean} 数组是否值相等
+ **/
 export const valueEquals = (a, b) => {
   // see: https://stackoverflow.com/questions/3115982/how-to-check-if-two-arrays-are-equal-with-javascript
   if (a === b) return true;
@@ -92,10 +150,29 @@ export const valueEquals = (a, b) => {
   return true;
 };
 
+/**
+ * 转义正则表达式特殊字符
+ * @desc 将字符串中的正则表达式特殊字符转义，使其可以安全地用于正则表达式
+ * @param {*} [value=''] - 要转义的字符串
+ * @return {string} 转义后的字符串
+ **/
 export const escapeRegexpString = (value = '') => String(value).replace(/[|\\{}()[\]^$+*?.]/g, '\\$&');
 
 // TODO: use native Array.find, Array.findIndex when IE support is dropped
-export const arrayFindIndex = function (arr, pred) {
+/**
+ * 查找数组中符合条件的元素索引
+ * @desc 查找数组中第一个满足测试函数的元素的索引
+ * @param {Array} arr - 要查找的数组
+ * @param {Function} pred - 测试函数，返回true表示找到匹配元素
+ * @return {number} 找到的元素索引，未找到返回-1
+ **/
+export const arrayFindIndex = (arr, pred) => {
+  if (!Array.isArray(arr)) {
+    return -1;
+  }
+  if (typeof pred !== 'function') {
+    return -1;
+  }
   for (let i = 0; i !== arr.length; ++i) {
     if (pred(arr[i])) {
       return i;
@@ -104,12 +181,31 @@ export const arrayFindIndex = function (arr, pred) {
   return -1;
 };
 
-export const arrayFind = function (arr, pred) {
+/**
+ * 查找数组中符合条件的元素
+ * @desc 查找数组中第一个满足测试函数的元素
+ * @param {Array} arr - 要查找的数组
+ * @param {Function} pred - 测试函数，返回true表示找到匹配元素
+ * @return {*} 找到的元素，未找到返回undefined
+ **/
+export const arrayFind = (arr, pred) => {
+  if (!Array.isArray(arr)) {
+    return undefined;
+  }
+  if (typeof pred !== 'function') {
+    return undefined;
+  }
   const idx = arrayFindIndex(arr, pred);
   return idx !== -1 ? arr[idx] : undefined;
 };
 
 // coerce truthy value to array
+/**
+ * 将真值转换为数组
+ * @desc 如果输入是数组则直接返回，否则将真值包装为数组，假值返回空数组
+ * @param {*} val - 要转换的值
+ * @return {Array} 转换后的数组
+ **/
 export const coerceTruthyValueToArray = function (val) {
   if (Array.isArray(val)) {
     return val;
@@ -229,7 +325,7 @@ export function objToArray(obj) {
 // requestAnimationFrame 适配函数
 const raFrame =
   window.requestAnimationFrame ||
-  window.webkitRequestAnimationFrame ||
+  window['webkitRequestAnimationFrame'] ||
   function (callback) {
     return window.setTimeout(callback, 1000 / 60);
   };
@@ -265,7 +361,7 @@ export const requestAnimationFrame = raFrame;
  */
 export const cancelAnimationFrame =
   window.cancelAnimationFrame ||
-  window.webkitRequestAnimationFrame ||
+  window['webkitCancelAnimationFrame'] ||
   function (id) {
     window.clearTimeout(id);
   };
@@ -433,7 +529,8 @@ export function pager(data, page = 1, size = 10) {
 /**
  * getWinTop
  * @desc 获取同域的top窗口
- * @param {object} wind - window对象
+ * @param {object} [wind] - window对象
+ * @return {Window} 同域的top窗口
  **/
 export const getWinTop = function (wind) {
   wind = wind ? wind : window.__WUJIE_RAW_WINDOW__ ? window.__WUJIE_RAW_WINDOW__ : window;
@@ -581,28 +678,35 @@ export const getFileType = function (fileName) {
 
 /**
  * arrUnique
- * @desc:数组元素对象去重
+ * @desc 数组元素对象去重
  * @author huangbo
  * @date 2022年5月7日
- * @param {Object} [data] - 原始数组
+ * @param {Array} [data] - 原始数组
  * @param {String} [key] - 对象子元素的属性名
+ * @return {Array} 去重后的数组
  **/
 export const arrUnique = function (data, key) {
+  // 验证输入参数
+  if (!Array.isArray(data) || data.length === 0) return [];
+
   let newArr = [];
   if (key === undefined) {
-    data.sort();
-    newArr = [data[0]];
-    for (let i = 1; i < data.length; i++) {
-      if (data[i] !== newArr[newArr.length - 1]) {
-        newArr.push(data[i]);
+    // 对基本类型数组去重
+    const sortedData = [...data].sort(); // 避免修改原数组
+    newArr = [sortedData[0]];
+    for (let i = 1; i < sortedData.length; i++) {
+      if (sortedData[i] !== newArr[newArr.length - 1]) {
+        newArr.push(sortedData[i]);
       }
     }
   } else {
+    // 对对象数组按指定键去重
     let obj = {};
     for (let i = 0; i < data.length; i++) {
-      if (!obj[data[i][key]]) {
-        newArr.push(data[i]);
-        obj[data[i][key]] = true;
+      const item = data[i];
+      if (item && obj[item[key]] === undefined) {
+        newArr.push(item);
+        obj[item[key]] = true;
       }
     }
   }
@@ -618,16 +722,17 @@ export const arrUnique = function (data, key) {
  * @return {number} 数组中数字的平均值
  **/
 export const average = function (...numbers) {
-  // Ensure that all arguments are valid numbers
+  // 处理空参数情况
+  if (numbers.length === 0) return 0;
+
+  // 确保所有参数都是有效数字
   if (!numbers.every(Number.isFinite)) {
     throw new Error('Invalid input. Please provide valid numbers.');
   }
 
-  // Calculate the average of the numbers
+  // 计算平均值
   const sum = numbers.reduce((acc, num) => acc + num, 0);
-  const average = sum / numbers.length;
-
-  return average;
+  return sum / numbers.length;
 };
 
 /**
@@ -640,7 +745,9 @@ export const average = function (...numbers) {
  * @return {string} 格式化后的文件大小
  */
 export const formatFileSize = function (size, digits = 2) {
-  if (size === 0) return '';
+  // 验证输入参数
+  if (size === 0 || typeof size !== 'number' || isNaN(size)) return '';
+  if (typeof digits !== 'number' || isNaN(digits)) digits = 2;
 
   const k = 1024;
   const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
@@ -654,9 +761,10 @@ export const formatFileSize = function (size, digits = 2) {
 
 /**
  * browser
- * @desc:浏览器类型
+ * @desc 浏览器类型
  * @author huangbo
  * @date 2022年5月7日
+ * @return {string|undefined} 浏览器类型标识
  **/
 export const browser = function () {
   const reg = { ie: /msie/, moz: /gecko/, opera: /opera/, safari: /safari/ };
@@ -669,9 +777,14 @@ export const browser = function () {
 
 /**
  * busEmit
- * @desc:发送事件
+ * @desc 发送事件
  * @author huangbo
  * @date 2022年5月7日
+ * @param {Object} that - Vue实例或包含bus的对象
+ * @param {Object} options - 事件选项
+ * @param {string} options.method - 事件名称
+ * @param {Array|*} options.args - 事件参数
+ * @param {Object} [options.opener] - 窗口对象（用于跨窗口通信）
  **/
 export const busEmit = function (that, { method, args, opener }) {
   if (opener) {
@@ -706,6 +819,7 @@ export const busEmit = function (that, { method, args, opener }) {
  * chunkToChinese
  * @desc 将四位数的整数转换为中文大写
  * @param {number} chunk - 数字
+ * @return {string} 中文大写数字
  **/
 export const chunkToChinese = function chunkToChinese(chunk) {
 
@@ -745,7 +859,6 @@ export const chunkToChinese = function chunkToChinese(chunk) {
 
 /**
  * concatenate
- * @desc 指定连接符合并文本
  * @desc 使用指定的连接符合并文本字符串
  * @author SuTao
  * @date 2023年12月14日
@@ -767,11 +880,13 @@ export const concatenate = function (separator, ...strings) {
 
 /**
  * delUrlParam
- * @desc:删除url指定参数
+ * @desc 删除url指定参数
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - url地址
- * @param {String,Array} [key] - 参数名
+ * @param {Object} options - 参数选项
+ * @param {String} [options.url] - url地址
+ * @param {String|Array} [options.key] - 参数名
+ * @return {string} 删除参数后的url
  **/
 export const delUrlParam = function ({ url, key }) {
   let pUrl = '';
@@ -817,7 +932,7 @@ export const delUrlParam = function ({ url, key }) {
 
 /**
  * domEval
- * @desc:添加js内容
+ * @desc 添加js内容
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [code] - js内容
@@ -830,10 +945,10 @@ export const domEval = function (code) {
 
 /**
  * downloadFile
- * @desc:下载附件
+ * @desc 下载附件
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [code] - js内容
+ * @param {String} fileUrl - 文件下载地址
  **/
 export const downloadFile = function (fileUrl) {
   const link = document.createElement('a');
@@ -847,10 +962,11 @@ export const downloadFile = function (fileUrl) {
 
 /**
  * encode
- * @desc:加密
+ * @desc 加密
  * @author huangbo
  * @date 2022年5月7日
- * @param {string} [data] - 被加密的字符串
+ * @param {string} value - 被加密的字符串
+ * @return {string} 加密后的字符串
  **/
 export const encode = function (value) {
   let kleng = publicKey.length;
@@ -874,11 +990,11 @@ export const encode = function (value) {
 
 /**
  * decode
- * @desc:解密
+ * @desc 解密
  * @author huangbo
  * @date 2022年5月7日
- * @param {string} [value] - 被解密的加密字符串
- * @param {string} [key] - 私钥
+ * @param {string} value - 被解密的加密字符串
+ * @return {string} 解密后的字符串
  **/
 export const decode = function (value) {
   let kleng = publicKey.length;
@@ -905,11 +1021,14 @@ export const decode = function (value) {
 };
 
 /**
- * 排除属性
- * @desc:exclAttribute
+ * exclAttribute
+ * @desc 排除对象中的指定属性
  * @author huangbo
  * @date 2022年5月7日
- * @param {String/Array} [attrs] - 要排除的属性
+ * @param {Object} options - 参数选项
+ * @param {String|Array} [options.attrs='value'] - 要排除的属性
+ * @param {Object} options.data - 源对象
+ * @return {Object} 排除属性后的新对象
  **/
 // 用于缓存exclAttribute的结果
 const _exclAttributeCache = new Map();
@@ -954,8 +1073,9 @@ export const exclAttribute = ({ attrs = 'value', data }) => {
  * @desc 导出表格数据
  * @author huangbo
  * @date 2022年5月7日
- * @param {Object} [data] - 导出数据
- * @param {String} [name] - 文件名
+ * @param {Object} options - 参数选项
+ * @param {Object} options.data - 导出数据
+ * @param {String} [options.name] - 文件名
  **/
 export const exportXls = function ({ data, name }) {
   // 创建Blob对象
@@ -987,6 +1107,7 @@ export const exportXls = function ({ data, name }) {
  * @param {Boolean} [deep] - 是否深拷贝
  * @param {Object} [target] - 目标对象
  * @param {...Object} [source] - 源对象
+ * @return {Object} 拷贝后的对象
  **/
 export const extend = function () {
   // target目标对象 source源对象
@@ -1043,7 +1164,8 @@ export const extend = function () {
  * @desc 获取数据类型
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [obj] - 任意值
+ * @param {*} [obj] - 任意值
+ * @return {string} 数据类型
  **/
 export const getObjectType = function (obj) {
   return Object.prototype.toString.call(obj).replace(/\[object (.*)\]/, '$1').toLowerCase();
@@ -1054,25 +1176,44 @@ export const getObjectType = function (obj) {
  * @desc 获取URL参数
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - url地址
+ * @param {Object} options - 参数配置对象
+ * @param {String} [options.url] - url地址，可选
+ * @param {String} [options.name] - 参数名，可选
+ * @return {Object|string} 参数对象或指定参数值
  **/
-export const getParams = function (key, url) {
+export const getParams = function ({url, name} = {}) {
   let href = '';
   try {
     href = window.top.location.href;
   } catch (e) {
     href = window.location.href;
   }
+
   const paramStr = (url || href).split('?')[1] || '';
-  if (!paramStr) return '';
   const params = {};
-  paramStr.split('&').forEach((item) => {
-    const [k, value] = item.split('=');
-    if (k) {
-      params[decodeURIComponent(k)] = decodeURIComponent(value || '');
-    }
-  });
-  return key ? params[key] || '' : params;
+
+  if (paramStr) {
+    paramStr.split('&').forEach((item) => {
+      const [k, value] = item.split('=');
+      if (k) {
+        const decodedKey = decodeURIComponent(k);
+        const decodedValue = decodeURIComponent(value || '');
+
+        // 处理重复参数，保存为数组
+        if (params[decodedKey] !== undefined) {
+          if (!Array.isArray(params[decodedKey])) {
+            params[decodedKey] = [params[decodedKey]];
+          }
+          params[decodedKey].push(decodedValue);
+        } else {
+          params[decodedKey] = decodedValue;
+        }
+      }
+    });
+  }
+
+  return name ? params[name] || '' : params;
+
 };
 
 /**
@@ -1080,7 +1221,8 @@ export const getParams = function (key, url) {
  * @desc 获取并执行JS文件
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - 脚本地址
+ * @param {String} url - 脚本地址
+ * @return {Promise} Promise对象
  **/
 export const getScript = function (url) {
   return new Promise((resolve, reject) => {
@@ -1105,6 +1247,7 @@ export const getScript = function (url) {
  * @date 2022年5月7日
  * @param {Element} [el] - dom元素
  * @param {String} [style] - 样式名称
+ * @return {string} 样式值
  **/
 export const getStyle = function (el, style) {
   if (!el || !style) return '';
@@ -1129,6 +1272,7 @@ export const getStyle = function (el, style) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [type] - 类型
+ * @return {string} 转换后的类型文本
  **/
 export const getTypeName = function (type) {
   if (!type) return '';
@@ -1154,8 +1298,9 @@ export const getTypeName = function (type) {
  * @desc 处理数据获取值
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [obj] - 数据源
+ * @param {Object} [obj] - 数据源
  * @param {String} [key] - 键名，支持a.b.c形式
+ * @return {*} 获取的值
  **/
 export const getValues = function (obj, key) {
   if (!obj || !key) return obj;
@@ -1173,6 +1318,7 @@ export const getValues = function (obj, key) {
  * @desc 获取缩放比
  * @author huangbo
  * @date 2022年5月7日
+ * @return {number} 缩放比例
  **/
 export const getZoom = function () {
   // 获取当前页面的缩放比例
@@ -1203,6 +1349,7 @@ export const getZoom = function () {
  * @desc 获取同域top窗口
  * @author huangbo
  * @date 2022年5月7日
+ * @return {Window} 同域的top窗口
  **/
 export const getMyWinTop = function () {
   const win = window.__WUJIE_RAW_WINDOW__
@@ -1228,6 +1375,7 @@ export const getMyWinTop = function () {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 字符串
+ * @return {number} 字符个数（中文算2个，其他算1个）
  **/
 export const getLength = function (str) {
   if (!str) return 0;
@@ -1252,6 +1400,7 @@ export const getLength = function (str) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [url] - url地址
+ * @return {string} 更新时间戳后的url
  **/
 export const timestampUrl = function (url) {
   if (!url) return '';
@@ -1273,7 +1422,8 @@ export const timestampUrl = function (url) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 被检测字符串
- * @param {String} [chars] - 目标字符
+ * @param {String|Array} [chars] - 目标字符
+ * @return {boolean} 是否包含目标字符
  **/
 export const hasChars = function (str, chars) {
   if (!str || !chars) return false;
@@ -1295,8 +1445,9 @@ export const hasChars = function (str, chars) {
  * @desc 验证值是否相同
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [a] - 第一个值
- * @param {Any} [b] - 第二个值
+ * @param {*} [a] - 第一个值
+ * @param {*} [b] - 第二个值
+ * @return {boolean} 值是否相同
  **/
 export const identical = function (a, b) {
   // 如果是严格相等，直接返回
@@ -1340,7 +1491,8 @@ export const identical = function (a, b) {
  * @date 2022年5月7日
  * @param {Array} [arr] - 源数组
  * @param {String} [key] - 键名
- * @param {String} [value] - 键值
+ * @param {*} [value] - 键值
+ * @return {number} 数组下标，没找到返回-1
  **/
 export const indexOfObj = function (arr, key, value) {
   if (!Array.isArray(arr) || !key) return -1;
@@ -1357,7 +1509,8 @@ export const indexOfObj = function (arr, key, value) {
  * @desc 判断是否为空
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [value] - 任意值
+ * @param {*} [value] - 任意值
+ * @return {boolean} 是否为空
  **/
 export const isEmpty = function (value) {
   if (value === undefined || value === null) {
@@ -1380,7 +1533,8 @@ export const isEmpty = function (value) {
  * @desc 判断是否存在
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [value] - 任意值
+ * @param {*} [value] - 任意值
+ * @return {boolean} 是否存在
  **/
 export const isExist = function (value) {
   return value !== undefined && value !== null;
@@ -1391,7 +1545,8 @@ export const isExist = function (value) {
  * @desc 判断是否是函数
  * @author huangbo
  * @date 2022年5月7日
- * @param {Any} [value] - 任意值
+ * @param {*} [value] - 任意值
+ * @return {boolean} 是否是函数
  **/
 export const isFunction = function (value) {
   return typeof value === 'function';
@@ -1402,8 +1557,9 @@ export const isFunction = function (value) {
  * @desc 判断对象是否相等
  * @author huangbo
  * @date 2022年5月7日
- * @param {Object} [a] - 第一个对象
- * @param {Object} [b] - 第二个对象
+ * @param {*} [a] - 第一个值
+ * @param {*} [b] - 第二个值
+ * @return {boolean} 对象是否相等
  **/
 export const isObjectEqual = function (a, b) {
   // 如果两者严格相等，直接返回true
@@ -1461,22 +1617,15 @@ export const isObjectEqual = function (a, b) {
   return true;
 };
 
-/**
- * joinUrl
- * @desc:判断url地址是否以字符开头，没有则添加
- * @author huangbo
- * @date 2022年5月7日
- * @param {string} [reg] - 域名或者路径
- * @param {string/array} [url] - 地址
- * @param {boolean} [single] - 是否做js沙箱隔离
- **/
 /**
  * joinUrl
  * @desc 拼接路径
  * @author huangbo
  * @date 2022年5月7日
- * @param {string} [url] - 地址
- * @param {string/array} [reg] - 域名或者路径前缀
+ * @param {Object} options - 参数选项
+ * @param {string} options.url - 地址
+ * @param {string|array} options.reg - 域名或者路径前缀
+ * @return {string} 拼接后的url
  **/
 export const joinUrl = function ({ url, reg }) {
   // 类型检查
@@ -1526,7 +1675,7 @@ export const joinUrl = function ({ url, reg }) {
  * @desc 加载JS文件
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - JS文件地址
+ * @param {String} url - JS文件地址
  * @param {Function} [callback] - 回调函数
  **/
 export const loadJs = function (url, callback) {
@@ -1545,7 +1694,8 @@ export const loadJs = function (url, callback) {
  * @desc 加载动画
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [text] - 提示文本
+ * @param {String} [text='请求中...'] - 提示文本
+ * @return {Object} Loading实例
  **/
 export const loading = function (text = '请求中...') {
   return Loading.service({
@@ -1561,6 +1711,7 @@ export const loading = function (text = '请求中...') {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 字符串
+ * @return {string} 转换后的字符串
  **/
 export const lowerCase = function (str) {
   if (typeof str !== 'string') return str;
@@ -1573,6 +1724,7 @@ export const lowerCase = function (str) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Element} [el] - dom元素
+ * @return {boolean} 是否溢出
  **/
 export const overbrim = function (el) {
   if (!el) return false;
@@ -1603,6 +1755,7 @@ export const overbrim = function (el) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Object} [obj] - 源对象
+ * @return {string} URL参数字符串
  **/
 export const queryParams = function (obj) {
   if (!obj || typeof obj !== 'object') return '';
@@ -1629,6 +1782,7 @@ export const queryParams = function (obj) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Function} [callback] - 回调函数
+ * @return {Function} 移除监听器的函数
  **/
 export const receiveMessage = function (callback) {
   const handleMessage = function (event) {
@@ -1650,7 +1804,8 @@ export const receiveMessage = function (callback) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Number} [num] - 数字
- * @param {Number} [digits] - 小数位数
+ * @param {Number} [digits=2] - 小数位数
+ * @return {string} 补全后的数字字符串
  **/
 export const replenish = function (num, digits = 2) {
   if (typeof num !== 'number' || isNaN(num)) {
@@ -1666,6 +1821,7 @@ export const replenish = function (num, digits = 2) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Number} [num] - 金额
+ * @return {string} 人民币大写
  **/
 export const rmbToCapital = function (num) {
   // 检查输入是否为数字
@@ -1767,8 +1923,9 @@ export const setScale = function (scale) {
  * @desc 向iframe发送信息
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [id] - iframe元素id
- * @param {Object} [data] - 发送的数据
+ * @param {Object} options - 参数选项
+ * @param {String} options.id - iframe元素id
+ * @param {Object} options.data - 发送的数据
  **/
 export const sendMessage = function ({ id, data }) {
   const iframe = document.getElementById(id);
@@ -1789,7 +1946,7 @@ export const sendMessage = function ({ id, data }) {
  * @desc 设置浏览器图标
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - 图标URL
+ * @param {String} url - 图标URL
  **/
 export const setFavicon = function (url) {
   if (!url) {
@@ -1821,7 +1978,8 @@ export const setFavicon = function (url) {
  * @desc 求和
  * @author huangbo
  * @date 2022年5月7日
- * @param {...number} [numbers] - 数字
+ * @param {...number} numbers - 数字
+ * @return {number} 数字的总和
  **/
 export const sum = function (...numbers) {
   // 确保所有参数都是有效的数字
@@ -1839,6 +1997,7 @@ export const sum = function (...numbers) {
  * @date 2022年5月7日
  * @param {String} [str] - 源字符串
  * @param {String} [searchString] - 搜索字符串
+ * @return {boolean} 是否以指定字符开头
  **/
 export const startWith = function (str, searchString) {
   if (typeof str !== 'string' || typeof searchString !== 'string') {
@@ -1854,6 +2013,7 @@ export const startWith = function (str, searchString) {
  * @date 2022年5月7日
  * @param {String} [str] - 源字符串
  * @param {Number} [length] - 提取长度
+ * @return {string} 提取后的字符串
  **/
 export const takeLeft = function (str, length) {
   if (typeof str !== 'string' || typeof length !== 'number' || length < 0) {
@@ -1869,6 +2029,7 @@ export const takeLeft = function (str, length) {
  * @date 2022年5月7日
  * @param {String} [str] - 源字符串
  * @param {Number} [length] - 提取长度
+ * @return {string} 提取后的字符串
  **/
 export const takeRight = function (str, length) {
   if (typeof str !== 'string' || typeof length !== 'number' || length < 0) {
@@ -1883,6 +2044,7 @@ export const takeRight = function (str, length) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 源字符串
+ * @return {string} 删除空格后的字符串
  **/
 export const trimWhitespace = function (str) {
   if (typeof str !== 'string') {
@@ -1897,7 +2059,8 @@ export const trimWhitespace = function (str) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {Number} [num] - 浮点数
- * @param {Number} [digits] - 小数位数
+ * @param {Number} [digits=2] - 小数位数
+ * @return {number} 保留小数位后的数字
  **/
 export const toFixed = function (num, digits = 2) {
   if (typeof num !== 'number' || isNaN(num)) {
@@ -1913,6 +2076,7 @@ export const toFixed = function (num, digits = 2) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 函数字符串
+ * @return {Function|null} 转换后的函数或null
  **/
 export const toFunction = function (str) {
   if (typeof str !== 'string') {
@@ -1961,6 +2125,7 @@ export const updateTheme = function (color) {
  * @author huangbo
  * @date 2022年5月7日
  * @param {String} [str] - 字符串
+ * @return {string} 转换后的字符串
  **/
 export const upperType = function (str) {
   if (typeof str !== 'string') {
@@ -1974,25 +2139,40 @@ export const upperType = function (str) {
  * @desc 对象转url拼接参数
  * @author huangbo
  * @date 2022年5月7日
- * @param {String} [url] - 源url
- * @param {Object} [params] - 参数对象
+ * @param {String} [options.url] - 源url
+ * @param {Object} [options.params] - 参数对象
+ * @param {Boolean} [options.timestamp] - 是否添加时间戳
  **/
-export const urlJoinParams = function (url, params) {
+export const urlJoinParams = function ({url = '', params = {}, timestamp = false} = {}) {
   if (typeof url !== 'string') {
-    return url;
+    return '';
   }
-  if (!params || typeof params !== 'object') {
-    return url;
+  if (!url) {
+    return '';
+  }
+  // 处理URL中的锚点
+  let urlWithoutHash = url;
+  let hash = '';
+  const hashIndex = url.indexOf('#');
+  if (hashIndex > -1) {
+    urlWithoutHash = url.slice(0, hashIndex);
+    hash = url.slice(hashIndex);
+  }
+  // 复制参数对象以避免修改原对象
+  const paramsCopy = {...params};
+  // 添加时间戳
+  if (timestamp) {
+    paramsCopy._t = Date.now();
   }
   // 将参数对象转换为URL参数字符串
-  const queryString = queryParams(params);
+  const queryString = queryParams(paramsCopy);
   if (!queryString) {
     return url;
   }
   // 检查URL是否已经包含查询参数
-  const hasQuery = url.includes('?');
+  const hasQuery = urlWithoutHash.includes('?');
   // 拼接URL和查询参数
-  return `${url}${hasQuery ? '&' : '?'}${queryString}`;
+  return `${urlWithoutHash}${hasQuery ? '&' : '?'}${queryString}${hash}`;
 };
 
 /**