DOM 操作

DOM 模块 提供了对原生 DOM 操作的轻量级封装，特别针对 TechUI 的 TuiAdaptive (自适应) 系统进行了深度优化。

它不仅包含常规的元素查询与查找，还提供了在复杂缩放环境（Scale Context）下精准计算元素尺寸与坐标的核心算法。

引入方式

import { syncContSize, tCoreTpl, tDom, tQuery } from "@techui/utils";

元素查询

tQuery 对象提供了一组用于查找和遍历 DOM 节点的快捷方法。

tQuery.el(selector, all)

querySelector 的简写封装。

• selector: CSS 选择器字符串。
• all: boolean。默认为 false 返回单个元素，设为 true 返回 NodeList。

const app = tQuery.el('#app'); 
const items = tQuery.el('.list-item', true);

tQuery.get1stParent(el, selector)

查找最近的匹配父级元素（closest 的封装）。

// 查找当前点击元素最近的 .card 父级
const card = tQuery.get1stParent(e.target, '.card');

tQuery.clearExcept(container, exceptEl)

清空容器内的所有子元素，但保留指定的某一个元素。常用于保留 loading 遮罩或特定状态节点。

tQuery.clearExcept(document.body, document.querySelector('#app'));

tQuery.valueByPath(obj, path, fallback)

多语言/深层对象取值器。 虽然不是直接操作 DOM，但常用于在 DOM 渲染前安全获取 data.user.profile.name 形式的数据。

const data = { user: { name: 'TechUI' } };
const name = tQuery.valueByPath(data, 'user.name'); // "TechUI"
const age = tQuery.valueByPath(data, 'user.age', 18); // 18 (Fallback)

尺寸与自适应

tDom 是 TechUI 处理自适应布局的核心对象，它能识别元素是否处于 #tuiAdpt（自适应缩放面板）内部，并计算真实的物理坐标。

tDom.isInAdp(el)

判断一个元素是否位于自适应缩放容器 (#tuiAdpt) 内部。

if (tDom.isInAdp(myElement)) {
  console.log("当前元素处于缩放环境中");
}

tDom.rootInfo(el)

获取元素相对于浏览器视口 (Root) 以及自适应容器 (Adpt) 的详细布局信息。 此方法解决了在 transform: scale() 环境下，原生 getBoundingClientRect 数据换算困难的问题。

• 返回: 包含 rootWidth, isInAdp, 以及 A2RTop (Adaptive To Root Top) 等关键坐标偏移量。

const layout = tDom.rootInfo(el);
// layout.A2RLeft 表示自适应容器左边界距离视口的距离

syncContSize(options)

容器尺寸同步计算器。 用于计算“源元素”的几何属性，以便将这些属性应用到“目标元素”上（目前主要用于TuiAdaptive的同步容器的计算）。

• 参数:
  • source: 源 DOM 元素。
  • target: 目标 DOM 元素（注：源码中实际样式赋值已被注释，主要用于返回计算后的 Rect 对象）。
  • syncPosition: boolean，是否计算位置。
  • positionBaseTo: 'root' (基于视口) | 'parent' (基于父容器偏移)。
• 逻辑: 会自动判断 source 是否在自适应面板中，如果在，则使用 clientWidth 而非 rect.width 以避免缩放导致的尺寸偏差。

const rect = syncContSize({
  source: buttonEl,
  target: tooltipEl,
  syncPosition: true,
  positionBaseTo: 'root'
});
// rect: { width: 100, height: 40, left: 200, top: 300 }

模板解析

tCoreTpl(string)

一个极简的字符串模板解析函数。用于解析 [key]value 格式的特定配置字符串。（目前用于解析Wasm模块中的部分模板字符串）

const configStr = "[title]Hello TechUI[color]Blue";
const config = tCoreTpl(configStr);

console.log(config);
// 输出: { title: "Hello TechUI", color: "Blue" }