@TechUI/Utils 简介

TechUI Utils (工具函数库) 是 TechUI 生态系统的底层润滑剂。

不同于 Lodash 或 Underscore 这样大而全的通用库，@techui/utils 是为了满足 TechUI 内部组件对高性能、轻量级和特定业务逻辑的需求而深度定制的。它封装了从 DOM 操作到本地存储，再到类型检测的一系列原子能力。

一句话总结：轻量、纯净、为 TechUI 量身定制的底层工具集。

定位与使用建议

⚠️ 请注意：这是一个“内部优先”的工具库。

虽然本库完全开源并包含在 NPM 包中，但其主要设计目的是为了支撑 @techui/prime、@techui/admin 等上层组件库的运行。因此：

1. 内部专用逻辑：部分模块（如 i18n, style 的特定初始化方法）与 TechUI 的架构深度绑定，不建议开发者在业务代码中直接调用，以免随框架升级发生破坏性变更。
2. 开发者便利工具：另一部分模块（如 tTimer 定时器管理、tType 数据处理、tStore 存储封装）具有很高的通用性，我们非常推荐开发者在项目中使用它们来提升效率。

💡 建议：在阅读后续分模块文档时，请根据您的实际需求选择性使用。

核心模块概览

为了维持代码的组织性，我们将工具库划分为以下七大职能模块：

• 🛠 通用 (Common): 包含设备环境嗅探 (deviceInfo)、全屏控制以及一些无法归类的通用逻辑。
• ⚡️ 监测 (Monitor): 强大的事件管理系统。包含对 DOM 尺寸 (ResizeObserver)、节点变动 (MutationObserver) 的封装，以及高性能的事件防抖/节流工具。
• 💾 存储 (Store): 提供对 LocalStorage、SessionStorage、Cookie 以及 IndexedDB 的统一封装，支持自动序列化与命名空间管理。
• 🏗 DOM 操作 (DOM): 针对 TechUI 自适应系统优化的 DOM 查询与尺寸计算工具，解决了缩放场景下的坐标换算难题。
• 🛡 类型与数据: 提供比原生 typeof 更精准的类型检测，以及针对数组、对象、数字、字符串的深度处理（如深拷贝、合并）。
• 🎨 样式 (Style): 提供 CSS 变量生成、动态样式注入以及安全的 DOM 类名操作方法。
• 🌍 多语言 (i18n): 处理系统语言侦测、锁定与资源加载的底层逻辑。

设计哲学

您可能会问：“为什么不直接使用社区成熟的 Lodash 或 VueUse？”

极致的体积控制

TechUI 的核心组件（如 Base/Prime）对包体积极其敏感。引入完整的第三方通用库（往往 20KB+）对于仅需要其中几个函数的场景来说过于沉重。@techui/utils 保持了极小的体积。

业务逻辑绑定

我们需要处理特定于 TechUI 的逻辑，这些是通用库无法提供的。例如：

• 存储前缀：防止微前端环境下 Key 冲突。
• 自适应坐标：在 transform: scale 的容器中获取正确的 DOM 坐标。
• 主题注册校验：验证用户注册的主题对象是否符合 Schema。

安装

通常情况下，@techui/utils 会作为 Admin 或 Prime 的依赖自动安装。如果您需要在其他独立项目中复用这些能力：

npm install @techui/utils

按需引入

我们建议按需引入具体的模块：

// ✅ 推荐：只引入需要的模块
import { tTimer, tType } from "@techui/utils";

// 使用定时器工具
await tTimer.w(1000); // 等待 1秒

// 使用类型工具
if (tType(data) === 'array') {
  // ...
}

查看更多细节

TechUI Utils，有独立的章节介绍，请跳转至 工具 章节进行查看