VTJ核心引擎：工具函数库

工具函数库

简介

本文件为 VTJ 低代码引擎工具函数库的全面技术文档，覆盖核心引擎提供的实用工具函数，重点包括：

• 数据处理工具：数组/映射/键值对转换、去重、拆分/拼接、统计等
• 文件与媒体工具：File/Blob/Base64/FormData 转换与下载
• Web 平台工具：URL 解析与拼接、浏览器信息采集、请求封装、JSONP、脚本加载、RAF、日志记录
• 存储工具：统一的带过期策略的本地/会话/内存存储封装

文档提供 API 接口说明、参数与返回值、使用示例、性能优化建议与最佳实践，并解释设计原则与扩展机制，帮助开发者快速定位与高效使用。

项目结构

工具函数库位于 packages/utils，对外通过统一入口导出，内部按功能域拆分模块，便于按需引入与测试。

graph TB
subgraph "工具库入口"
IDX["index.ts<br/>统一导出"]
end
subgraph "核心工具模块"
UTIL["util.ts<br/>客户端判断/文件/FormData/Blob转换"]
CLIENT["client.ts<br/>客户端信息采集"]
URL["url.ts<br/>URL解析/拼接/查询串编解码"]
STORAGE["storage.ts<br/>统一存储封装(含过期)"]
DOWNLOAD["download.ts<br/>下载工具"]
RAF["raf.ts<br/>动画帧调度"]
PATCH["browser-patch.ts<br/>事件监听兼容补丁"]
end
subgraph "Web 平台工具"
REQ["request.ts<br/>HTTP请求封装(含拦截器/并发/取消/跳过警告)"]
JSONP["jsonp.ts<br/>JSONP请求"]
LOAD["loadScript.ts<br/>动态脚本加载"]
LOG["logger.ts<br/>日志门控与业务命名空间"]
end
IDX --> UTIL
IDX --> CLIENT
IDX --> URL
IDX --> STORAGE
IDX --> DOWNLOAD
IDX --> RAF
IDX --> PATCH
IDX --> REQ
IDX --> JSONP
IDX --> LOAD
IDX --> LOG

核心组件

• 统一入口导出：通过 index.ts 汇聚所有子模块，支持按需导入与全量导入
• 客户端能力：isClient 判断运行环境；client.ts 提供 UA 解析的客户端信息
• 数据处理：util.ts 提供文件/FormData/Blob 转换与基础工具；配合 @vtj/base 的数组/树等工具
• Web 请求：request.ts 封装 axios，提供拦截器、并发控制、取消、跳过警告、URL 模板替换等
• 存储：storage.ts 提供统一的本地/会话/内存存储，支持过期与前缀
• URL 工具：url.ts 提供 host 获取、URL 解析、查询串编解码、参数追加
• 下载：download.ts 支持 URL/远程文件/Blob/JSON 下载
• 日志：logger.ts 提供按级别与业务名过滤的日志记录器
• JSONP/脚本加载：jsonp.ts 与 loadScript.ts 提供跨域与动态脚本加载能力
• 动画帧：raf.ts 提供 requestAnimationFrame/cancelAnimationFrame 的安全封装

架构总览

工具库采用“按功能域拆分 + 统一入口导出”的组织方式，内部模块之间通过明确职责边界协作，避免循环依赖。核心模块间关系如下：

graph LR
UTIL["util.ts"] --> URL["url.ts"]
UTIL --> STORAGE["storage.ts"]
UTIL --> DOWNLOAD["download.ts"]
CLIENT["client.ts"] --> UTIL
RAF["raf.ts"] --> UTIL
PATCH["browser-patch.ts"] --> UTIL
REQ["request.ts"] --> URL
REQ --> UTIL
JSONP["jsonp.ts"] --> URL
LOAD["loadScript.ts"] --> UTIL
LOG["logger.ts"] --> UTIL

详细组件分析

数据处理工具（util.ts）

• isClient：判断是否在浏览器环境
• fileToBase64：将 File 对象异步转为 dataURL（base64）
• formDataToJson：将 FormData 转为普通对象，字符串值进行解码
• dataURLtoBlob：将 dataURL（base64）转为 Blob
• blobToFile：将 Blob 转为 File（设置 lastModified/name）

flowchart TD
Start(["开始"]) --> CheckEnv["检查运行环境"]
CheckEnv --> IsClient{"是否浏览器环境？"}
IsClient --> |否| Fallback["返回默认值/空结果"]
IsClient --> |是| Op["执行具体转换操作"]
Op --> End(["结束"])

客户端信息采集（client.ts）

• getClientInfo：解析 userAgent，识别操作系统、版本、浏览器、版本、是否移动设备
• 识别逻辑覆盖 Windows/Mac/iOS/Android/Linux，以及 Edge/Firefox/Opera/Chrome/Safari/IE 等主流浏览器

flowchart TD
UA["获取UA"] --> DetectOS["检测操作系统"]
DetectOS --> DetectBrowser["检测浏览器与版本"]
DetectBrowser --> MobileCheck["移动设备判定"]
MobileCheck --> Result["返回客户端信息对象"]

URL 工具（url.ts）

• getCurrentHost：获取当前页面 host（可选包含路径）
• getHost：从任意 URL 中提取 host
• stringify：对象转查询串（含编码）
• parse：查询串解析为对象（含解码）
• append：向 URL 追加查询参数（支持字符串或对象）

flowchart TD
In["输入URL/查询对象"] --> Split["分离路径与查询串"]
Split --> Merge["合并原始查询与新查询"]
Merge --> Encode["逐项编码"]
Encode --> Join["拼接为完整URL"]
Join --> Out["输出"]

存储工具（storage.ts）

• Storage 类：统一管理本地/会话/内存存储，支持过期时间与 key 前缀
• 方法：save/get/remove/clear，自动处理 JSON 序列化/反序列化与过期清理
• storage 实例：默认实例，可直接使用

classDiagram
class Storage {
+options : StorageOptions
+save(key, value, opts)
+get(key, opts)
+remove(key, opts)
+clear(opts)
}
class StorageOptions {
+type : "cache"|"local"|"session"
+expired : number
+prefix : string
}
Storage --> StorageOptions : "配置"

下载工具（download.ts）

• downloadUrl：直接下载指定 URL
• downloadBlob：下载 Blob 数据
• downloadRemoteFile：远程下载并触发下载
• downloadJson：下载 JSON 数据

sequenceDiagram
participant U as "调用方"
participant D as "download.ts"
participant F as "浏览器下载"
U->>D : downloadUrl(url, filename)
D->>F : 创建a标签并触发点击
F-->>U : 触发下载

请求封装（request.ts）

• Request 类：基于 axios 的二次封装，支持拦截器、并发/取消、URL 模板、数据类型转换、跳过警告、loading 控制、错误提示
• 工厂函数 createRequest/createApi/createApis/useApi：提供便捷的静态 API
• 关键特性：请求/响应拦截、超时、Content-Type 自动推断、FormData/URLSearchParams 自动构造、path 参数模板替换

sequenceDiagram
participant C as "调用方"
participant R as "Request"
participant AX as "axios"
participant INT as "拦截器"
C->>R : send({url, data, settings})
R->>AX : 发起请求(合并headers/params/data)
AX-->>INT : 响应进入拦截器
INT-->>R : 校验/转换/包装
R-->>C : 返回数据(可选原始响应/成功校验)

JSONP（jsonp.ts）

• jsonp：支持 URL 模板与查询参数追加，返回 Promise 包裹的 JSON 结果

flowchart TD
A["输入URL/选项"] --> B{"URL是否包含模板占位符？"}
B --> |是| C["模板编译并替换变量"]
B --> |否| D["保持原URL"]
C --> E["追加查询参数"]
D --> E
E --> F["发起JSONP请求"]
F --> G["解析JSON并返回"]

动态脚本加载（loadScript.ts）

• loadScript：异步加载外部脚本，支持字符集、属性、文本内容与库导出名

flowchart TD
S["输入脚本地址/选项"] --> L["加载脚本"]
L --> OK{"加载成功？"}
OK --> |是| R["解析导出(可选)并返回"]
OK --> |否| E["抛出错误"]

动画帧调度（raf.ts）

• rAF/cAF：在浏览器环境下使用 requestAnimationFrame/cancelAnimationFrame，在非浏览器环境降级为 setTimeout/setTimeout

flowchart TD
A["rAF(fn)"] --> B{"是否浏览器环境？"}
B --> |是| C["使用requestAnimationFrame(fn)"]
B --> |否| D["使用setTimeout(fn, 16)"]

日志记录（logger.ts）

• Logger：支持 debug/log/info/warn/error 五级日志，可通过 URL 参数动态调整日志级别与业务名前缀

flowchart TD
CFG["解析URL中的日志配置"] --> LEVEL["确定目标级别"]
CFG --> BN["确定业务名匹配规则"]
LEVEL --> LOG["按级别输出日志"]
BN --> LOG

浏览器事件补丁（browser-patch.ts）

• 为 EventTarget.prototype.addEventListener 增强 passive 默认行为，确保兼容性

依赖关系分析

• 内部依赖：各模块相对独立，仅在必要处相互引用（如 util.ts 被多模块复用）
• 外部依赖：axios、load-script、fetch-jsonp、@vtj/base（用于合并、防抖节流、路径模板等）
• 导出策略：index.ts 统一 re-export，便于按需引入与 Tree-shaking

graph TB
P["packages/utils/package.json"] --> DEP["@vtj/base"]
P --> AX["axios"]
P --> LS["load-script"]
P --> FJP["fetch-jsonp"]
IDX["index.ts"] --> M1["util.ts"]
IDX --> M2["client.ts"]
IDX --> M3["url.ts"]
IDX --> M4["storage.ts"]
IDX --> M5["download.ts"]
IDX --> M6["request.ts"]
IDX --> M7["jsonp.ts"]
IDX --> M8["loadScript.ts"]
IDX --> M9["raf.ts"]
IDX --> M10["logger.ts"]
IDX --> M11["browser-patch.ts"]

性能与优化

• 请求层
  • 合理设置超时与 Content-Type，减少不必要的数据转换
  • 使用拦截器统一处理 loading 与错误提示，避免重复逻辑
  • 对高频请求使用防抖/节流或缓存策略
• 存储层
  • 为过期时间设置合理阈值，避免频繁 IO
  • 使用前缀隔离不同业务域，降低 key 冲突风险
• 文件与下载
  • 大文件优先使用 Blob/远程下载，避免内存峰值
  • 下载完成后及时 revokeObjectURL，释放内存
• 日志
  • 生产环境限制日志级别，避免过多 I/O
  • 使用业务名前缀精准筛选日志

故障排查指南

• 请求失败
  • 检查拦截器链路与 validate 回调
  • 确认 headers 与 Content-Type 是否匹配
  • 使用 useRequest/useResponse 快速定位问题
• JSONP 失败
  • 确认回调参数与服务端一致
  • 检查 append 后的 URL 是否正确
• 存储异常
  • 检查 JSON 序列化/反序列化是否正常
  • 核对过期时间与前缀配置
• 下载无效
  • 确认 Blob 类型与下载链接是否有效
  • 检查跨域与权限设置

结论

该工具函数库以“模块化 + 统一入口”为核心设计思想，围绕数据处理、文件与下载、Web 请求、URL/存储、日志与脚本加载等关键场景提供了高内聚、低耦合的工具集。通过拦截器、过期策略、环境适配与降级方案，兼顾易用性与稳定性。建议在实际项目中结合文档与示例，按需引入并遵循最佳实践，以获得更佳的开发体验与运行性能。

附录：函数参考手册

基础工具（util.ts）

• isClient：布尔值，表示是否在浏览器环境
• fileToBase64(file: File)：Promise，将文件转为 dataURL
• formDataToJson(data: FormData)：Record<string, any>，将 FormData 转为对象
• dataURLtoBlob(dataURL: string)：Blob，将 dataURL 转为 Blob
• blobToFile(blob: Blob, fileName: string)：File，将 Blob 转为 File

客户端信息（client.ts）

• getClientInfo()：ClientInfo，包含 os/osVersion/browser/browserVersion/isMobile

URL 工具（url.ts）

• getCurrentHost(includePath: boolean)：string|null，获取当前 host
• getHost(url: string)：string，从 URL 中提取 host
• stringify(query: Record<string, any>)：string，对象转查询串
• parse(str: string, sep?: string, eq?: string)：Record<string, any>，查询串转对象
• append(url: string, query: string|Record<string, any>)：string，在 URL 追加参数

存储工具（storage.ts）

• new Storage(options)：构造函数，支持 type/expired/prefix
• save(key, value, opts?)：保存
• get(key, opts?)：读取，自动处理过期
• remove(key, opts?)：删除
• clear(opts?)：清空
• storage：默认实例

下载工具（download.ts）

• downloadUrl(url: string, filename?: string)：void
• downloadBlob(data: any, filename?: string, type?: string)：void
• downloadRemoteFile(url: string, filename?: string, type?: string)：Promise
• downloadJson(data: any, filename?: string)：void

请求封装（request.ts）

• createRequest(options)：IStaticRequest，工厂函数
• request：默认实例
• createApi(config|url, req?)：函数式 API
• createApis(map, req?)：批量生成 API
• useApi(loader, transform?)：组合式 API，返回 data/error/loading/reload

JSONP（jsonp.ts）

• jsonp(url: string, options?)：Promise，支持模板与查询参数

动态脚本加载（loadScript.ts）

• loadScript(src: string, options?)：Promise<any|undefined>，支持 library 导出名

动画帧（raf.ts）

• rAF(fn)：number，requestAnimationFrame 或 setTimeout 降级
• cAF(handle)：void，cancelAnimationFrame 或 clearTimeout

日志（logger.ts）

• getLogger(options)：Logger 实例
• Logger.debug/log/info/warn/error：按级别输出
• logger：默认实例

参考资料

VTJ.PRO 是一个开源的、AI 驱动的 Vue 3 企业级应用开发平台。它通过 AI 智能体与可视化编排实现高效开发，并支持导出标准 Vue 代码以避免平台锁定。更多信息请访问：

• 📘 官方文档：vtj.pro/
• 🌐 在线平台：app.vtj.pro/
• 📦 开源仓库：gitee.com/newgateway/…