前端工具类

Vben Admin 提供了 20 个前端工具类，覆盖常见的业务场景。

工具类列表

工具类	说明	主要功能
ExportUtils	导出工具	Excel/CSV/JSON 导出
ClipboardUtils	剪贴板工具	复制文本/HTML/图片
EncryptUtils	加密工具	MD5/AES/SHA256/Base64
FullscreenUtils	全屏工具	进入/退出/切换全屏
WatermarkUtils	水印工具	添加水印、防删除
QRCodeUtils	二维码工具	生成、下载二维码
ValidationUtils	验证工具	前端数据验证
DesensitizeUtils	脱敏工具	前端数据脱敏
PrintUtils	打印工具	HTML 元素打印
DownloadUtils	下载工具	文件/Blob/Base64 下载
StorageUtils	存储工具	localStorage/sessionStorage
UrlUtils	URL 工具	参数解析/构建
FormatUtils	格式化工具	文件大小/数字/日期
DomUtils	DOM 工具	DOM 操作、滚动控制
TreeUtils	树形工具	数组转树、查找过滤
DeviceUtils	设备工具	移动端/浏览器判断
ColorUtils	颜色工具	颜色转换、加深变浅
ArrayUtils	数组工具	去重/分组/求和
ObjectUtils	对象工具	深拷贝/深度合并
FunctionUtils	函数工具	防抖/节流

ExportUtils

导出工具类，支持 Excel、CSV、JSON 格式。

导出 Excel

typescript

import { ExportUtils } from '@vben/utils'

// 基础导出
const data = [
  { name: '张三', age: 25, email: 'zhangsan@example.com' },
  { name: '李四', age: 30, email: 'lisi@example.com' },
]

ExportUtils.exportExcel(data, '用户列表')

自定义列

typescript

import { ExportUtils } from '@vben/utils'

const data = [
  { name: '张三', age: 25, email: 'zhangsan@example.com' },
  { name: '李四', age: 30, email: 'lisi@example.com' },
]

const columns = [
  { header: '姓名', key: 'name', width: 20 },
  { header: '年龄', key: 'age', width: 10 },
  { header: '邮箱', key: 'email', width: 30 },
]

ExportUtils.exportExcel(data, '用户列表', columns)

导出 CSV

typescript

import { ExportUtils } from '@vben/utils'

const data = [
  { name: '张三', age: 25 },
  { name: '李四', age: 30 },
]

ExportUtils.exportCSV(data, '用户列表')

导出 JSON

typescript

import { ExportUtils } from '@vben/utils'

const data = { users: [...], total: 100 }

ExportUtils.exportJSON(data, '用户数据')

ClipboardUtils

剪贴板工具类。

复制文本

typescript

import { ClipboardUtils } from '@vben/utils'

// 复制文本
await ClipboardUtils.copy('要复制的文本')

// 复制成功提示
await ClipboardUtils.copy('文本', {
  onSuccess: () => console.log('复制成功'),
  onError: (err) => console.error('复制失败', err)
})

复制 HTML

typescript

import { ClipboardUtils } from '@vben/utils'

const html = '<div><h1>标题</h1><p>内容</p></div>'
await ClipboardUtils.copyHTML(html)

复制图片

typescript

import { ClipboardUtils } from '@vben/utils'

const imageUrl = 'https://example.com/image.jpg'
await ClipboardUtils.copyImage(imageUrl)

读取剪贴板

typescript

import { ClipboardUtils } from '@vben/utils'

// 读取文本
const text = await ClipboardUtils.readText()

// 读取图片
const image = await ClipboardUtils.readImage()

EncryptUtils

加密工具类。

MD5 加密

typescript

import { EncryptUtils } from '@vben/utils'

const hash = EncryptUtils.md5('password123')
// 输出：482c811da5d5b4bc6d497ffa98491e38

AES 加密/解密

typescript

import { EncryptUtils } from '@vben/utils'

const key = 'my-secret-key'
const text = '敏感数据'

// 加密
const encrypted = EncryptUtils.aesEncrypt(text, key)

// 解密
const decrypted = EncryptUtils.aesDecrypt(encrypted, key)

SHA256 加密

typescript

import { EncryptUtils } from '@vben/utils'

const hash = EncryptUtils.sha256('password123')

Base64 编码/解码

typescript

import { EncryptUtils } from '@vben/utils'

// 编码
const encoded = EncryptUtils.base64Encode('Hello World')

// 解码
const decoded = EncryptUtils.base64Decode(encoded)

FullscreenUtils

全屏工具类。

进入全屏

typescript

import { FullscreenUtils } from '@vben/utils'

// 全屏整个页面
FullscreenUtils.enter()

// 全屏指定元素
const element = document.getElementById('container')
FullscreenUtils.enter(element)

退出全屏

typescript

import { FullscreenUtils } from '@vben/utils'

FullscreenUtils.exit()

切换全屏

typescript

import { FullscreenUtils } from '@vben/utils'

FullscreenUtils.toggle()

监听全屏变化

typescript

import { FullscreenUtils } from '@vben/utils'

FullscreenUtils.onChange((isFullscreen) => {
  console.log('全屏状态：', isFullscreen)
})

WatermarkUtils

水印工具类。

添加水印

typescript

import { WatermarkUtils } from '@vben/utils'

WatermarkUtils.add({
  text: '内部资料',
  fontSize: 16,
  color: 'rgba(0, 0, 0, 0.15)',
  rotate: -20,
  zIndex: 9999
})

自定义水印

typescript

import { WatermarkUtils } from '@vben/utils'

WatermarkUtils.add({
  text: '机密文件',
  fontSize: 20,
  color: 'rgba(255, 0, 0, 0.2)',
  rotate: -30,
  width: 300,
  height: 200,
  x: 50,
  y: 50
})

移除水印

typescript

import { WatermarkUtils } from '@vben/utils'

WatermarkUtils.remove()

防删除水印

typescript

import { WatermarkUtils } from '@vben/utils'

// 启用防删除保护
WatermarkUtils.add({
  text: '内部资料',
  preventDelete: true // 监听 DOM 变化，自动恢复水印
})

QRCodeUtils

二维码工具类。

生成二维码

typescript

import { QRCodeUtils } from '@vben/utils'

// 生成二维码（返回 Data URL）
const qrCode = await QRCodeUtils.generate({
  text: 'https://example.com',
  width: 200,
  height: 200
})

// 显示在页面上
const img = document.createElement('img')
img.src = qrCode
document.body.appendChild(img)

自定义样式

typescript

import { QRCodeUtils } from '@vben/utils'

const qrCode = await QRCodeUtils.generate({
  text: 'https://example.com',
  width: 300,
  height: 300,
  colorDark: '#000000',
  colorLight: '#ffffff',
  correctLevel: QRCodeUtils.CorrectLevel.H // 容错级别
})

下载二维码

typescript

import { QRCodeUtils } from '@vben/utils'

await QRCodeUtils.download({
  text: 'https://example.com',
  filename: '二维码.png'
})

添加 Logo

typescript

import { QRCodeUtils } from '@vben/utils'

const qrCode = await QRCodeUtils.generate({
  text: 'https://example.com',
  width: 300,
  height: 300,
  logo: '/logo.png',
  logoWidth: 60,
  logoHeight: 60
})

ValidationUtils

前端验证工具类。

手机号验证

typescript

import { ValidationUtils } from '@vben/utils'

const isValid = ValidationUtils.isPhone('13812341234')
// 返回：true

邮箱验证

typescript

import { ValidationUtils } from '@vben/utils'

const isValid = ValidationUtils.isEmail('example@gmail.com')
// 返回：true

身份证验证

typescript

import { ValidationUtils } from '@vben/utils'

const isValid = ValidationUtils.isIdCard('110101199001011234')
// 返回：true

URL 验证

typescript

import { ValidationUtils } from '@vben/utils'

const isValid = ValidationUtils.isUrl('https://www.example.com')
// 返回：true

自定义验证规则

typescript

import { ValidationUtils } from '@vben/utils'

// 验证用户名（4-16位字母数字下划线）
const isValid = ValidationUtils.test(/^[a-zA-Z0-9_]{4,16}$/, 'username123')

StorageUtils

存储工具类，封装 localStorage 和 sessionStorage。

LocalStorage

typescript

import { StorageUtils } from '@vben/utils'

// 设置
StorageUtils.local.set('user', { name: '张三', age: 25 })

// 获取
const user = StorageUtils.local.get('user')

// 删除
StorageUtils.local.remove('user')

// 清空
StorageUtils.local.clear()

SessionStorage

typescript

import { StorageUtils } from '@vben/utils'

// 设置
StorageUtils.session.set('token', 'abc123')

// 获取
const token = StorageUtils.session.get('token')

// 删除
StorageUtils.session.remove('token')

设置过期时间

typescript

import { StorageUtils } from '@vben/utils'

// 设置 1 小时后过期
StorageUtils.local.set('data', { value: 123 }, 3600)

// 获取时自动检查过期
const data = StorageUtils.local.get('data') // 过期返回 null

FormatUtils

格式化工具类。

文件大小格式化

typescript

import { FormatUtils } from '@vben/utils'

FormatUtils.fileSize(1024)        // 1 KB
FormatUtils.fileSize(1048576)     // 1 MB
FormatUtils.fileSize(1073741824)  // 1 GB

数字格式化

typescript

import { FormatUtils } from '@vben/utils'

// 千分位
FormatUtils.number(1234567.89)  // 1,234,567.89

// 保留小数位
FormatUtils.number(123.456, 2)  // 123.46

// 货币格式
FormatUtils.currency(1234.56)   // ¥1,234.56

日期格式化

typescript

import { FormatUtils } from '@vben/utils'

const date = new Date()

FormatUtils.date(date, 'YYYY-MM-DD')           // 2026-02-05
FormatUtils.date(date, 'YYYY-MM-DD HH:mm:ss')  // 2026-02-05 14:30:00
FormatUtils.date(date, 'MM/DD/YYYY')           // 02/05/2026

相对时间

typescript

import { FormatUtils } from '@vben/utils'

const date = new Date(Date.now() - 3600000) // 1小时前
FormatUtils.relativeTime(date)  // 1小时前

const date2 = new Date(Date.now() - 86400000) // 1天前
FormatUtils.relativeTime(date2) // 1天前

TreeUtils

树形数据工具类。

数组转树

typescript

import { TreeUtils } from '@vben/utils'

const list = [
  { id: 1, name: '节点1', parentId: 0 },
  { id: 2, name: '节点1-1', parentId: 1 },
  { id: 3, name: '节点1-2', parentId: 1 },
  { id: 4, name: '节点2', parentId: 0 },
]

const tree = TreeUtils.listToTree(list, {
  id: 'id',
  parentId: 'parentId',
  children: 'children'
})

树转数组

typescript

import { TreeUtils } from '@vben/utils'

const tree = [
  {
    id: 1,
    name: '节点1',
    children: [
      { id: 2, name: '节点1-1' },
      { id: 3, name: '节点1-2' }
    ]
  }
]

const list = TreeUtils.treeToList(tree)

查找节点

typescript

import { TreeUtils } from '@vben/utils'

// 根据 ID 查找
const node = TreeUtils.findNode(tree, 2, 'id')

// 根据条件查找
const node = TreeUtils.findNode(tree, (node) => node.name === '节点1-1')

过滤树

typescript

import { TreeUtils } from '@vben/utils'

// 过滤包含关键字的节点
const filtered = TreeUtils.filterTree(tree, (node) => 
  node.name.includes('节点1')
)

ArrayUtils

数组工具类。

数组去重

typescript

import { ArrayUtils } from '@vben/utils'

const arr = [1, 2, 2, 3, 3, 4]
const unique = ArrayUtils.unique(arr)  // [1, 2, 3, 4]

// 对象数组去重
const users = [
  { id: 1, name: '张三' },
  { id: 2, name: '李四' },
  { id: 1, name: '张三' }
]
const unique = ArrayUtils.uniqueBy(users, 'id')

数组分组

typescript

import { ArrayUtils } from '@vben/utils'

const users = [
  { name: '张三', age: 25 },
  { name: '李四', age: 30 },
  { name: '王五', age: 25 }
]

const grouped = ArrayUtils.groupBy(users, 'age')
// { 25: [...], 30: [...] }

数组求和

typescript

import { ArrayUtils } from '@vben/utils'

const numbers = [1, 2, 3, 4, 5]
const sum = ArrayUtils.sum(numbers)  // 15

// 对象数组求和
const orders = [
  { amount: 100 },
  { amount: 200 },
  { amount: 300 }
]
const total = ArrayUtils.sumBy(orders, 'amount')  // 600

完整示例

用户列表导出

vue

<script setup lang="ts">
import { ref } from 'vue'
import { ExportUtils, FormatUtils, DesensitizeUtils } from '@vben/utils'
import { message } from 'ant-design-vue'

const users = ref([
  { id: 1, name: '张三', phone: '13812341234', email: 'zhangsan@example.com', createTime: new Date() },
  { id: 2, name: '李四', phone: '13987654321', email: 'lisi@example.com', createTime: new Date() },
])

const handleExport = () => {
  const data = users.value.map(user => ({
    ID: user.id,
    姓名: user.name,
    手机号: DesensitizeUtils.phone(user.phone),
    邮箱: DesensitizeUtils.email(user.email),
    创建时间: FormatUtils.date(user.createTime, 'YYYY-MM-DD HH:mm:ss')
  }))
  
  ExportUtils.exportExcel(data, '用户列表')
  message.success('导出成功')
}
</script>

<template>
  <Button @click="handleExport">导出用户</Button>
</template>

注意事项

注意

部分工具类需要浏览器 API 支持
加密工具仅用于前端简单加密，敏感数据请使用后端加密
剪贴板操作需要 HTTPS 或 localhost 环境
全屏 API 在不同浏览器中可能有差异

提示

使用 ExportUtils 时注意数据量，大数据建议后端导出
StorageUtils 会自动处理 JSON 序列化
TreeUtils 支持自定义字段名
FormatUtils 支持自定义格式

前端工具类 ​

工具类列表 ​

ExportUtils ​

导出 Excel ​

自定义列 ​

导出 CSV ​

导出 JSON ​

ClipboardUtils ​

复制文本 ​

复制 HTML ​

复制图片 ​

读取剪贴板 ​

EncryptUtils ​

MD5 加密 ​

AES 加密/解密 ​

SHA256 加密 ​

Base64 编码/解码 ​

FullscreenUtils ​

进入全屏 ​

退出全屏 ​

切换全屏 ​

监听全屏变化 ​

WatermarkUtils ​

添加水印 ​

自定义水印 ​

移除水印 ​

防删除水印 ​

QRCodeUtils ​

生成二维码 ​

自定义样式 ​

下载二维码 ​

添加 Logo ​

ValidationUtils ​

手机号验证 ​

邮箱验证 ​

身份证验证 ​

URL 验证 ​

自定义验证规则 ​

StorageUtils ​

LocalStorage ​

SessionStorage ​

设置过期时间 ​

FormatUtils ​

文件大小格式化 ​

数字格式化 ​

日期格式化 ​

相对时间 ​

TreeUtils ​

数组转树 ​

树转数组 ​

查找节点 ​

过滤树 ​

ArrayUtils ​

数组去重 ​

数组分组 ​

数组求和 ​

完整示例 ​

用户列表导出 ​

注意事项 ​

相关链接 ​

前端工具类

工具类列表

ExportUtils

导出 Excel

自定义列

导出 CSV

导出 JSON

ClipboardUtils

复制文本

复制 HTML

复制图片

读取剪贴板

EncryptUtils

MD5 加密

AES 加密/解密

SHA256 加密

Base64 编码/解码

FullscreenUtils

进入全屏

退出全屏

切换全屏

监听全屏变化

WatermarkUtils

添加水印

自定义水印

移除水印

防删除水印

QRCodeUtils

生成二维码

自定义样式

下载二维码

添加 Logo

ValidationUtils

手机号验证

邮箱验证

身份证验证

URL 验证

自定义验证规则

StorageUtils

LocalStorage

SessionStorage

设置过期时间

FormatUtils

文件大小格式化

数字格式化

日期格式化

相对时间

TreeUtils

数组转树

树转数组

查找节点

过滤树

ArrayUtils

数组去重

数组分组

数组求和

完整示例

用户列表导出

注意事项

相关链接