通用工具

Common (通用模块) 汇集了 TechUI 中那些无法被简单归类，但在业务开发中极高频使用的“瑞士军刀”型函数。

它涵盖了从设备环境嗅探、数据结构转换到视图过渡动画等一系列原子能力。

引入方式

import { 
  deviceInfo, 
  fullScreen, 
  flatToTree, 
  genUid, 
  viewTransStart,
  colorPicker,
  tConsole,
  tTime
} from "@techui/utils";

设备与屏幕

deviceInfo()

获取当前设备的详细硬件与环境信息。常用于响应式布局判断或移动端兼容处理。

• 返回: Object
• 源码逻辑: 基于 UserAgent 和屏幕尺寸 (document.body.clientWidth) 进行计算断点。

const info = deviceInfo();
console.log(info);

/* 输出示例:
{
  type: "pc-xl",      // 屏幕断点: pc-xl, pc-lg, pc-md, pc-sm, pad, mobile
  h: 1920,            // 当前宽度
  v: 1080,            // 当前高度
  touchable: false,   // 是否支持触控
  browser: "webkit",  // 浏览器内核: webkit, Firefox, IE
  orientation: "landscape", // 横竖屏状态
  screenInvert: false       // 屏幕是否反转
}
*/

fullScreen

全屏控制对象，封装了浏览器原生的 requestFullscreen 和 exitFullscreen API。

• fullScreen.isEnabled(): 判断当前是否处于全屏状态。
• fullScreen.toggle(): 在全屏与非全屏之间切换。
• fullScreen.switch(boolean): 强制切换状态（true 进入全屏，false 退出）。

// 按钮点击事件
const handleScreen = () => {
  fullScreen.toggle();
};

数据结构

flatToTree(flatData)

将扁平化的数据库结果集（包含 id, parentId）转换为树形结构（包含 children）。

• 特性: 自动根据 order 字段排序，并清理空的 children 数组。
• 场景: 侧边栏菜单生成、组织架构树。

const list = [
  { id: 1, name: 'Root', parentId: null, order: 1 },
  { id: 2, name: 'Child', parentId: 1, order: 0 }
];

const tree = flatToTree(list);
// 结果: [{ id: 1, children: [{ id: 2, ... }] }]

genUid(prefix, len) V0.0.5+

生成唯一标识符。

• prefix: ID 前缀字符串。
• len: 随机后缀的长度。

genUid('node', 6); // 输出: "node_xYz123"

视觉与动画

viewTransStart(options)

基于 Chrome 原生 View Transitions API 的转场动画封装。

• 机制: 在动画执行期间，会自动给 html 根元素添加 tui-transitioning 类名，便于 CSS 钩子控制。
• 降级: 若浏览器不支持该 API，会直接执行回调。

viewTransStart({
  enable: true, // 是否开启转场
  callback: () => {
    // 在这里更新 DOM，例如切换路由或改变主题
    updateMyDom(); 
  },
  complete: () => {
    console.log('转场结束');
  }
});

colorPicker(options)

高级颜色拾取器。通常用于 ECharts 图表或数据可视化的动态配色生成。

• 依赖: 内部依赖 $c (Chroma.js 封装) 和 $tCore。
• 参数:
  • palette: 基础色板数组。
  • total: 生成颜色的总数。
  • mode: 插值模式 (lch, hsl, lab 等)。
  • pickType: 拾取策略 (seq 顺序, rdm 随机)。

注意，此工具在后续版本中可能被废弃，使用$c.scale替代

const colors = colorPicker({
  palette: ['#ff0000', '#0000ff'], // 红到蓝
  total: 10,                       // 生成10个渐变色
  mode: 'lch'
});

调试与格式化

tConsole

节流控制台。 用于防止同一条错误或警告信息在控制台中疯狂刷屏。

• tConsole.s(type, name, msg, thro): 发送信息。
  • type: 'log' | 'warn' | 'error' | 'info'
  • name: 唯一标识 Key，相同 Key 的信息会被节流。
  • thro: 是否开启节流（默认 true）。
• tConsole.g(name): 获取已缓存的信息。

// 在循环中调用，只会打印一次
for(let i=0; i<100; i++){
  tConsole.s('warn', 'myKey', '这是一条警告', true);
}

tTime

简单的正则时间格式化工具。

• formatTime(str, fmt): 格式化 HH:mm。
• formatWeek(str, fmt): 格式化 YYYY-WW。

tTime.formatTime('14:05', 'HH时MM分'); // -> "14时05分"
tTime.formatWeek('2023-W01', 'YYYY年 第WW周'); // -> "2023年 第01周"