@hhfenpm/utils 1.0.1 → 1.0.3

package/README.md

@@ -11,46 +11,48 @@ npm install @hhfenpm/utils
 ## 使用
 
 ```javascript
-// 按需导入
-import { format_date, validatePhone, getSession } from "@hhfenpm/utils";
+// 按需导入（推荐使用驼峰命名）
+import { formatDate, validatePhone, getSession } from "@hhfenpm/utils";
 
 // 或导入整个模块
 import * as utils from "@hhfenpm/utils";
 ```
 
+**注意：** 本包导出的是驼峰命名（camelCase）的 API。如果您的项目需要向后兼容的下划线命名（如 `format_date`），请通过项目本地的 utils 层导入，这些层会提供向后兼容的别名。
+
 ## 功能模块
 
 ### 格式化 (format)
 
-- `format_date(timestamp, str)` - 日期格式化
+- `formatDate(timestamp, formatStr)` - 日期格式化
 - `formatDateMinute(timestamp)` - 日期时间格式化（精确到分钟）
-- `format_decimal(number, num, scale)` - 小数转百分比（数字）
-- `format_decimal_string(number, num, scale)` - 小数转百分比（字符串）
-- `format_money(number, num, scale)` - 金额格式化
-- `format_number(num)` - 数字格式化（千分位）
-- `create_guid()` - 创建唯一 ID
-- `arr_label(arr, props)` - 数组转标签对象
-- `arr_obj(arr, props)` - 数组转对象
-- `copy_content(content)` - 复制到剪贴板
-- `calculate_height(item, container)` - 计算高度
-- `formatTxt(text)` - 文字截断
-- `set_cursor(dom, start, end)` - 设置光标位置
-- `sleep(time)` - 同步 setTimeout
+- `formatDecimal(number, decimalPlaces, scale)` - 小数转百分比（数字）
+- `formatDecimalString(number, decimalPlaces, scale)` - 小数转百分比（字符串）
+- `formatMoney(number, decimalPlaces, scale)` - 金额格式化
+- `formatNumber(num)` - 数字格式化（千分位）
+- `createGuid()` - 创建唯一 ID
+- `arrToLabel(arr, props)` - 数组转标签对象
+- `arrToObj(arr, props)` - 数组转对象
+- `copyContent(content)` - 复制文本到剪贴板
+- `calculateHeight(itemId, containerId)` - 计算高度（判断元素高度是否超过容器）
+- `formatText(text, maxLength)` - 文字截断（超过指定长度显示...）
+- `setCursor(dom, start, end)` - 设置光标位置（用于contenteditable元素）
+- `sleep(time)` - 同步 setTimeout（Promise版本）
 - `detectZoom()` - 检测浏览器缩放比例
 - `findNodeOfTree(tree, id, keyMap)` - 递归查找树节点
-- `copyToClip(content, type)` - 复制到剪贴板（兼容版）
+- `copyToClip(content, type)` - 复制文本到剪贴板（兼容版）
 - `hidePhone(phone)` - 手机号脱敏
 - `escapeRegExp(string)` - 转义正则表达式特殊字符
 
 ### 验证 (validate)
 
-- `validateFieldAsync(prop, form)` - 基于 Promise 的表单字段验证
-- `validatePhone(rule, value, callback)` - 手机号验证
+- `validateFieldAsync(prop, form)` - 基于 Promise 的表单字段验证（避免回调地狱）
+- `validatePhone(rule, value, callback)` - 手机号验证规则
 - `isEmptyObj(obj)` - 判断对象是否为空
-- `isEqual(a, b)` - 深度相等比较
+- `isEqual(a, b)` - 深度比较两个值是否相等（不包含引用比较）
 - `isEmpty(value)` - 判断值是否为空
 - `getBrowserInfo()` - 获取浏览器信息
-- `isSupported()` - 检测是否支持媒体设备
+- `isSupported()` - 检测浏览器是否支持媒体设备（getUserMedia）
 - `validateMeaninglessConsecutiveSymbols(input)` - 校验无意义连续符号
 
 ### 缓存 (cache)
@@ -59,30 +61,31 @@ import * as utils from "@hhfenpm/utils";
   - `cache.set(key, data)` - 设置缓存
   - `cache.get(key)` - 获取缓存
   - `cache.clear(key)` - 清除缓存
-- `buildUniqueUrl(url, method, params, data)` - 构建唯一的 URL 键值
+- `buildUniqueUrl(url, method, params, data)` - 构建唯一的 URL 键值（用于请求缓存）
 
 ### Session 管理 (session)
 
-- `set_system_key(key)` - 设置系统标识
-- `get_system_key(key)` - 获取带系统标识的 key
+- `setSystemKey(key)` - 设置系统标识前缀
+- `getSystemKey(key)` - 获取带系统标识的 key
 - `setSession(session, key)` - 设置 localStorage 中的 session
 - `getSession(key)` - 获取 localStorage 中的 session
 - `removeSession(key)` - 移除 localStorage 中的 session
-- `extentSession(patch, key)` - 扩展 session 中的部分属性
+- `extendSession(patch, key)` - 扩展 session 中的部分属性（推荐使用）
+- `extentSession(patch, key)` - 扩展 session 中的部分属性（向后兼容，拼写错误但保留）
 - `setSessionStorage(session, key)` - 设置 sessionStorage
 - `getSessionStorage(key)` - 获取 sessionStorage
 - `removeSessionStorage(key)` - 移除 sessionStorage
 
 ### 图片 URL 处理 (imgUrl)
 
-- `getImgURL(url)` - 获取图片 URL
+- `getImgURL(url)` - 获取通用图片 URL
 - `getGaugeImgUrl(url)` - 获取量表图片 URL
-- `doctor_head_img(url)` - 获取医生头像 URL
+- `doctorHeadImg(url, defaultUrl)` - 获取医生头像 URL
 
 ### 设备检测 (device)
 
-- `isTablet()` - 检测是否为平板
-- `getDeviceType()` - 获取设备类型
+- `isTablet()` - 检测当前设备是否为平板
+- `getDeviceType()` - 获取设备类型（'desktop' | 'tablet' | 'mobile'）
 - `isTouchDevice()` - 检测是否为触摸设备
 - `getDeviceInfo()` - 获取设备信息
 
@@ -92,25 +95,27 @@ import * as utils from "@hhfenpm/utils";
 - `toQueryString(obj)` - 对象转查询字符串
 - `urlToJson(selfUrl)` - URL 转 JSON 对象
 - `getQueryString(name, url)` - 获取 URL 中的指定参数
-- `setUrl(json, originUrl)` - 设置 URL 参数
-- `get_url_params(url)` - 获取 URL 参数（兼容旧 API）
+- `setUrl(json, originUrl)` - 设置 URL 参数，返回新的 URL
+- `getUrlParams(url)` - 获取 URL 参数（简化版）
 
 ### 通用工具 (tools)
 
 - `convertMilliseconds(ms, secondsTo2decimal)` - 毫秒转时分秒
-- `myDebounce(fn, time)` - 防抖函数
-- `debounce(fn, delay)` - 防抖函数（兼容版）
+- `debounce(fn, delay)` - 防抖函数
+- `myDebounce(fn, delay)` - 防抖函数（别名，向后兼容）
 - `throttle(fn, delay)` - 节流函数
-- `mapStringifyReplacer(key, value)` - Map 序列化替换器
-- `mapParseReviver(key, value)` - Map 反序列化恢复器
-- `getHalfYearAgoToday(reduce)` - 获取 N 个月前的日期
+- `mapStringifyReplacer(key, value)` - Map 序列化替换器（用于 JSON.stringify）
+- `mapParseReviver(key, value)` - Map 反序列化恢复器（用于 JSON.parse）
+- `getHalfYearAgoToday(reduce)` - 获取 N 个月前的今天
 - `fileDownloadHelper` - 文件下载助手
-- `copyText(text)` - 复制文本到剪贴板
+  - `fileDownloadHelper.download(blob, filename)` - 下载文件
+  - `fileDownloadHelper.getFilenameFromHeaders(headers, defaultName)` - 从响应头获取文件名
+- `copyText(text)` - 复制文本到剪贴板（Promise版本）
 
 ### UUID 生成 (uuid)
 
 - `uuid()` - 生成短 UUID
-- `uuidLong()` - 生成长 UUID
+- `uuidLong()` - 生成长 UUID（由三个短UUID拼接）
 
 ### 对象属性获取 (get)
 
@@ -119,12 +124,28 @@ import * as utils from "@hhfenpm/utils";
 ### Axios 适配器 (defaultAdapter)
 
 - `defaultAdapter(options)` - 防止重复请求的适配器
+  - `options.cacheTime` - 缓存时间（毫秒），设置为0不清除缓存，默认0
+  - `options.cache` - 是否支持缓存，默认false
+  - `options.noWarn` - 是否禁用警告，默认false
+
+## 向后兼容说明
+
+本包导出的是标准的驼峰命名（camelCase）API。如果您需要向后兼容的下划线命名（如 `format_date`、`format_decimal` 等），请通过项目本地的 utils 层导入：
+
+```javascript
+// ✅ 推荐：通过项目 utils 层导入（提供向后兼容）
+import { format_date, format_decimal } from '@/utils/format'
+
+// ⚠️ 不推荐：直接导入 npm 包（只有驼峰命名）
+import { formatDate, formatDecimal } from '@hhfenpm/utils'
+```
 
 ## 注意事项
 
-1. **API 兼容性**：所有导出的函数名都保持与原业务代码中的命名一致（使用下划线命名），确保兼容旧 API。
+1. **API 命名**：本包使用标准的驼峰命名（camelCase）。向后兼容的下划线命名由项目本地的 utils 层提供。
 2. **依赖要求**：需要安装 `date-fns` 作为 peerDependency。
 3. **浏览器环境**：部分函数需要在浏览器环境中使用，在 Node.js 环境中会返回默认值或警告。
+4. **拼写说明**：`extentSession` 是历史遗留的拼写错误，建议使用 `extendSession`，但 `extentSession` 仍然可用以保持向后兼容。
 
 ## 开发