VTJ核心引擎：通用辅助函数

踩着两条虫
1 阅读7分钟

通用辅助函数

简介

本文件面向“通用辅助函数”的技术文档，系统梳理与归纳了跨平台、跨模块的常用工具函数，覆盖字符串处理、尺寸解析、对象属性合并、样式注入与内联、脚本加载、请求与下载、存储、URL 工具、版本管理、日志与计时器等能力。文档提供函数参考、设计目的、适用场景、性能与注意事项，并辅以可视化图示帮助开发者高效使用。

项目结构

通用辅助函数主要分布在以下位置：

  • 平台层：web/h5 平台导出统一工具入口，便于在不同运行环境复用
  • UI 层：提供尺寸转换、对象属性合并等与 UI 渲染密切相关的工具
  • 渲染器层：提供样式注入、内联、脚本加载、插件识别、页面设置等渲染期工具
  • 基础工具包：提供通用的字符串、类型判断、网络请求、下载、存储、Cookie、JSONP、定时器、日志、版本等工具
graph TB
subgraph "平台层"
WEB["@vtj/web 工具入口<br/>platforms/web/src/utils/index.ts"]
H5["@vtj/h5 工具入口<br/>platforms/h5/src/utils/index.ts"]
end
subgraph "UI 层"
UIIDX["UI 工具入口<br/>packages/ui/src/utils/index.ts"]
UIUTIL["UI 工具实现<br/>packages/ui/src/utils/util.ts"]
end
subgraph "渲染器层"
RNDIDX["渲染器工具入口<br/>packages/renderer/src/utils/index.ts"]
RNDUTIL["渲染器工具实现<br/>packages/renderer/src/utils/util.ts"]
end
subgraph "基础工具包"
UIDX["工具包入口<br/>packages/utils/src/index.ts"]
UBASE["基础工具<br/>packages/utils/src/base.ts"]
UCLIENT["客户端工具<br/>packages/utils/src/client.ts"]
UCOOKIE["Cookie 工具<br/>packages/utils/src/cookie.ts"]
UDOWNLOAD["下载工具<br/>packages/utils/src/download.ts"]
UJSONP["JSONP 工具<br/>packages/utils/src/jsonp.ts"]
ULOAD["脚本加载<br/>packages/utils/src/loadScript.ts"]
ULOGGER["日志工具<br/>packages/utils/src/logger.ts"]
URAF["动画帧工具<br/>packages/utils/src/raf.ts"]
UREQUEST["请求工具<br/>packages/utils/src/request.ts"]
USTORAGE["存储工具<br/>packages/utils/src/storage.ts"]
UURL["URL 工具<br/>packages/utils/src/url.ts"]
UVERSION["版本工具<br/>packages/utils/src/version.ts"]
UUTIL["通用工具<br/>packages/utils/src/util.ts"]
end
WEB --> UIDX
H5 --> UIDX
UIIDX --> UIUTIL
RNDIDX --> RNDUTIL
UIDX --> UBASE
UIDX --> UCLIENT
UIDX --> UCOOKIE
UIDX --> UDOWNLOAD
UIDX --> UJSONP
UIDX --> ULOAD
UIDX --> ULOGGER
UIDX --> URAF
UIDX --> UREQUEST
UIDX --> USTORAGE
UIDX --> UURL
UIDX --> UVERSION
UIDX --> UUTIL

核心组件

本节对常用工具函数进行分类与要点说明，便于快速定位与使用。

  • 字符串与类型处理

    • 将任意值转为字符串（保留原字符串或序列化）
    • 判断是否为 Vue 插件（函数或带 install 的对象）
    • 判断是否为内置标签或原生 HTML 标签
    • 将布尔或对象值转换为对象属性集合（默认值合并）

  • 尺寸与单位处理

    • 将数值或百分比/视口单位转换为像素数值
    • 将数值或字符串尺寸转换为字符串（自动补 px）

  • 样式与脚本注入

    • 通过 CSSStyleSheet 或 style 元素注入样式（支持作用域与 rpx 转换）
    • 将已 adopted 的样式表内联到 head 中
    • 按 URL 列表批量注入 link stylesheet
    • 异步加载远程脚本并暴露全局库对象

  • 页面与容器设置

    • 基于页面/区块文件设置容器类名（如 is-page、is-pure）

  • 平台与运行时

    • 获取 Mock 实例（兼容不同运行时）
    • 通用工具（类型判断、字符串处理等）

架构总览

通用辅助函数采用“分层聚合”的组织方式：

  • 平台入口：统一导出工具包，屏蔽平台差异
  • 功能子模块：按领域拆分（网络、存储、样式、脚本、日志等）
  • UI/渲染器适配：在 UI 层与渲染器层补充与框架强相关的工具
graph LR
PWEB["平台 Web 入口"] --> UENTRY["工具包入口"]
PH5["平台 H5 入口"] --> UENTRY
UENTRY --> NET["网络/请求"]
UENTRY --> STORAGE["存储/Cookie"]
UENTRY --> DOWNLOAD["下载"]
UENTRY --> SCRIPT["脚本加载"]
UENTRY --> LOG["日志"]
UENTRY --> TIMER["计时器/RAF"]
UENTRY --> UTIL["通用工具"]
UI["UI 工具"] --> UENTRY
RENDER["渲染器工具"] --> UENTRY

详细组件分析

UI 工具函数

  • 函数：getSizeValue

    • 设计目的：统一尺寸输出格式，数字自动补 px
    • 参数：value（字符串或数字）
    • 返回：字符串（带 px 或原样返回）
    • 适用场景：样式计算、尺寸传参
    • 性能与注意：常量时间，无副作用

  • 函数：parseSize

    • 设计目的：将百分比/视口单位转换为基于最大值的像素值
    • 参数：size（字符串或数字）、max（最大值）
    • 返回：数字（像素）
    • 适用场景：响应式布局、容器尺寸计算
    • 性能与注意：正则匹配与整数解析，建议传入合法字符串

  • 函数：toObjectProps

    • 设计目的：将布尔或对象值标准化为对象属性集合
    • 参数：value（布尔或对象）、defaultValue（默认对象）
    • 返回：对象（合并默认值与传入对象）
    • 适用场景：组件属性合并、配置项归一化
    • 性能与注意：浅拷贝与对象合并，避免深层嵌套
flowchart TD
Start(["进入 parseSize"]) --> TypeCheck["判断 size 类型"]
TypeCheck --> IsNum{"是数字？"}
IsNum --> |是| RetNum["直接返回数字"]
IsNum --> |否| Regex["检测是否为百分比/视口单位"]
Regex --> HasUnit{"匹配到单位？"}
HasUnit --> |是| ParseInt["解析数值并按比例计算"]
HasUnit --> |否| ParseInt2["解析为整数"]
ParseInt --> Floor["向下取整"]
ParseInt2 --> RetInt["返回整数"]
Floor --> End(["结束"])
RetInt --> End
RetNum --> End

渲染器工具函数

  • 函数：toString

    • 设计目的：将任意值转为字符串（字符串保持不变，否则 JSON 序列化）
    • 参数：value（任意）
    • 返回：字符串
    • 适用场景：日志、调试信息输出

  • 函数：adoptedStyleSheets

    • 设计目的：向文档注入样式，支持作用域与 rpx 转换；优先使用 CSSStyleSheet API，回退到 style 元素
    • 参数：global（运行时窗口）、id（样式标识）、css（样式内容）、scoped（是否作用域）
    • 返回：无（副作用注入样式）
    • 适用场景：动态样式注入、主题切换
    • 性能与注意：CSSStyleSheet.replaceSync 在部分浏览器不可用时会回退到 DOM 操作，注意幂等性与去重

  • 函数：adoptStylesToInline

    • 设计目的：将已 adopted 的样式表规则内联到 head 的 style 中
    • 参数：document（文档对象）
    • 返回：无（副作用）
    • 适用场景：预渲染、静态化输出

  • 函数：loadCss

    • 设计目的：异步拉取远程 CSS 并注入
    • 参数：id、url
    • 返回：无
    • 适用场景：懒加载样式

  • 函数：loadCssUrl

    • 设计目的：批量注入 link stylesheet
    • 参数：urls（URL 数组）、global（可选）
    • 返回：无
    • 适用场景：多资源样式加载

  • 函数：loadScriptUrl

    • 设计目的：异步加载远程脚本并暴露全局库对象
    • 参数：urls（URL 数组）、library（库名称）、global（可选）
    • 返回：Promise（解析为模块默认或命名导出）
    • 适用场景：第三方库按需加载
    • 性能与注意：onload/onerror 处理，避免重复注入

  • 函数：isVuePlugin

    • 设计目的：判断值是否为 Vue 插件（函数或含 install 的对象）
    • 参数：value（未知）
    • 返回：布尔
    • 适用场景：插件注册前校验

  • 函数：isBuiltInTag / isNativeTag

    • 设计目的：区分内置组件与原生 HTML 标签
    • 参数：tag（字符串）
    • 返回：布尔
    • 适用场景：渲染器标签路由

  • 函数：getMock

    • 设计目的：获取 Mock 实例（兼容不同运行时）
    • 参数：global（可选）
    • 返回：Mock 对象或 undefined
    • 适用场景：测试与开发环境

  • 函数：setupPageSetting

    • 设计目的：根据页面/区块文件设置容器类名
    • 参数：app（应用实例）、route（路由对象）、file（页面/区块文件）
    • 返回：无
    • 适用场景：页面容器状态标记
sequenceDiagram
participant Caller as "调用方"
participant Loader as "loadScriptUrl"
participant Doc as "document.head"
participant Global as "window"
Caller->>Loader : 传入 urls, library
Loader->>Global : 读取已有模块
alt 已存在
Loader-->>Caller : 返回模块
else 不存在
loop 遍历 urls
Loader->>Doc : 创建 script 元素并设置 src
Doc-->>Loader : onload/onerror 回调
alt 加载成功
Loader->>Global : 读取 library
Loader-->>Caller : 返回模块
else 加载失败
Loader-->>Caller : 抛出错误
end
end
end

基础工具包（packages/utils）

  • 入口导出：统一导出各子模块，便于按需引入

  • 通用工具（util.ts）

    • 包含类型判断、字符串处理等基础能力

  • 基础工具（base.ts）

    • 提供基础类型与工具函数

  • 客户端工具（client.ts）

    • 运行时环境检测与客户端相关能力

  • Cookie 工具（cookie.ts）

    • Cookie 读写与解析

  • 下载工具（download.ts）

    • 文件下载与 Blob 处理

  • JSONP 工具（jsonp.ts）

    • JSONP 请求封装

  • 脚本加载（loadScript.ts）

    • 脚本加载与模块暴露

  • 日志工具（logger.ts）

    • 日志级别与输出控制

  • 计时器（raf.ts）

    • 动画帧与节流工具

  • 请求工具（request.ts）

    • HTTP 请求封装（GET/POST/拦截器等）

  • 存储工具（storage.ts）

    • 本地存储封装（localStorage/sessionStorage）

  • URL 工具（url.ts）

    • URL 解析与查询参数处理

  • 版本工具（version.ts）

    • 版本比较与语义化版本处理

依赖分析

  • 平台入口依赖工具包：web/h5 平台通过入口统一导出 @vtj/utils，降低模块耦合
  • UI/渲染器依赖工具包：UI 层与渲染器层分别导出自身工具入口，再由工具包统一收敛
  • 工具包内部模块解耦：各子模块独立导出，按需引入，避免全量导入
graph TB
WEBIDX["platforms/web/src/utils/index.ts"] --> UENTRY["packages/utils/src/index.ts"]
H5IDX["platforms/h5/src/utils/index.ts"] --> UENTRY
UIIDX["packages/ui/src/utils/index.ts"] --> UIUTIL["packages/ui/src/utils/util.ts"]
RNDIDX["packages/renderer/src/utils/index.ts"] --> RNDUTIL["packages/renderer/src/utils/util.ts"]
UENTRY --> UUTIL["packages/utils/src/util.ts"]
UENTRY --> UREQUEST["packages/utils/src/request.ts"]
UENTRY --> USTORAGE["packages/utils/src/storage.ts"]
UENTRY --> UURL["packages/utils/src/url.ts"]
UENTRY --> UDOWNLOAD["packages/utils/src/download.ts"]
UENTRY --> ULOAD["packages/utils/src/loadScript.ts"]
UENTRY --> ULOGGER["packages/utils/src/logger.ts"]
UENTRY --> URAF["packages/utils/src/raf.ts"]
UENTRY --> UCOOKIE["packages/utils/src/cookie.ts"]
UENTRY --> UJSONP["packages/utils/src/jsonp.ts"]
UENTRY --> UCLIENT["packages/utils/src/client.ts"]
UENTRY --> UBASE["packages/utils/src/base.ts"]
UENTRY --> UVERSION["packages/utils/src/version.ts"]

性能考虑

  • 样式注入

    • 优先使用 CSSStyleSheet API 注入，不支持时回退到 DOM 操作；注意幂等性与去重，避免重复插入
    • 内联 adopted 样式时受同源策略限制，读取失败会记录错误，建议降级处理

  • 尺寸解析

    • 百分比/视口单位解析涉及正则与整数解析，建议传入规范字符串，避免异常分支

  • 脚本加载

    • 使用 Promise 包装 script 加载，onload/onerror 分支明确，避免重复注入

  • 请求与下载

    • 统一的请求封装与下载工具，建议结合缓存与超时控制，避免频繁 IO

故障排查指南

  • 样式未生效

    • 检查是否正确调用注入函数，确认 id 唯一且未被覆盖
    • 若使用 CSSStyleSheet API，确认浏览器支持情况

  • adopted 样式内联失败

    • 检查同源策略与 CORS 设置，确认 cssRules 可读

  • 脚本加载失败

    • 检查 urls 是否可达，onerror 回调是否触发

  • 插件注册报错

    • 使用 isVuePlugin 校验插件类型，确保为函数或含 install 的对象

  • Mock 未找到

    • 使用 getMock 获取实例，注意不同运行时的差异

结论

通用辅助函数体系以“平台入口 + 工具包 + 领域子模块”的方式组织，兼顾跨平台与功能内聚。UI/渲染器层补充与框架强相关的工具，基础工具包提供通用能力。通过本文档的函数参考、设计目的、适用场景与性能注意事项，开发者可高效选择与组合工具函数，提升开发效率与稳定性。

附录

  • 平台入口导出

    • web 平台导出统一工具入口，便于在不同运行环境复用
    • h5 平台导出统一工具入口

  • UI 工具入口

    • 导出尺寸、对象属性合并等工具

  • 渲染器工具入口

    • 导出样式、脚本、插件识别、页面设置等工具
avatar
文章
阅读
粉丝