HumanBreak/docs/api/motajs-render-core/RenderItem.md

RenderItem 类 API 文档

需丰富

本文档由 DeepSeek R1 模型生成并微调。

---

继承关系

graph LR
    RenderItem --> EventEmitter

    click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"

---

接口说明

IRenderUpdater

interface IRenderUpdater {
    update(item?: RenderItem): void;
}

描述
定义元素更新能力的接口。RenderItem 通过 update 方法通知父元素需要重新渲染。

---

IRenderAnchor

interface IRenderAnchor {
    anchorX: number;
    anchorY: number;
    setAnchor(x: number, y: number): void;
}

描述
管理元素锚点的接口。锚点用于定位元素的渲染基准点（如中心点、左上角等）。

---

IRenderConfig

interface IRenderConfig {
    highResolution: boolean;
    antiAliasing: boolean;
    setHD(hd: boolean): void;
    setAntiAliasing(anti: boolean): void;
}

描述
管理画布渲染配置的接口，控制高清模式和抗锯齿的开关。

---

IRenderChildable

interface IRenderChildable {
    children: Set<RenderItem>;
    appendChild(...child: RenderItem[]): void;
    removeChild(...child: RenderItem[]): void;
    requestSort(): void;
}

描述
管理子元素的接口。需在子类中实现具体逻辑（如 Container 元素）。

属性说明

属性名	类型	默认值	说明
uid	number	自动递增	元素的唯一标识符
id	string	''	元素 ID（原则不可重复）
zIndex	number	0	元素的纵深层级（决定遮挡关系）
width	number	200	元素的逻辑宽度
height	number	200	元素的逻辑高度
anchorX	number	0	锚点横坐标（0 左端，1 右端）
anchorY	number	0	锚点纵坐标（0 上端，1 下端）
type	RenderItemPosition	'static'	渲染模式（absolute 绝对定位，static 跟随摄像机）
highResolution	boolean	true	是否启用高清画布
antiAliasing	boolean	true	是否启用抗锯齿
hidden	boolean	false	元素是否隐藏
filter	string	'none'	元素的滤镜效果
composite	GlobalCompositeOperation	'source-over'	渲染混合模式
alpha	number	1	元素的不透明度（0 透明，1 不透明）
cursor	string	'inherit'	鼠标悬停时的光标样式
noEvent	boolean	false	是否忽略交互事件
isRoot	boolean	false	是否为根元素（需实现 IRenderTreeRoot 接口）
connected	boolean	自动计算	元素是否已连接到根元素

特殊属性说明

• transform: 元素的变换矩阵（Transform 实例），修改时会自动触发 updateTransform。

---

构造方法

constructor(type: RenderItemPosition, enableCache: boolean = true, transformFallThrough: boolean = false)

参数

• type: 渲染模式（absolute 或 static）
• enableCache: 是否启用渲染缓存（默认启用）
• transformFallThrough: 是否启用变换矩阵下穿机制（默认关闭）

示例

const item = new RenderItem('absolute');

---

方法说明

size

function size(width: number, height: number): void;

描述
设置元素的尺寸。
示例

item.size(300, 200); // 设置宽度 300，高度 200

---

pos

function pos(x: number, y: number): void;

描述
设置元素的坐标（等效于修改 transform 的平移量）。
示例

item.pos(100, 50); // 设置坐标为 (100, 50)

---

append

function append(parent: RenderItem): void;

描述
将元素添加到指定父元素下。
示例

const parent = new RenderItem('static');
item.append(parent); // 将 item 添加为 parent 的子元素

---

remove

function remove(): boolean;

描述
从父元素中移除当前元素。
返回值

• true 表示移除成功，false 表示失败。
  示例

item.remove(); // 从父元素中移除

---

hide

function hide(): void;

描述
隐藏元素。
示例

item.hide(); // 隐藏元素

---

show

function show(): void;

描述
显示元素。
示例

item.show(); // 显示元素

---

delegateTicker

function delegateTicker(fn: TickerFn, time?: number, end?: () => void): number;

描述
委托动画帧函数，持续执行指定时间。
返回值

• 委托 ID，可用于移除。
  示例

const id = item.delegateTicker(() => {
    console.log('每帧执行');
}, 1000); // 持续 1 秒

---

destroy

function destroy(): void;

描述
销毁元素，释放资源。
示例

item.destroy(); // 销毁元素

getAbsolutePosition

function getAbsolutePosition(x?: number, y?: number): [number, number];

描述
获取元素在全局坐标系中的绝对坐标。
示例

const [absX, absY] = item.getAbsolutePosition(); // 获取元素原点绝对坐标

---

getBoundingRect

function getBoundingRect(): DOMRectReadOnly;

描述
获取元素的包围矩形（相对于父元素坐标系）。
示例

const rect = item.getBoundingRect();
console.log(rect.width, rect.height);

---

setZIndex

function setZIndex(zIndex: number): void;

描述
设置元素的纵深层级（zIndex 越大越靠前）。
示例

item.setZIndex(5); // 置顶显示

---

requestRenderFrame

function requestRenderFrame(fn: () => void): void;

描述
在下一帧渲染时执行函数（适用于需要在渲染流程中更新的操作）。
示例

item.requestRenderFrame(() => {
    item.pos(item.x + 1, item.y); // 每帧右移 1 单位
});

---

setFilter

function setFilter(filter: string): void;

描述
设置元素的 CSS 滤镜效果（如模糊、灰度等）。
示例

item.setFilter('blur(5px)'); // 添加模糊效果

---

受保护方法说明

render

protected abstract render(canvas: MotaOffscreenCanvas2D, transform: Transform): void;

描述
抽象渲染方法，子类必须实现此方法以定义具体渲染逻辑。
示例

class CustomItem extends RenderItem {
    protected render(canvas: MotaOffscreenCanvas2D) {
        canvas.ctx.fillStyle = 'red';
        canvas.ctx.fillRect(0, 0, this.width, this.height);
    }
}

---

isActionInElement

protected isActionInElement(x: number, y: number): boolean;

描述
判断坐标点是否在元素范围内（可覆盖实现自定义碰撞检测）。
默认行为
检测坐标是否在 [0, width] x [0, height] 矩形内。

---

静态方法说明

RenderItem.ticker

类型

const ticker: Ticker;

描述
全局动画帧管理器，用于处理所有委托的动画帧函数。

---

事件说明

事件继承自 ERenderItemActionEvent

事件名	参数类型	说明
beforeRender	Transform	渲染前触发
afterRender	Transform	渲染后触发
destroy	[]	元素销毁时触发
transform	[RenderItem, Transform]	变换矩阵更新时触发

---

总使用示例

::: code-group

// 创建元素（以 Sprite 为例）
const item = new Sprite('static');

// 设置属性
item.size(400, 300);
item.pos(100, 50);
item.setAnchor(0.5, 0.5); // 设置中心锚点
item.setZIndex(2);

// 监听渲染事件
item.on('beforeRender', transform => {
    console.log('即将渲染，变换矩阵:', transform);
});

// 添加动画效果
const tickerId = item.delegateTicker(time => {
    item.pos(Math.sin(time / 1000) * 100, 50);
});

// 销毁元素
setTimeout(() => {
    item.destroy();
}, 5000);

// 创建自定义可交互元素
class Button extends RenderItem {
    constructor() {
        super('static');
        this.size(100, 40);
        this.on('click', ev => {
            console.log('按钮被点击！坐标:', ev.offsetX, ev.offsetY);
        });
    }

    protected render(canvas: MotaOffscreenCanvas2D) {
        // 绘制圆角矩形按钮
        const ctx = canvas.ctx;
        ctx.fillStyle = '#4CAF50';
        ctx.roundRect(0, 0, this.width, this.height, 8);
        ctx.fill();
    }
}

// 使用按钮
const button = new Button();
button.pos(200, 150);
button.append(parentElement);

// 添加鼠标悬停效果
button.on('enter', () => button.setFilter('brightness(1.2)'));
button.on('leave', () => button.setFilter('none'));

:::

RenderItem 类 API 文档（补充部分）

本文档由 DeepSeek R1 模型生成并微调。

---