new-utils.md 7.2 KB
工具函数（新增）
本文档记录新增的前端工具函数。
clipboard — 剪贴板
复制文本到剪贴板。
copyToClipboard(text, onSuccess, onError)
底层复制方法，使用 navigator.clipboard API，带 execCommand 降级。
import { copyToClipboard } from '@/utils/clipboard'
copyToClipboard(
'Hello World',
() => console.log('复制成功'),
(err) => console.error('复制失败', err)
)
copy(text, successMsg, errorMsg)
高级复制方法，成功后自动弹出 Naive UI 消息提示。
import { copy } from '@/utils/clipboard'
copy('复制的内容', '复制成功', '复制失败')
websocket — WebSocket 客户端
基于 SockJS + STOMP 的 WebSocket 客户端。
initWebSocketClient()
初始化并连接 WebSocket 服务。
import { initWebSocketClient, disconnectWebSocketClient } from '@/utils/websocket'
// 初始化连接
initWebSocketClient()
// 断开连接
disconnectWebSocketClient()
功能
- 连接到
/ws端点 - 开发环境自动适配
VITE_HTTP_PROXY_TARGET - 订阅
/topic/auth主题 - 自动处理认证相关广播（踢出、替换、封禁）并自动登出
依赖
sockjs-client@stomp/stompjs@/store（useAuthStore, useUserStore）
watermark — 水印
全屏水印管理工具，基于 Naive UI NWatermark 组件。
createWatermark(options)
创建水印，返回 { destroy() }。
import { createWatermark } from '@/utils/watermark'
const wm = createWatermark({
content: '内部机密',
fontSize: 16,
fontColor: '#cccccc',
rotate: -20,
xGap: 200,
yGap: 200,
zIndex: 1000
})
// 销毁水印
wm.destroy()
setupWatermark()
获取水印管理器，支持 show/hide/update。
import { setupWatermark } from '@/utils/watermark'
const watermark = setupWatermark()
watermark.show({ content: '内部机密' })
watermark.hide()
watermark.update({ content: '新的水印' })
tab — 标签页管理
多标签页导航管理工具。
import {
closePage,
closeAndOpen,
reloadPage,
closeOtherPages,
closeAllPages
} from '@/utils/tab'
// 关闭指定标签页
closePage('/user/list')
// 关闭并打开新页面
closeAndOpen('/old-path', '/new-path')
// 刷新当前页面
reloadPage('/user/list')
// 关闭其他页面
closeOtherPages('/user/list')
// 关闭所有页面
closeAllPages()
导出方法
| 方法 | 说明 |
|---|---|
closePage(target) |
关闭指定标签页 |
closePages(targets) |
批量关闭标签页 |
closeAndOpen(closeTarget, openTarget) |
关闭旧页面，打开新页面 |
reloadPage(path) |
刷新指定页面 |
closeOtherPages(path) |
关闭除指定页面外的所有标签页 |
closeLeftPages(path) |
关闭左侧标签页 |
closeRightPages(path) |
关闭右侧标签页 |
closeAllPages() |
关闭所有标签页 |
echarts-theme — ECharts 主题
ECharts 主题配置，支持 CSS 变量集成和暗色模式。
getEChartsTheme()
获取完整的 ECharts 主题配置（从 CSS 变量派生）。
import { getEChartsTheme, chartPresets } from '@/utils/echarts-theme'
const theme = getEChartsTheme()
chart.setOption({ ...chartPresets.line, theme })
chartPresets
预置图表配置：
| 预设 | 说明 |
|---|---|
line |
折线图 |
area |
面积图 |
bar |
柱状图 |
pie |
饼图 |
scatter |
散点图 |
radar |
雷达图 |
gauge |
仪表盘 |
getResponsiveConfig(containerWidth)
根据容器宽度返回响应式网格/标签配置。
其他方法
| 方法 | 说明 |
|---|---|
generateGradientColor(color, alpha) |
生成渐变色（Hex → RGBA） |
generateChartGradient(ctx, color, direction) |
创建线性渐变 |
toggleEChartsTheme(chartInstance) |
切换 ECharts 主题 |
applyThemeToChart(chartInstance, customTheme) |
应用自定义主题 |
responsive-font — 响应式字体
根据屏幕宽度自动缩放字体大小。
import { calculateFontScale, initResponsiveFont } from '@/utils/responsive-font'
// 手动计算
const scale = calculateFontScale()
// 自动初始化（带防抖 resize 监听）
initResponsiveFont(() => {
console.log('字体缩放已更新')
})
断点
| 屏幕宽度 | 缩放比例 |
|---|---|
| ≤ 768px | 0.8 |
| ≤ 1024px | 0.85 |
| ≤ 1440px | 0.9 |
| > 1440px | 1.0 |
enum — 字典/枚举
字典数据获取、缓存和查找。
import { getEnum, getEnumLabel, batchGetEnum } from '@/utils/enum'
// 获取字典（自动缓存）
const items = await getEnum('user_status')
// 查找 Label
const label = getEnumLabel('user_status', 1) // → "启用"
// 批量获取
const enums = await batchGetEnum(['user_status', 'user_type'])
导出方法
| 方法 | 说明 |
|---|---|
getEnum(type, version, forceRefresh) |
获取字典数据 |
batchGetEnum(types) |
批量获取字典 |
getEnumLabel(type, value) |
根据值查找标签 |
getEnumValue(type, label) |
根据标签查找值 |
clearEnumCache(types) |
清除指定字典缓存 |
clearAllEnumCache() |
清除所有字典缓存 |
is — 类型检查
类型检查工具函数。
import { isString, isArray, isNumber, isEmpty, isUrl } from '@/utils/is'
isString('hello') // true
isArray([1, 2, 3]) // true
isNumber(42) // true
isEmpty({}) // true
isUrl('https://...') // true
导出方法
is(val, type), isDef, isUndef, isNull, isWhitespace, isObject, isArray, isString, isNumber, isBoolean, isDate, isRegExp, isFunction, isPromise, isElement, isWindow, isNullOrUndef, isNullOrWhitespace, isEmpty, ifNull(val, def), isUrl, isExternal, isServer, isClient
menu-utils — 菜单工具
菜单数据处理工具，将原始菜单数据转为 Naive UI 菜单格式。
import { processMenuData, findActiveTopMenu, findMenuItem } from '@/utils/menu-utils'
const { topMenus, sideMenus } = processMenuData(rawMenuData)
const activeTop = findActiveTopMenu(topMenus, route)
const item = findMenuItem(topMenus, 'system-user')
导出方法
| 方法 | 说明 |
|---|---|
processTopMenus(menuItems) |
处理顶级菜单，生成唯一 ID/Key，包装图标 |
processMenuData(menuItems) |
扁平化 subapp 类型，处理子项，转换图标为渲染函数 |
findActiveTopMenu(menus, route) |
查找当前路由对应的顶级菜单 |
findMenuItem(menuItems, key) |
递归查找指定 Key/ID 的菜单项 |
naiveTools — Naive UI 增强
Naive UI 离散 API 的全局化和增强。
功能
- Message 增强 — 键值去重（防止重复弹出）、loading 状态支持
- Dialog 增强 — 添加
NDialog.confirm()快捷方法 - 全局挂载 —
window.$message,window.$dialog,window.$notification,window.$loadingBar,window.$loading,window.$copy,window.$imagePreview,window.$watermark,window.$homePath - 暗色模式 — 自动适配主题
- Loading 服务 — 全屏 Loading 遮罩（
show(),close(),service()）
入口函数
import { setupNaiveDiscreteApi } from '@/utils/naiveTools'
// 在应用初始化时调用
setupNaiveDiscreteApi()