更新记录

2.0.1（2025-11-25） 下载此版本

2.0.0（2025-10-22） 下载此版本

[2.0.0] - 2025-10-22

1.0.0（2025-08-31） 下载此版本

• 初始版本发布
• 数据验证模块：isPhone, isEmail, isIdCard, isEmpty, isInRange
• 日期处理模块：formatDate, getRelativeTime, getDaysDiff
• 设备信息模块：getPlatform, isApp, isMiniProgram, isH5
• 字符串处理模块：randomString, maskString, capitalizeFirstLetter
• 业务工具模块：deepClone, debounce, throttle, formatMoney
• TypeScript 类型定义文件
• 完整使用文档

平台兼容性

uni-app(3.6.14)

uni-app x(3.6.14)

其他

hy-utils-plus

一个功能强大的 uni-app 工具函数库，包含11大模块，200+实用方法，支持多端使用。

✨ 特性

• 📦 11大模块：数据验证、日期处理、设备信息、字符串、数字、数组、树形数据、URL、颜色、文件、业务工具
• 🚀 200+方法：覆盖日常开发99%的工具函数需求
• 💪 TypeScript支持：完整的类型定义
• 🎯 多端兼容：支持H5、小程序、APP等多个平台
• 📝 详细文档：每个方法都有详细注释和示例
• 🔧 按需引入：支持全量引入和按需引入

📦 安装

方式一：通过 HBuilderX 插件市场安装

1. 在 插件市场 搜索 hy-utils-plus
2. 点击"使用 HBuilderX 导入插件"

方式二：手动安装

1. 将 uni_modules 文件夹下的 hy-utils-plus 目录拷贝到你的项目 uni_modules 目录下
2. 重新运行项目

🚀 快速开始

全量引入（推荐）

import Utils from '@/uni_modules/hy-utils-plus/js_sdk/index.js';

// 使用示例
console.log(Utils.validate.isPhone('***')); // true
console.log(Utils.date.formatDate(new Date())); // 2025-10-22 10:30:45
console.log(Utils.string.uuid()); // a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

按需引入

import { validate, date, string } from '@/uni_modules/hy-utils-plus/js_sdk/index.js';

// 或直接引入具体文件
import { isPhone, isEmail } from '@/uni_modules/hy-utils-plus/js_sdk/modules/validate.js';

挂载到全局（可选）

// main.js
import Utils from '@/uni_modules/hy-utils-plus/js_sdk/index.js';

// Vue2
Vue.prototype.$utils = Utils;

// Vue3
app.config.globalProperties.$utils = Utils;

// 使用
this.$utils.validate.isPhone('***');

TypeScript 支持

本插件完全支持 TypeScript，提供了完整的类型定义文件。

// TypeScript 项目中使用
import Utils from '@/uni_modules/hy-utils-plus/js_sdk/index';

// 所有方法都有完整的类型提示和智能补全
const isValid: boolean = Utils.validate.isPhone('***');
const formatted: string = Utils.date.formatDate(new Date());

// 泛型类型自动推断
interface User {
  id: number;
  name: string;
}

const users: User[] = [...];
const uniqueUsers = Utils.array.unique(users); // 类型自动推断为 User[]

更多 TypeScript 使用示例，请查看 TYPESCRIPT.md

📚 API 文档

1. 数据验证模块 (validate)

提供30+种常用验证方法：

// 基础验证
Utils.validate.isPhone('***')          // 手机号
Utils.validate.isTel('010-12345678')          // 座机号
Utils.validate.isEmail('test@example.com')    // 邮箱
Utils.validate.isUrl('https://example.com')   // URL地址
Utils.validate.isIPv4('192.168.1.1')         // IP地址

// 证件验证
Utils.validate.isIdCard('110101199001011234')        // 身份证（简单）
Utils.validate.isIdCardStrict('110101199001011234')  // 身份证（严格，含校验位）
Utils.validate.isBankCard('6222021234567890123')     // 银行卡（Luhn算法）
Utils.validate.isCarPlate('京A12345')                 // 车牌号
Utils.validate.isPassport('E12345678')               // 护照号

// 姓名验证
Utils.validate.isChineseName('张三')          // 中文姓名
Utils.validate.isEnglishName('John Smith')   // 英文姓名

// 密码验证
Utils.validate.isStrongPassword('Abc@123456')   // 强密码（8位+大小写+数字+特殊字符）
Utils.validate.isMediumPassword('Abc123456')    // 中等密码（6位+字母+数字）

// 数字验证
Utils.validate.isNumber('12345')                // 纯数字
Utils.validate.isPositiveInteger(123)           // 正整数
Utils.validate.isPositiveNumber(12.34)          // 正数
Utils.validate.isInRange(50, 0, 100)           // 数字范围

// 其他验证
Utils.validate.hasChinese('Hello你好')          // 包含中文
Utils.validate.hasEmoji('😀')                   // 包含emoji
Utils.validate.hasHtmlTag('<div>')             // 包含HTML标签
Utils.validate.isJSON('{"name":"test"}')       // JSON字符串
Utils.validate.isBase64('SGVsbG8=')            // Base64

2. 日期处理模块 (date)

提供30+种日期处理方法：

// 格式化
Utils.date.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')  // 2025-10-22 10:30:45
Utils.date.getRelativeTime(new Date())                     // 刚刚
Utils.date.formatCountdown('2025-12-31')                   // 70天12时30分15秒

// 判断
Utils.date.isToday(new Date())           // 是否今天
Utils.date.isYesterday(date)             // 是否昨天
Utils.date.isThisWeek(date)              // 是否本周
Utils.date.isLeapYear(2024)              // 是否闰年

// 获取信息
Utils.date.getWeekday(new Date(), true)  // 星期三
Utils.date.getQuarter(new Date())        // 4（第四季度）
Utils.date.getDayOfYear(new Date())      // 296（一年中的第几天）
Utils.date.getZodiacSign(new Date())     // 天秤座
Utils.date.getChineseZodiac(new Date())  // 蛇

// 时间操作
Utils.date.dateAdd(new Date(), 7, 'day')              // 加7天
Utils.date.getDaysDiff('2025-01-01', '2025-12-31')   // 364
Utils.date.getDateRange('week')                       // { start, end }

// 倒计时
Utils.date.countdown('2025-12-31')       // { days, hours, minutes, seconds, total }
Utils.date.formatDuration(3665)          // 01:01:05

3. 字符串处理模块 (string)

提供50+种字符串处理方法：

// 生成
Utils.string.randomString(16)            // 随机字符串
Utils.string.uuid()                      // UUID

// 脱敏
Utils.string.maskPhone('***')    // 138****8000
Utils.string.maskIdCard('110101199001011234')  // 110101********1234
Utils.string.maskBankCard('6222021234567890')  // 6222************7890

// 命名转换
Utils.string.camelToSnake('userName')    // user_name
Utils.string.snakeToCamel('user_name')   // userName
Utils.string.camelToKebab('userName')    // user-name
Utils.string.kebabToCamel('user-name')   // userName

// 大小写
Utils.string.capitalizeFirstLetter('hello')  // Hello
Utils.string.capitalizeWords('hello world')  // Hello World

// 截断
Utils.string.truncate('这是一段很长的文字', 10)              // 这是一段很长...
Utils.string.truncateByBytes('Hello世界', 10)             // Hello世...

// HTML处理
Utils.string.escapeHtml('<div>')         // &lt;div&gt;
Utils.string.stripHtmlTags('<p>文本</p>')  // 文本
Utils.string.highlightKeyword('搜索关键词', '关键')  // 搜索<span class="highlight">关键</span>词

// 提取
Utils.string.extractNumbers('价格123元')  // 123
Utils.string.extractChinese('Hello中国')  // 中国
Utils.string.extractLetters('价格123元')  // 

// 其他
Utils.string.removeEmoji('😀文本😀')      // 文本
Utils.string.byteLength('Hello世界')     // 11（中文按2字节计算）
Utils.string.similarity('kitten', 'sitting')  // 0.57（相似度）

4. 数字处理模块 (number)

提供40+种数字处理方法：

// 取整
Utils.number.round(3.456, 2)             // 3.46
Utils.number.ceil(3.14, 1)               // 3.2
Utils.number.floor(3.99, 1)              // 3.9

// 随机数
Utils.number.randomInt(1, 100)           // 随机整数
Utils.number.randomFloat(1.0, 10.0, 2)   // 随机小数

// 限制范围
Utils.number.clamp(150, 0, 100)          // 100

// 统计
Utils.number.sum(1, 2, 3, 4, 5)          // 15
Utils.number.average(1, 2, 3, 4, 5)      // 3
Utils.number.max(1, 2, 3, 4, 5)          // 5
Utils.number.min(1, 2, 3, 4, 5)          // 1

// 百分比
Utils.number.toPercent(0.25, 2)          // 25.00%
Utils.number.fromPercent('25%')          // 0.25

// 数字转换
Utils.number.toChinese(12345)            // 一万二千三百四十五
Utils.number.toChineseMoney(12345.67)    // 壹万贰仟叁佰肆拾伍元陆角柒分
Utils.number.toRoman(2024)               // MMXXIV
Utils.number.toHex(255)                  // FF

// 数学函数
Utils.number.factorial(5)                // 120
Utils.number.fibonacci(10)               // 55
Utils.number.gcd(48, 18)                 // 6（最大公约数）
Utils.number.lcm(12, 18)                 // 36（最小公倍数）

// 格式化
Utils.number.formatFileSize(1024000)     // 1000.00 KB
Utils.number.padZero(5, 3)               // 005

5. 数组处理模块 (array)

提供60+种数组处理方法：

// 去重
Utils.array.unique([1, 2, 2, 3])                    // [1, 2, 3]
Utils.array.uniqueBy(users, 'id')                   // 按id去重

// 集合运算
Utils.array.difference([1, 2, 3], [2, 3, 4])       // [1]
Utils.array.intersection([1, 2, 3], [2, 3, 4])     // [2, 3]
Utils.array.union([1, 2], [2, 3])                  // [1, 2, 3]

// 分组分块
Utils.array.groupBy(users, 'role')                 // 按角色分组
Utils.array.chunk([1, 2, 3, 4, 5], 2)             // [[1, 2], [3, 4], [5]]
Utils.array.partition(arr, x => x > 10)            // [[>10的], [<=10的]]

// 扁平化
Utils.array.flatten([[1, 2], [3, [4, 5]]])        // [1, 2, 3, 4, 5]

// 统计
Utils.array.sum([1, 2, 3, 4, 5])                  // 15
Utils.array.average([1, 2, 3, 4, 5])              // 3
Utils.array.max([1, 2, 3, 4, 5])                  // 5
Utils.array.count([1, 2, 2, 3], 2)                // 2

// 随机
Utils.array.shuffle([1, 2, 3, 4, 5])              // 随机打乱
Utils.array.sample([1, 2, 3, 4, 5], 2)            // 随机取2个

// 分页
Utils.array.paginate(arr, 1, 10)                  // { data, total, page, pageSize, totalPages }

// 树形转换
Utils.array.arrayToTree(flatData)                 // 扁平数组转树形
Utils.array.treeToArray(treeData)                 // 树形转扁平数组

// 提取
Utils.array.pluck(users, 'name')                  // ['张三', '李四']
Utils.array.toMap(users, 'id')                    // Map对象
Utils.array.toObject(users, 'id')                 // { '1': user1, '2': user2 }

// 其他
Utils.array.range(1, 10, 2)                       // [1, 3, 5, 7, 9]
Utils.array.fill(5, i => i * 2)                   // [0, 2, 4, 6, 8]
Utils.array.zip([1, 2], ['a', 'b'])              // [[1, 'a'], [2, 'b']]

6. 树形数据模块 (tree)

提供20+种树形数据处理方法：

// 转换
Utils.tree.arrayToTree(flatData, { idKey: 'id', parentIdKey: 'pid' })
Utils.tree.treeToArray(treeData)

// 查找
Utils.tree.findNode(tree, node => node.id === 5)
Utils.tree.findAllNodes(tree, node => node.type === 'folder')
Utils.tree.findPath(tree, node => node.id === 5)

// 遍历
Utils.tree.traverseDFS(tree, (node, level) => console.log(node))
Utils.tree.traverseBFS(tree, (node, level) => console.log(node))

// 操作
Utils.tree.filterTree(tree, node => node.visible)
Utils.tree.mapTree(tree, node => ({ ...node, label: node.name }))
Utils.tree.sortTree(tree, (a, b) => a.order - b.order)

// 增删改
Utils.tree.addNode(tree, parent => parent.id === 1, newNode)
Utils.tree.removeNode(tree, node => node.id === 5)
Utils.tree.updateNode(tree, node => node.id === 5, { name: '新名称' })

// 获取信息
Utils.tree.getTreeDepth(tree)                     // 树的深度
Utils.tree.getParents(tree, node => node.id === 5)  // 获取所有父节点
Utils.tree.getChildren(tree, node => node.id === 1) // 获取所有子节点
Utils.tree.getLeafNodes(tree)                     // 获取所有叶子节点
Utils.tree.countNodes(tree)                       // 统计节点数量

7. URL处理模块 (url)

提供20+种URL和路径处理方法：

// URL解析
Utils.url.parseUrl('https://example.com/path?a=1&b=2#hash')
// { protocol, host, pathname, search, hash, query: {a:1, b:2} }

// 查询参数
Utils.url.parseQuery('a=1&b=2')                   // { a: '1', b: '2' }
Utils.url.objectToQuery({ a: 1, b: 2 })          // 'a=1&b=2'
Utils.url.addQuery(url, { page: 2 })             // url?page=2
Utils.url.removeQuery(url, 'page', 'size')       // 移除参数
Utils.url.getQueryValue(url, 'page')             // '2'
Utils.url.getPageQuery('id')                     // 获取当前页面参数

// 路径操作
Utils.url.joinPath('/api', 'users', '123')       // /api/users/123
Utils.url.normalizePath('/a/b/../c/')            // /a/c
Utils.url.basename('/path/to/file.js')           // file.js
Utils.url.dirname('/path/to/file.js')            // /path/to
Utils.url.extname('file.js')                     // .js

// 判断
Utils.url.isUrl('https://example.com')           // true
Utils.url.isAbsoluteUrl('http://example.com')    // true
Utils.url.isAbsolutePath('/path/to/file')        // true

8. 颜色处理模块 (color)

提供15+种颜色处理方法：

// 颜色转换
Utils.color.hexToRgb('#FF5733')                  // { r: 255, g: 87, b: 51 }
Utils.color.rgbToHex(255, 87, 51)                // #FF5733
Utils.color.hexToRgba('#FF5733', 0.5)            // rgba(255, 87, 51, 0.5)
Utils.color.rgbToHsl(255, 87, 51)                // { h: 11, s: 100, l: 60 }
Utils.color.hslToRgb(11, 100, 60)                // { r: 255, g: 87, b: 51 }

// 颜色调整
Utils.color.lighten('#FF5733', 20)               // 变亮
Utils.color.darken('#FF5733', 20)                // 变暗
Utils.color.mix('#FF0000', '#0000FF', 0.5)       // 混合颜色

// 颜色生成
Utils.color.gradient('#FF0000', '#0000FF', 5)    // 生成渐变色数组
Utils.color.complement('#FF5733')                // 互补色
Utils.color.randomColor()                        // 随机颜色

// 颜色判断
Utils.color.isDark('#000000')                    // true
Utils.color.isLight('#FFFFFF')                   // true

// 颜色解析
Utils.color.parseColor('rgba(255, 87, 51, 0.5)') // { r, g, b, a }
Utils.color.formatColor('rgb(255, 87, 51)', 'hex')  // #FF5733

9. 文件处理模块 (file)

提供20+种文件处理方法：

// 文件信息
Utils.file.getExtension('file.txt')              // txt
Utils.file.getFilename('/path/to/file.txt')      // file
Utils.file.formatFileSize(1024000)               // 1000.00 KB
Utils.file.getMimeType('image.png')              // image/png

// 文件类型判断
Utils.file.isImage('photo.jpg')                  // true
Utils.file.isVideo('movie.mp4')                  // true
Utils.file.isAudio('music.mp3')                  // true
Utils.file.isDocument('report.pdf')              // true
Utils.file.isArchive('archive.zip')              // true

// 文件选择
await Utils.file.chooseImage({ count: 9 })       // 选择图片
await Utils.file.chooseVideo({ maxDuration: 60 }) // 选择视频
await Utils.file.chooseFile({ count: 1 })        // 选择文件

// 文件操作
await Utils.file.uploadFile(url, filePath)       // 上传文件
await Utils.file.downloadFile(url)               // 下载文件
await Utils.file.getFileInfo(filePath)           // 获取文件信息
await Utils.file.saveFile(tempFilePath)          // 保存文件
await Utils.file.removeFile(filePath)            // 删除文件

// 格式转换
await Utils.file.base64ToPath(base64Str)         // Base64转文件路径

10. 设备信息模块 (device)

提供40+种设备和环境相关方法：

// 平台判断
Utils.device.getPlatform()                       // 'h5' | 'weixin' | 'app-android' ...
Utils.device.isApp()                             // 是否APP
Utils.device.isAndroid()                         // 是否Android
Utils.device.isIOS()                             // 是否iOS
Utils.device.isMiniProgram()                     // 是否小程序
Utils.device.isH5()                              // 是否H5
Utils.device.isWeixinBrowser()                   // 是否微信浏览器
Utils.device.isMobile()                          // 是否移动设备

// 系统信息
Utils.device.getSystemInfo()                     // 获取系统信息
Utils.device.getScreenWidth()                    // 屏幕宽度
Utils.device.getScreenHeight()                   // 屏幕高度
Utils.device.getStatusBarHeight()                // 状态栏高度
Utils.device.getSafeArea()                       // 安全区域
Utils.device.isFullScreen()                      // 是否全面屏

// 单位转换
Utils.device.rpxToPx(750)                        // rpx转px
Utils.device.pxToRpx(375)                        // px转rpx

// 网络状态
await Utils.device.getNetworkType()              // 获取网络类型
await Utils.device.isOnline()                    // 是否联网
await Utils.device.isWifi()                      // 是否WiFi

// 设备功能
await Utils.device.getBatteryInfo()              // 电池信息
await Utils.device.getClipboardData()            // 获取剪贴板
await Utils.device.setClipboardData('复制内容')  // 设置剪贴板
await Utils.device.vibrateShort()                // 短震动
await Utils.device.makePhoneCall('10086')        // 拨打电话
await Utils.device.scanCode()                    // 扫码
await Utils.device.getLocation()                 // 获取位置

11. 业务工具模块 (business)

提供40+种常用业务方法：

// 对象操作
Utils.business.deepClone(obj)                    // 深度克隆
Utils.business.deepMerge(obj1, obj2)            // 深度合并
Utils.business.pick(obj, ['name', 'age'])       // 属性筛选
Utils.business.omit(obj, ['password'])          // 属性排除
Utils.business.get(obj, 'user.address.city')   // 获取深层属性
Utils.business.set(obj, 'user.name', '张三')   // 设置深层属性

// 函数工具
Utils.business.debounce(fn, 300)                // 防抖
Utils.business.throttle(fn, 300)                // 节流
await Utils.business.sleep(1000)                // 延迟
await Utils.business.retry(fn, 3, 1000)         // 重试

// 金额处理
Utils.business.formatMoney(1999)                // 19.99
Utils.business.formatMoneyWithComma(1000000)    // 1,000,000.00
Utils.business.yuanToCent(19.99)                // 1999

// 数字格式化
Utils.business.formatNumber(***)          // 1.23亿

// 数组工具（部分与array模块重复，保留兼容）
Utils.business.unique([1, 2, 2, 3])             // [1, 2, 3]
Utils.business.groupBy(arr, 'type')             // 分组
Utils.business.sortBy(arr, 'age', 'desc')       // 排序
Utils.business.shuffle([1, 2, 3])               // 随机打乱

// 本地存储
Utils.business.storage('key')                   // 获取
Utils.business.storage('key', value)            // 设置
Utils.business.storage('key', null)             // 删除
Utils.business.storageWithExpire('key', value, 3600000) // 带过期时间
Utils.business.clearStorage()                   // 清空
Utils.business.getStorageKeys()                 // 获取所有键

// URL工具
Utils.business.objectToQuery(obj)               // 对象转查询字符串
Utils.business.queryToObject(str)               // 查询字符串转对象

// 其他
Utils.business.range(1, 10, 2)                  // [1, 3, 5, 7, 9]
Utils.business.isEqual(obj1, obj2)              // 深度比较

💡 使用示例

表单验证

export default {
  data() {
    return {
      form: {
        phone: '',
        email: '',
        idCard: ''
      }
    }
  },
  methods: {
    validate() {
      const { validate } = this.$utils;

      if (!validate.isPhone(this.form.phone)) {
        return uni.showToast({ title: '手机号格式错误', icon: 'none' });
      }

      if (!validate.isEmail(this.form.email)) {
        return uni.showToast({ title: '邮箱格式错误', icon: 'none' });
      }

      if (!validate.isIdCard(this.form.idCard)) {
        return uni.showToast({ title: '身份证号格式错误', icon: 'none' });
      }

      // 提交表单
    }
  }
}

列表数据处理

import Utils from '@/uni_modules/hy-utils-plus/js_sdk/index.js';

export default {
  data() {
    return {
      list: [],
      filterType: 'all'
    }
  },
  computed: {
    // 分组显示
    groupedList() {
      return Utils.array.groupBy(this.list, 'category');
    },

    // 过滤+排序
    processedList() {
      let result = this.list;

      // 过滤
      if (this.filterType !== 'all') {
        result = result.filter(item => item.type === this.filterType);
      }

      // 排序
      result = Utils.business.sortBy(result, 'createTime', 'desc');

      return result;
    }
  }
}

树形菜单

import Utils from '@/uni_modules/hy-utils-plus/js_sdk/index.js';

export default {
  data() {
    return {
      flatMenus: [],
      treeMenus: []
    }
  },
  onLoad() {
    this.loadMenus();
  },
  methods: {
    async loadMenus() {
      const res = await this.$http.get('/api/menus');
      this.flatMenus = res.data;

      // 转换为树形结构
      this.treeMenus = Utils.tree.arrayToTree(this.flatMenus, {
        idKey: 'id',
        parentIdKey: 'parentId',
        rootValue: 0
      });
    },

    // 查找节点
    findMenu(id) {
      return Utils.tree.findNode(this.treeMenus, node => node.id === id);
    },

    // 获取面包屑路径
    getBreadcrumb(id) {
      const path = Utils.tree.findPath(this.treeMenus, node => node.id === id);
      return path ? path.map(node => node.name) : [];
    }
  }
}

📝 更新日志

详见 changelog.md

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT License

👨‍💻 作者

如有问题或建议，请在插件市场页面留言。