@dfsj/utils

v4.0.0-alpha.4

Published

6 days ago

通用的项目工具集

0High
0Medium
0Low

mr_geeker

zhou-qi-jun

utils vue3 ts

@dfsj/utils

通用工具函数库，提供加密、日期格式化、校验、DOM 操作、树结构处理等 25+ 模块的常用工具方法，按需引入，无冗余依赖

简介

@dfsj/utils 是 monorepo 的基础工具层，为其他包和业务应用提供类型判断、格式化、校验、加密、缓存、树操作等通用能力。所有模块支持 Tree-Shaking，不依赖任何框架，可在浏览器和 Node.js 环境中使用。

主要功能

| 模块 | 说明 | 主要导出 | |:-----|:-----|:---------| | is | 类型判断集合（50+ 方法） | isString, isNumber, isObject, isArray, isPromise, isUrl, isDef 等 | | format | 格式化工具集 | formatMobile, formatCamelCase, formatNumToUpper, formatThousandSeparator 等 | | validate | 校验规则 | isValidateMobile, isValidateEmail, isValidateIdCard, isEmptyValue 等 | | color | 颜色转换与处理 | hexToRgba, rgbaToHex, darken, lighten, mixColor, colorIsDark 等 | | dom | DOM 操作工具集 | addClass, removeClass, on, off, getViewportOffset, setCssVar 等 | | download | 文件下载 | downloadByOnlineUrl, downloadByBase64, downloadByData, downloadByUrl | | tree | 树结构操作（11 个方法） | listToTree, treeToList, findNode, findPath, treeFilter, treeForEach, treeMap | | encryption | 加密 / 签名 | AesEncryption, CryptoSM (SM2/SM4), CryptoRSA, HttpSignUtils, md5, sha256 | | cache | 本地缓存增强 | createStorage (localStorage/sessionStorage), Memory (内存缓存) | | object | 对象操作 | deepMerge, deepClone, pick, omit | | url | URL 工具 | openWindow, getUrlParam, setObjToUrlParams, getObjFormUrlParams | | mitt | 事件总线（基于 mitt 封装） | useMitt (on, off, emit, clear) | | diff | 数组差异计算 | diff (找出新增/删除/相同元素) | | base64 | Base64 编解码 | base64ToBlob, urlToBase64 | | uuid | UUID 生成器 | generateUUID | | bem | BEM 规范类名生成 | createBEM / useBEM | | slot | Vue Slot 工具函数 | getSlot, extendSlots | | getter | 属性动态获取 | getter, valueOf | | propTypes | Vue 组件 Props 类型扩展 | oneOfTypePlus 等增强类型定义 | | async | 异步工具 | sleep (延迟等待) | | random | 随机数生成 | randomInt | | browser | 浏览器环境检测 | isServer, isClient, isWindow | | localforage | IndexedDB 缓存 | LocalforageCache (基于 localforage 的持久化缓存) | | schedule | 任务调度 | NodeScheduleMission (基于 node-schedule 的定时任务) |

安装

pnpm add @dfsj/utils

快速开始

import {
  isString, isArray, isEmpty, isUrl,
  formatDateTime, formatMobile,
  isValidateMobile, isValidateEmail, isValidateIdCard,
  addClass, removeClass, on, off,
  downloadByOnlineUrl,
  listToTree, treeToList, findNode, treeFilter,
  md5, sha256, AesEncryption,
  hexToRgba, rgbaToHex,
} from '@dfsj/utils'

// 类型判断
if (isString(value) && !isEmpty(value)) { /* ... */ }

// 手机号格式化 → "138-1234-5678"
formatMobile(13812345678)

// 邮箱校验
isValidateEmail('[email protected]')

// 扁平数组转树形结构
listToTree(flatList, { id: 'id', pid: 'parentId' })

// 文件下载
downloadByOnlineUrl('https://example.com/file.pdf', 'report.pdf')

// 颜色转换
hexToRgba('#ff8800')  // "rgba(255,136,0,1)"

使用要求

| 环境 | 要求 | |:-----|:-----| | Node.js | >=18.12.0 | | TypeScript | >=5.0.0 | | 框架依赖 | Vue >=3.3（可选，仅 slot/mitt 模块依赖） |

开发指南

git clone http://10.10.12.18/dfsj/dfsj
pnpm install
cd packages/utils
pnpm watch

文档

许可证

MIT

@dfsj/utils

通用工具函数库 - 提供加密、日期格式化、校验、DOM 操作、树结构处理等 25+ 模块的常用工具方法，按需引入，无冗余依赖

✨ 功能特性

📦 安装

# pnpm
pnpm add @dfsj/utils

# npm
npm install @dfsj/utils

# yarn
yarn add @dfsj/utils

🚀 快速开始

// 基础导入
import {
  // 类型判断
  isString, isNumber, isArray, isEmpty, isUrl, isDef,
  
  // 格式化
  formatDateTime, formatMobile, formatCamelCase,
  
  // 校验
  isValidateMobile, isValidateEmail, isValidateIdCard,
  
  // DOM 操作
  addClass, removeClass, on, off,
  
  // 文件下载
  downloadFile, downloadByUrl,
  
  // 树操作
  listToTree, treeToList, findNode, treeFilter,

  // 加密
  md5, sha256, AesEncryption,

} from '@dfsj/utils'

// ========== 使用示例 ==========

// 1️⃣ 类型判断
if (isString(value) && !isEmpty(value)) {
  console.log('有效的字符串')
}

// 2️⃣ 手机号格式化
const formatted = formatMobile(13812345678)
// 输出: "138-1234-5678"

// 3️⃣ 邮箱校验
if (isValidateEmail('[email protected]')) {
  console.log('邮箱格式正确')
}

// 4️⃣ 身份证校验（含校验位验证）
const result = isValidateIdCard('110101199001011234')
console.log(result.valid, result.message)

// 5️⃣ 扁平数组转树形结构
const treeData = listToTree(flatList, { id: 'id', pid: 'parentId', children: 'children' })

// 6️⃣ 文件下载
downloadByOnlineUrl('https://example.com/file.pdf', 'report.pdf')

// 7️⃣ MD5 加密
const hash = md5('hello world')

// 8️⃣ 颜色转换
const rgbaColor = hexToRgba('#ff8800')      // "rgba(255,136,0,1)"
const hexColor = rgbaToHex('rgba(255,128,0,0.5)')  // "#ff800080"

📖 完整 API 文档

详细的使用说明、参数类型和更多示例，请查看各模块的独立文档：

| 模块 | 文档链接 | 说明 | |:-----|:---------|:-----| | 通用工具 | common.md | deepMerge, openWindow, getUrlParam 等 | | 类型判断 | is.md | 50+ 类型判断方法 | | 格式化 | format.md | 手机号、金额大写、千分位等 | | 校验规则 | validate.md | 手机号/邮箱/身份证/密码等 | | 颜色处理 | color.md | HEX↔RGBA转换、颜色混合等 | | DOM 操作 | dom.md | class操作、事件绑定、CSS变量等 | | 文件下载 | download.md | 在线文件/Base64/数据流下载 | | 树操作 | tree.md | 列表转树、查找节点、过滤遍历等 | | 加密签名 | encryption.md | AES/SM2/SM4/RSA/MD5/SHA256 | | 本地缓存 | cache.md | localStorage/sessionStorage/Memory | | 差异计算 | diff.md | 数组差异对比 | | 事件总线 | mitt.md | 发布订阅模式事件管理 | | BEM 规范 | bem.md | CSS BEM 类名生成 | | 浏览器检测 | browser.md | 运行环境判断 | | 任务调度 | schedule.md | Node 定时任务 | | UUID | uuid.md | 唯一标识符生成 | | Base64 | file.md | Base64 编解码转换 | | PropTypes | propTypes.md | Vue Props 类型扩展 |

🔧 开发指南

环境要求

| 环境 | 版本要求 | |:-----|:---------| | Node.js | >= 18.12.0 | | TypeScript | >= 5.0.0 | | 框架依赖 | Vue >= 3.3 (可选，仅 slot/mitt 模块依赖) |

项目结构

packages/utils/
├── src/                    # 源代码目录
│   ├── index.ts           # 主入口（导出所有模块）
│   ├── is.ts              # 类型判断
│   ├── format.ts          # 格式化
│   ├── validate.ts        # 校验规则
│   ├── color.ts           # 颜色转换
│   ├── dom.ts             # DOM 操作
│   ├── download.ts        # 文件下载
│   ├── tree.ts            # 树结构
│   ├── object.ts          # 对象操作
│   ├── url.ts             # URL 工具
│   ├── encryption/        # 加密模块（子目录）
│   │   ├── CryptoUtils.ts # AES 加密
│   │   ├── cryptoSM.ts    # 国密 SM2/SM4
│   │   ├── cryptoRSA.ts   # RSA 加密
│   │   └── httpSign.ts    # HTTP 签名
│   ├── cache/             # 缓存模块（子目录）
│   │   ├── memory.ts      # 内存缓存
│   │   └── storageCache.ts# 存储缓存
│   └── ...                # 其他模块
├── dist/                  # 编译输出目录
├── typings/               # 全局类型声明
└── __tests__/             # 测试目录

构建命令

# 开发模式（监听文件变化）
pnpm run watch

# 生产构建
pnpm run build

# 运行测试
pnpm test

📋 更新日志

查看完整的版本更新记录：CHANGELOG.md

最近更新 (v3.7.0)

2025-01-10:
- 新增 propTypes 模块（Vue Props 类型扩展）
- 新增 rgba/hex8 颜色转换函数
- 优化任务调度导出方式
- 修复 getter/diff 模块相关问题
- 新增 IndexedDB 缓存支持（LocalforageCache）

📄 许可证

MIT

💡 使用建议

::: tip 推荐做法

类型判断复杂场景：推荐使用 lodash-es 库进行数组、对象的高级判断和逻辑操作
加密敏感操作：建议在服务端处理关键加密逻辑，前端仅做基础加密
树操作大数据量：使用 treeForEach 时注意其提前终止机制，避免性能问题 :::

::: warning 注意事项

isNullAndUnDef 已标记为 deprecated，请使用 isNullOrUnDef
isValidateNull 已标记为 deprecated，请使用 isEmptyValue
部分 DOM 相关方法仅在浏览器环境中可用 :::

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@dfsj/utils

简介

主要功能

安装

快速开始

使用要求

开发指南

文档

许可证

@dfsj/utils

✨ 功能特性

📦 安装

🚀 快速开始

📖 完整 API 文档

🔧 开发指南

环境要求

项目结构

构建命令

📋 更新日志

最近更新 (v3.7.0)

📄 许可证

💡 使用建议