voya utils

项目简介

@voya-kit/utils：voya typeScript 开发工具集。本工具包汇总了一系列实用功能，覆盖了日期处理、颜色操作、数组与对象操作、类型检查、DOM操作、事件管理、本地存储管理、URL操作、唯一标识生成、格式解析、数据验证等多个方面。

安装

通过NPM安装 @voya-kit/utils：

npm install @voya-kit/utils --save

引入与使用

在你的TypeScript项目中，你可以按需导入所需的函数或整个工具包：

import { formatToDate, getItem, isEmail } from '@voya-kit/utils';

// 使用示例
const formattedDate = formatToDate(new Date(), 'yyyy-MM-dd');
const userData = await getItem('user-data-key');
const isValidEmail = isEmail('[email protected]');

主要功能概览

日期处理

| 函数名 | 功能描述 | |---------------------|-------------------------------------------------------------------------------------------------------------| | formatToDateTime | 将给定日期按照指定格式（默认：YYYY-MM-DD HH:mm:ss）格式化为字符串，利用dayjs库实现。 | | formatToDate | 将给定日期按照指定格式（默认：YYYY-MM-DD）格式化为字符串，采用dayjs库进行日期格式化。 | | calcTimeDiff | 计算两个时间戳之间相差的时、分、秒、天数，依据传入的diffType参数决定计算单位。 | | parseTime | 格式化时间字符串或时间戳为可读日期时间格式，支持自定义格式或预设的'date'格式。 | | getGMTOffset | 返回当前时区相对于GMT的偏移量，格式如GMT+0800或GMT-0500。 | | dateUtil | 导出dayjs实例，方便直接使用dayjs库的所有功能，如日期计算、比较等。 |

数据检查

| 函数名 | 功能描述 | |--------------------|-----------------------------------------------------------------------------------------------------------------| | is | 检查给定值的类型是否与指定的类型字符串相匹配，如Object、Array等，返回布尔值。 | | isDef | 判断给定值是否已定义（非undefined），返回布尔值。 | | isUnDef | 判断给定值是否未定义（undefined），返回布尔值。 | | isObject | 检查给定值是否为一个对象（非null），返回布尔值。 | | isEmpty | 检查给定值是否为空，适用于数组、字符串、对象(Map、Set)等，返回布尔值。 | | isDate | 判断给定值是否为Date对象，返回布尔值。 | | isNull | 判断给定值是否为null，返回布尔值。 | | isNullAndUnDef | 判断给定值是否为null或undefined，返回布尔值。 | | isNullOrUnDef | 判断给定值是否为null或undefined之一，返回布尔值。 | | isNumber | 检查给定值是否为数字类型，返回布尔值。 | | isPromise | 判断给定值是否为Promise对象，检查其类型及是否存在.then和.catch方法，返回布尔值。 | | isString | 检查给定值是否为字符串类型，返回布尔值。 | | isFunction | 判断给定值是否为函数类型，返回布尔值。 | | isBoolean | 检查给定值是否为布尔类型，返回布尔值。 | | isRegExp | 判断给定值是否为正则表达式对象，返回布尔值。 | | isArray | 检查给定值是否为数组类型，返回布尔值。 | | isWindow | 判断给定值是否为Window对象，在浏览器环境下有效，返回布尔值。 | | isElement | 检查给定值是否为DOM元素（具有tagName属性的对象），返回布尔值。 | | isMap | 判断给定值是否为Map对象，返回布尔值。 |

localstorage操作

| 函数名 | 功能描述 | |---------------|-----------------------------------------------------------| | CacheDays | 缓存过期天数常量，设置为7天。 | | checkLocalforage | 检查并清理过期缓存。根据cacheField检查本地存储中的项，如果存在且已过期（超过7天），则删除该项。 | | clearLocalforage | 清空所有本地存储中的数据。 | | getItem | 获取缓存数据或从服务器请求数据并缓存。接受请求函数request和缓存字段名cacheField，先检查缓存是否过期，如不过期则直接返回缓存数据；否则，调用request获取数据，并将新数据存入缓存。 | | setItem | 设置或更新缓存数据。接收数据列表list和缓存字段名cacheField，将数据连同当前时间戳存入本地存储。 |

颜色处理工具

| 函数名 | 功能描述 | |---------------------|-----------------------------------------------------------| | isHexColor | 判断给定字符串是否为十六进制颜色值，支持3位或6位格式。 | | rgbToHex | 将RGB颜色值转换为十六进制颜色表示，输入为r, g, b三个0-255的整数。 | | hexToRGB | 将十六进制颜色值转换为RGB表示，返回格式为"RGB(r,g,b)"字符串。 | | colorIsDark | 判断十六进制颜色是否较暗，基于颜色的亮度计算。 | | darken | 使十六进制颜色变暗，根据给定的百分比减少亮度。 | | lighten | 使十六进制颜色变亮，根据给定的百分比增加亮度。 | | addLight | 向十六进制颜色的单个RGB分量添加亮度值，辅助函数。 | | luminanace | 计算RGB颜色的亮度值，用于对比度计算。 | | contrast | 计算两个RGB颜色之间的对比度。 | | calculateBestTextColor | 根据背景颜色自动计算最佳的文字颜色（黑色或白色）。 | | subtractLight | 从十六进制颜色的单个RGB分量减去亮度值，辅助函数。 |

DOM节点处理工具

| 函数名 | 功能描述 | |---------------------|-----------------------------------------------------------| | getBoundingClientRect | 返回一个元素的边界信息（位置和尺寸）作为 DOMRect 对象，或在元素不存在时返回0。 | | hasClass | 检查元素是否包含指定的 CSS 类名。 | | addClass | 为元素添加一个或多个 CSS 类名。 | | removeClass | 从元素中移除一个或多个 CSS 类名。 | | getViewportOffset | 计算元素相对于视口的位置，并返回包含 left, top, right, bottom, rightIncludeBody, bottomIncludeBody 的对象。 | | hackCss | 生成一个兼容多浏览器前缀的 CSS 样式对象。 | | on | 给元素绑定事件监听器。 | | off | 移除元素上的事件监听器。 | | once | 为元素绑定只执行一次的事件监听器。 | | useRafThrottle | 使用 requestAnimationFrame 实现函数节流。 | | getSiblings | 获取给定元素的所有兄弟元素节点。 | | getSpecifySibling | 根据提供的选择器，获取元素的指定兄弟元素。 |

mitt事件总线

| 函数名 | 功能描述 | |--------------|-----------------------------------------------------------| | mitt | 创建一个轻量级的事件发射器（Emitter），支持注册、注销和触发事件，包括通配符支持。 | | mitt.on | 注册事件处理器，针对特定事件类型或通配符'*'注册处理器。 | | mitt.off | 移除事件处理器，可针对特定事件类型及处理器或通配符处理器进行移除。 | | mitt.emit | 触发指定类型的事件，传递事件数据给所有注册该类型或通配符的处理器。 | | mitt.clear | 清除所有已注册的事件处理器。 |

代码示例：

/**
 * 用于监听页面切换
 */

import { mitt } from '@voya-kit/utils';

const emitter = mitt();

enum emitEnum {
  DTL = 'detail-to-list',
  LTD = 'list-to-detail',
  PL = 'page-leave',
}

const DTLKey = Symbol(emitEnum.DTL);

export const DetailToListChangeEvent = {
  emitDetailToList(fullPath: string) {
    emitter.emit(DTLKey, fullPath);
  },
  listenerDetailToList(callback?: (fullPath: string) => void) {
    emitter.on(DTLKey, callback);
  },
  offDetailToList() {
    emitter.off(DTLKey);
  },
};

URL路径处理工具

| 函数名 | 功能描述 | |----------------|-----------------------------------------------------------| | checkURLParameter | 检查并从URL中提取指定的查询参数值。如果参数存在，则返回其值；否则，返回空字符串。 | | removeUrlParam | 从当前页面URL中移除指定的查询参数，并更新浏览器地址栏的URL，不产生浏览历史记录。 |

随机ID生成工具

| 函数名 | 功能描述 | |----------------|-----------------------------------------------------------| | buildUUID | 生成符合UUID格式的字符串，包含32个16进制数字，分为5组，分别由短横线连接。 | | buildShortUUID| 生成简化的唯一ID字符串，包含时间戳、随机数和递增的唯一计数器，可附加前缀。 |

数值转换工具

| 函数/对象名 | 功能描述 | |---------------------|-----------------------------------------------------------| | FormatParserType | 定义格式化解析器的类型，包含formatter用于格式化输出值，parser用于解析输入值。 | | FormatParserListType| 定义格式化解析器列表的类型，键为字符串，值为FormatParserType实例。 | | FormatParserList | 预定义的格式化解析器列表，含有THOUSANDS（千位分隔符）和PERCENTAGE（百分比显示）两种格式。 | | Uint8ArrayToString | 将Uint8Array数据转换为UTF-8编码的字符串。 | | getStompSubscribeMsg| 解析STOMP订阅消息，将接收到的Uint8Array数据转换为JSON对象。 |

校验工具

| 函数名 | 功能描述 | |--------------------|-----------------------------------------------------------| | isExternal | 判断给定路径是否为外部链接（HTTP/HTTPS、MAILTO、TEL或以//开头）。 | | isPassword | 检查密码字符串长度是否大于等于6位。 | | returnFixNumber | 返回固定位数的数字字符串，去除前导零，位数默认为2。 | | numberRemoveZero | 去除数字字符串后的零，返回处理后的数字。 | | toFixedNoZero | 四舍五入数字并转换为字符串，去除末尾的零，保留位数默认为2。 | | toFixed | 四舍五入数字到指定小数位，不足位数补零，返回格式化的字符串。 | | isName | 判断字符串是否符合姓名规则，包含中文、字母、数字。 | | isIP | 验证字符串是否为有效的IPv4地址格式。 | | isLowerCase | 检查字符串是否全为小写字母。 | | isUpperCase | 检查字符串是否全为大写字母。 | | isLetter | 检查字符串是否全部由字母组成（大小写均可）。 | | isAlphabets | 检查字符串是否以字母开头，包含大小写字母。 | | isPort | 验证字符串是否为有效的端口号（0-65535）。 | | isPhone | 验证字符串是否为中国手机号格式。 | | isIdCard | 验证字符串是否为有效的中国第二代身份证号码。 | | isEmail | 验证字符串是否为有效的电子邮件格式。 | | isChina | 检查字符串是否为2至4位的中文字符。 | | hasChina | 检查字符串中是否包含中文字符。 | | isBlank | 检查值是否为空（包括空字符串、null、undefined、"null"字符串）。 | | isEffectiveNumber | 判断字符串是否为非空且可以转换为有效数字。 | | isTel | 验证字符串是否符合固定电话号码格式。 | | isFloat | 判断字符串是否为浮点数格式。 | | isFloatByDigit | 判断字符串是否为最多包含指定小数位的数字（默认两位）。 | | isJson | 判断字符串是否可被解析为有效的JSON对象。 | | isBankCard | 检查字符串是否仅包含数字和减号，适用于银行账号。 | | isBankCode | 检查字符串是否仅包含数字和英文字母，适用于银行相关代码。 | | isHaveChineseChar | 检查字符串是否包含中文标点符号。 | | isImage | 验证文件路径或字符串是否为常见图片格式。 | | isExcel | 验证文件路径或字符串是否为Excel文件格式。 | | isDoc | 验证文件路径或字符串是否为Word文档格式。 | | isPdf | 验证文件路径或字符串是否为PDF格式。 | | isTxt | 验证文件路径或字符串是否为文本文件格式。 | | isPPT | 验证文件路径或字符串是否为PowerPoint文件格式。 | | canPreview | 判断文件路径或字符串所代表的文件类型是否可预览（图片、文档等）。 | | isServer | 判断当前环境是否为服务器端（无window对象）。 | | isClient | 判断当前环境是否为客户端（有window对象）。 | | isUrl | 验证字符串是否为合法的URL格式。 |