@pit-frontend-framework/utils

@pit-frontend-framework/utils

湖南创智艾泰克科技有限公司前端组通用工具库，为 pit-frontend-framework 体系下的所有项目提供类型安全的共享工具函数。

安装

pnpm add @pit-frontend-framework/utils

引用路径说明

包提供三个导入入口，按需选择：

入口	路径	适用场景
完整入口	@pit-frontend-framework/utils	默认使用，包含全部导出

功能模块

应用配置 appConfig

运行时配置初始化，替代 import.meta.env 直接读取。必须在 createApp() 之前调用。

import { initAppConfigFromViteEnv, getAppConfig, onAppConfigReady } from '@pit-frontend-framework/utils';

// main.ts 中最先执行
initAppConfigFromViteEnv(import.meta.env);

AppConfig 接口字段：

字段	类型	说明
mode	string	运行模式（development / production）
baseUrl	string	请求前缀 baseURL
timeout	number	请求超时时间（ms）
baseApi	string	后台 API 地址前缀
loginTitle	string	登录页标题
loginAuthor	string	登录页底部著作信息
title	string	网站标题
jm	string	积木地址
sort	string	排序服务地址
wssUrl	string	WebSocket 地址
bimApi	string	BIM 服务地址
enablePageOffice	boolean	是否启用 PageOffice
jwksKid	string?	JWKS 公钥 kid

全局运行时常量 define

从 AppConfig 派生，使用 ESM live binding，initAppConfig() 调用后自动填充。

import { DEFINE_TITLE, DEFINE_BASE_URL, DEFINE_LOGIN_AUTHOR } from '@pit-frontend-framework/utils';

导出常量： DEFINE_MODE / DEFINE_LOGIN_TITLE / DEFINE_LOGIN_AUTHOR / DEFINE_TITLE / DEFINE_BASE_URL / DEFINE_TIME / DEFINE_JWKS_KID / DEFINE_JWKS_PATH / DEFINE_JM / DEFINE_SORT / WSS_URL / BIM_API / ENABLE_PAGEOFFICE

认证 & Token auth

Token 的读写、清除及 lock 锁屏标记管理。

import { getToken, setToken, removeToken, getLock, setLock } from '@pit-frontend-framework/utils';

const token = getToken();
setToken('Bearer xxx');
removeToken();

HTTP 请求 request

基于 axios 封装，支持钩子注入（拦截器）。

import { createRequestClient, setRequestHooks, http } from '@pit-frontend-framework/utils';

// 注册全局拦截钩子
setRequestHooks({
  onRequest(config) {
    config.headers.set('Authorization', getToken());
    return config;
  },
  onResponse(response) {
    // 统一处理响应
  },
});

// 使用默认实例
http.get('/api/user');
http.post('/api/login', { username, password });

路由上下文 routerContext / getRouter

框架不直接依赖宿主路由，通过注入解析函数实现解耦。

import { setRouteResolver, getCurrentRoute, getRouter } from '@pit-frontend-framework/utils';
import router from '@/router';

// main.ts 中注入
setRouteResolver(() => router.currentRoute.value);

// 任意处读取路由参数
const id = getRouter('id');            // 自动从 params / query / meta 查找
const type = getRouter('type', 'query'); // 指定从 query 读取

权限上下文 permissionContext

框架不依赖宿主 store，权限判断通过注入回调实现。

import { setPermissionContext, hasP, hasBtnP, hasFormP } from '@pit-frontend-framework/utils';

// main.ts 中注入
setPermissionContext({
  getPermissionList: () => store.permissionList,
  getModelId: () => store.modelId,
});

// 判断权限
hasP('system:user:add');
hasBtnP('btn_add');

存储适配器 storage

带前缀的 localStorage 封装，支持 JSON 序列化，SSR 降级到内存存储。

import { createStorage, storageGet, storageSet, storageRemove } from '@pit-frontend-framework/utils';

// 使用全局默认存储（前缀为空）
storageSet({ theme: 'dark', language: 'zh-CN' });
const theme = storageGet<string>('theme');
storageRemove('theme');

// 创建自定义前缀存储
const store = createStorage({ prefix: 'myapp_' });
store.set({ userId: '123' });
store.get<string>('userId');

跨标签页通信 broadcastService

基于 BroadcastChannel 封装，支持类型安全的事件订阅。

import { BroadcastService } from '@pit-frontend-framework/utils';

const bus = new BroadcastService('app');

// 订阅（自动清理）
const unsubscribe = bus.on<{ userId: string }>('logout', (data) => {
  console.log(data.userId);
});

// 广播（所有标签页 + 自身均触发）
bus.postMessage('logout', { userId: '123' });

// 取消订阅
unsubscribe();

i18n 桥接 i18n

与 vue-i18n 实例桥接，合并内置语言包，提供无依赖的 t() 函数。

import { locale, t } from '@pit-frontend-framework/utils';
import i18n from '@/i18n';

// main.ts 注入实例（合并内置语言包）
locale(i18n);

// 任意处翻译
t('clipboard.success');               // '复制成功！'
t('missing.key', '默认文本');         // 找不到时返回 fallback

内置语言包 namespace： clipboard / validate / passwordValidate / formValidate

表单校验 form

el-form rule 风格的校验器工厂，支持预置规则和自定义正则字符串，错误信息接入 i18n。

import { formValidate, regularList } from '@pit-frontend-framework/utils';

// 使用预置规则
const rules = {
  phone: [{ validator: formValidate('iphone'), trigger: 'blur' }],
  email: [{ validator: formValidate('email', '请输入有效邮箱'), trigger: 'blur' }],
};

// 自定义正则
const customRule = formValidate('/^[A-Z]{3}$/', '必须是3位大写字母');

预置规则： iphone / password / idCard / email / plateNumber / chinese / enCode / enCode2 / userAccount / userAccount1 / english / fullName / userCode / allDate / bigInt / netUrl

密码强度校验 password

import { passwordValidate, passwordValidateMsg, checkPasswordComplexity } from '@pit-frontend-framework/utils';

passwordValidate('MyP@ss1234word');   // boolean
passwordValidateMsg('weak');          // 返回 i18n 翻译的错误信息
checkPasswordComplexity('Abc123!');  // 仅基础复杂度检查，返回错误消息或空字符串

密码规则： 12-16 位，必须包含大小写字母、数字、特殊字符，且不含连续相同/字母/数字/键盘序列。

JWKS 公钥加密 jwks

import { getJwks, setJwksConfig } from '@pit-frontend-framework/utils';

// 设置全局 kid
setJwksConfig({ kid: 'your-key-id' });

// 加密（通常用于登录密码）
const encrypted = await getJwks(password, '/api/auth/.well-known/jwks.json');

日期工具 date

基于 dayjs 封装。

import { toDate, dateFormat, handleDateStr } from '@pit-frontend-framework/utils';

dateFormat(new Date(), 'YYYY-MM-DD');       // '2026-04-29'
toDate('2026-04-29');                        // Date 对象
handleDateStr('2026-04-29 12:00:00');       // 统一处理日期字符串

对象/数字工具 object

import { formatFloat, amountThousandsConversion, deepClone } from '@pit-frontend-framework/utils';

formatFloat(12.3456, 2);              // '12.35'
amountThousandsConversion(1234567);  // '1,234,567'
deepClone({ a: { b: 1 } });          // 深拷贝

树结构工具 tree

import { arrayToTree, treeToArray, iterationArr, toTreeViewJson } from '@pit-frontend-framework/utils';

// 扁平数组转树
arrayToTree(flatList, { id: 'id', parentId: 'parentId' });

// 树转扁平数组（深拷贝，children 置 null）
treeToArray(treeList);

// 遍历树节点
iterationArr(treeList, (node) => console.log(node));

校验工具 validate

import { isExternal, validURL, validEmail, islongitude, islatitude } from '@pit-frontend-framework/utils';

isExternal('https://example.com');   // true
validEmail('[e-mail]');       // true

表格列宽配置 tableSize

根据 el-table size 属性按比例生成列宽常量。

import { TABLE_SIZE, createTableSize } from '@pit-frontend-framework/utils';

// 默认 default 尺寸
TABLE_SIZE.DATE_WIDTH;     // 180
TABLE_SIZE.CREATOR_WIDTH;  // 120

// 挂载为 Vue 全局属性
app.config.globalProperties.$TABLE_SIZE = TABLE_SIZE;

通用业务常量 constants

import { IS_OK, BIDTYPE } from '@pit-frontend-framework/utils';

// HTTP 响应成功码
IS_OK; // '00000'

// 标段类型枚举
BIDTYPE.SG; // 'SG'

打印工具 print

import { Print, createPrintContent, MyPrint } from '@pit-frontend-framework/utils';

// 打印指定区域
Print('#print-area');

// 获取打印 HTML 内容（用于自定义处理）
const html = createPrintContent('#print-area', { noPrint: '.no-print' });

// Vue 插件形式（注入 $print）
app.use(MyPrint);

浏览器工具 browser

import { downloadFile, formatFileSize, copyText } from '@pit-frontend-framework/utils';

downloadFile('https://example.com/file.pdf', '文件.pdf');
formatFileSize(1048576); // '1.00 MB'

剪贴板 clipboard

import { copyText } from '@pit-frontend-framework/utils';

await copyText('Hello World');

事件总线 emitter

轻量级事件总线，基于 mitt 封装。

import { emitter } from '@pit-frontend-framework/utils';

emitter.on('refresh', () => { /* ... */ });
emitter.emit('refresh');
emitter.off('refresh');

pit 业务工具集 pit（兼容层）

聚合权限、存储、流程、数字、树等常用操作的兼容对象，对应旧版 pit-business-utils。

import { pit } from '@pit-frontend-framework/utils';

pit.hasP('system:user');
pit.hasBtnP('btn_add');
pit.hasFlow({ approvalStatus: 'draft', writeable: true }, true);
pit.storageGet<string>('theme');
pit.toDecimal(12.3);             // '12.30'
pit.toFileSize(1048576);         // '1.00 MB'

Peer Dependencies

依赖	版本要求
axios	^1.15.0
dayjs	^1.11.1
lodash / lodash-es	^4.17.21
lodash-unified	^1.0.3
jsrsasign	^10.9.0
qs	^6.11.2

启动初始化顺序

在 main.ts 中，以下调用有顺序依赖：

// 1. 最先初始化配置（其他工具依赖此）
initAppConfigFromViteEnv(import.meta.env);

// 2. 注入路由上下文
setRouteResolver(() => router.currentRoute.value);

// 3. 注入权限上下文
setPermissionContext({ ... });

// 4. 注入 i18n
locale(i18n);

// 5. createApp / app.mount