元素 API

tui-entine 元素提供了一系列方法，用于操作元素树、处理事件和获取元素信息。

appendChild

添加子元素到当前元素。

appendChild(...spreadChild : ITuiElement[]) : void

参数：

• ...spreadChild: ITuiElement[] - 要添加的子元素数组

示例：

const parent = engine.createView();
const child1 = engine.createView();
const child2 = engine.createView();

parent.appendChild(child1, child2);

prependChild

在当前元素的子元素列表开头添加子元素。

prependChild(...spreadChild : ITuiElement[]) : void

参数：

• ...spreadChild: ITuiElement[] - 要添加的子元素数组

示例：

const parent = engine.createView();
const child1 = engine.createView();
const child2 = engine.createView();

parent.prependChild(child1);
parent.appendChild(child2);
// 结果：child1 在 child2 前面

removeChild

从当前元素中移除子元素。

removeChild(child : ITuiElement) : ITuiElement

参数：

• child: ITuiElement - 要移除的子元素

返回值： ITuiElement - 被移除的元素

示例：

const removed = parent.removeChild(child);
console.log("已移除元素:", removed.id);

insertBefore

在指定子元素前插入新元素。

insertBefore(newNode : ITuiElement, referenceNode : ITuiElement | null) : ITuiElement

参数：

• newNode: ITuiElement - 要插入的新元素
• referenceNode: ITuiElement | null - 参考元素，新元素将插入到该元素之前

返回值： ITuiElement - 插入的新元素

示例：

const newElement = engine.createView();
parent.insertBefore(newElement, existingElement);

replaceChild

用新元素替换现有子元素。

replaceChild(newChild : ITuiElement, oldChild : ITuiElement) : ITuiElement

参数：

• newChild: ITuiElement - 新元素
• oldChild: ITuiElement - 要替换的旧元素

返回值： ITuiElement - 被替换的旧元素

示例：

const newElement = engine.createView();
const oldElement = parent.firstChild;
if (oldElement) {
  parent.replaceChild(newElement, oldElement);
}

addEventListener

为元素添加事件监听器。

addEventListener(type : string, listener : (event : ITuiTouchEvent) => void) : number

参数：

• type: string - 事件类型（'touchstart', 'touchmove', 'touchend', 'click'）
• listener: (event : ITuiTouchEvent) => void - 事件处理函数

返回值： number - 事件监听器 ID

示例：

const listenerId = element.addEventListener("click", (event) => {
  console.log("元素被点击", event.clientX, event.clientY);
});

removeEventListener

移除元素的事件监听器。

removeEventListener(listener : number) : void

参数：

• listener: number - 事件监听器 ID

示例：

element.removeEventListener(listenerId);

getBoundingClientRect

获取元素的位置和尺寸信息。

getBoundingClientRect() : TuiDOMRect

返回值： TuiDOMRect - 元素位置信息，包含以下属性：

• width: number - 元素宽度
• height: number - 元素高度
• x: number - 元素左上角 X 坐标
• y: number - 元素左上角 Y 坐标
• left: number - 元素左边界 X 坐标
• right: number - 元素右边界 X 坐标
• top: number - 元素上边界 Y 坐标
• bottom: number - 元素下边界 Y 坐标

示例：

const rect = element.getBoundingClientRect();
console.log("元素位置:", rect.x, rect.y);
console.log("元素尺寸:", rect.width, rect.height);

getAttribute

获取元素的属性值。

getAttribute(name : string) : string | null

参数：

• name: string - 属性名

返回值： string | null - 属性值，不存在返回 null

示例：

const value = element.getAttribute("id");
console.log("元素ID:", value);

setAttribute

设置元素的属性值。

setAttribute(name : string, value : string) : void

参数：

• name: string - 属性名
• value: string - 属性值

示例：

element.setAttribute("id", "my-element");
element.setAttribute("class", "container");

removeAttribute

移除元素的属性。

removeAttribute(name : string) : void

参数：

• name: string - 属性名

示例：

element.removeAttribute("class");

hasAttribute

检查元素是否有指定属性。

hasAttribute(name : string) : boolean

参数：

• name: string - 属性名

返回值： boolean - 是否有指定属性

示例：

if (element.hasAttribute("id")) {
  console.log("元素有ID属性");
}

querySelector

通过选择器获取第一个匹配的子元素。

querySelector(selector : string) : ITuiElement | null

参数：

• selector: string - 选择器

返回值： ITuiElement | null - 找到的元素，未找到返回 null

示例：

const child = element.querySelector(".container");
if (child) {
  console.log("找到容器元素");
}

querySelectorAll

通过选择器获取所有匹配的子元素。

querySelectorAll(selector : string) : ITuiElement[]

参数：

• selector: string - 选择器

返回值： ITuiElement[] - 找到的元素数组

示例：

const children = element.querySelectorAll(".item");
console.log("找到", children.length, "个项目");

cloneNode

克隆元素。

cloneNode(deep ?: boolean) : ITuiElement

参数：

• deep: boolean - 是否深度克隆，默认为 false

返回值： ITuiElement - 克隆的元素

示例：

// 浅克隆（只克隆元素本身）
const clone = element.cloneNode();

// 深克隆（克隆元素及其所有子元素）
const deepClone = element.cloneNode(true);

setStyles

设置元素的样式。

setStyles(e : UTSJSONObject) : void

参数：

• e: UTSJSONObject - 样式对象

示例：

element.setStyles({
  width: 100,
  height: 100,
  backgroundColor: "#f0f0f0",
});

生命周期方法

connectedCallback

元素被添加到元素树时调用。

connectedCallback() : void

示例：

// 自定义元素类中重写
class MyElement extends TuiElement {
  connectedCallback() {
    console.log("元素被添加到树中");
  }
}

disconnectedCallback

元素从元素树中移除时调用。

disconnectedCallback() : void

示例：

class MyElement extends TuiElement {
  disconnectedCallback() {
    console.log("元素从树中移除");
  }
}

adoptedCallback

元素被收养到新文档时调用。

adoptedCallback() : void

示例：

class MyElement extends TuiElement {
  adoptedCallback() {
    console.log("元素被收养到新文档");
  }
}

attributeChangedCallback

元素属性变化时调用。

attributeChangedCallback(name : string, oldValue ?: string, newValue ?: string) : void

参数：

• name: string - 属性名
• oldValue: string | undefined - 旧值
• newValue: string | undefined - 新值

示例：

class MyElement extends TuiElement {
  attributeChangedCallback(name, oldValue, newValue) {
    console.log(`属性 ${name} 从 ${oldValue} 变为 ${newValue}`);
  }
}