mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-31 04:02:59 +08:00
478 lines
11 KiB
Markdown
478 lines
11 KiB
Markdown
# RenderItem 类 API 文档
|
||
|
||
**需丰富**
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
---
|
||
|
||
## 继承关系
|
||
|
||
```mermaid
|
||
graph LR
|
||
RenderItem --> EventEmitter
|
||
|
||
click EventEmitter "https://nodejs.org/api/events.html#class-eventemitter"
|
||
```
|
||
|
||
---
|
||
|
||
## 接口说明
|
||
|
||
### IRenderUpdater
|
||
|
||
```typescript
|
||
interface IRenderUpdater {
|
||
update(item?: RenderItem): void;
|
||
}
|
||
```
|
||
|
||
**描述**
|
||
定义元素更新能力的接口。`RenderItem` 通过 `update` 方法通知父元素需要重新渲染。
|
||
|
||
---
|
||
|
||
### IRenderAnchor
|
||
|
||
```typescript
|
||
interface IRenderAnchor {
|
||
anchorX: number;
|
||
anchorY: number;
|
||
setAnchor(x: number, y: number): void;
|
||
}
|
||
```
|
||
|
||
**描述**
|
||
管理元素锚点的接口。锚点用于定位元素的渲染基准点（如中心点、左上角等）。
|
||
|
||
---
|
||
|
||
### IRenderConfig
|
||
|
||
```typescript
|
||
interface IRenderConfig {
|
||
highResolution: boolean;
|
||
antiAliasing: boolean;
|
||
setHD(hd: boolean): void;
|
||
setAntiAliasing(anti: boolean): void;
|
||
}
|
||
```
|
||
|
||
**描述**
|
||
管理画布渲染配置的接口，控制高清模式和抗锯齿的开关。
|
||
|
||
---
|
||
|
||
### IRenderChildable
|
||
|
||
```typescript
|
||
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`: 是否启用变换矩阵下穿机制（默认关闭）
|
||
|
||
**示例**
|
||
|
||
```typescript
|
||
const item = new RenderItem('absolute');
|
||
```
|
||
|
||
---
|
||
|
||
## 方法说明
|
||
|
||
### `size`
|
||
|
||
```typescript
|
||
function size(width: number, height: number): void;
|
||
```
|
||
|
||
**描述**
|
||
设置元素的尺寸。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.size(300, 200); // 设置宽度 300，高度 200
|
||
```
|
||
|
||
---
|
||
|
||
### `pos`
|
||
|
||
```typescript
|
||
function pos(x: number, y: number): void;
|
||
```
|
||
|
||
**描述**
|
||
设置元素的坐标（等效于修改 `transform` 的平移量）。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.pos(100, 50); // 设置坐标为 (100, 50)
|
||
```
|
||
|
||
---
|
||
|
||
### `append`
|
||
|
||
```typescript
|
||
function append(parent: RenderItem): void;
|
||
```
|
||
|
||
**描述**
|
||
将元素添加到指定父元素下。
|
||
**示例**
|
||
|
||
```typescript
|
||
const parent = new RenderItem('static');
|
||
item.append(parent); // 将 item 添加为 parent 的子元素
|
||
```
|
||
|
||
---
|
||
|
||
### `remove`
|
||
|
||
```typescript
|
||
function remove(): boolean;
|
||
```
|
||
|
||
**描述**
|
||
从父元素中移除当前元素。
|
||
**返回值**
|
||
|
||
- `true` 表示移除成功，`false` 表示失败。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.remove(); // 从父元素中移除
|
||
```
|
||
|
||
---
|
||
|
||
### `hide`
|
||
|
||
```typescript
|
||
function hide(): void;
|
||
```
|
||
|
||
**描述**
|
||
隐藏元素。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.hide(); // 隐藏元素
|
||
```
|
||
|
||
---
|
||
|
||
### `show`
|
||
|
||
```typescript
|
||
function show(): void;
|
||
```
|
||
|
||
**描述**
|
||
显示元素。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.show(); // 显示元素
|
||
```
|
||
|
||
---
|
||
|
||
### `delegateTicker`
|
||
|
||
```typescript
|
||
function delegateTicker(fn: TickerFn, time?: number, end?: () => void): number;
|
||
```
|
||
|
||
**描述**
|
||
委托动画帧函数，持续执行指定时间。
|
||
**返回值**
|
||
|
||
- 委托 ID，可用于移除。
|
||
**示例**
|
||
|
||
```typescript
|
||
const id = item.delegateTicker(() => {
|
||
console.log('每帧执行');
|
||
}, 1000); // 持续 1 秒
|
||
```
|
||
|
||
---
|
||
|
||
### `destroy`
|
||
|
||
```typescript
|
||
function destroy(): void;
|
||
```
|
||
|
||
**描述**
|
||
销毁元素，释放资源。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.destroy(); // 销毁元素
|
||
```
|
||
|
||
### `getAbsolutePosition`
|
||
|
||
```typescript
|
||
function getAbsolutePosition(x?: number, y?: number): [number, number];
|
||
```
|
||
|
||
**描述**
|
||
获取元素在全局坐标系中的绝对坐标。
|
||
**示例**
|
||
|
||
```typescript
|
||
const [absX, absY] = item.getAbsolutePosition(); // 获取元素原点绝对坐标
|
||
```
|
||
|
||
---
|
||
|
||
### `getBoundingRect`
|
||
|
||
```typescript
|
||
function getBoundingRect(): DOMRectReadOnly;
|
||
```
|
||
|
||
**描述**
|
||
获取元素的包围矩形（相对于父元素坐标系）。
|
||
**示例**
|
||
|
||
```typescript
|
||
const rect = item.getBoundingRect();
|
||
console.log(rect.width, rect.height);
|
||
```
|
||
|
||
---
|
||
|
||
### `setZIndex`
|
||
|
||
```typescript
|
||
function setZIndex(zIndex: number): void;
|
||
```
|
||
|
||
**描述**
|
||
设置元素的纵深层级（`zIndex` 越大越靠前）。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.setZIndex(5); // 置顶显示
|
||
```
|
||
|
||
---
|
||
|
||
### `requestRenderFrame`
|
||
|
||
```typescript
|
||
function requestRenderFrame(fn: () => void): void;
|
||
```
|
||
|
||
**描述**
|
||
在下一帧渲染时执行函数（适用于需要在渲染流程中更新的操作）。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.requestRenderFrame(() => {
|
||
item.pos(item.x + 1, item.y); // 每帧右移 1 单位
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### `setFilter`
|
||
|
||
```typescript
|
||
function setFilter(filter: string): void;
|
||
```
|
||
|
||
**描述**
|
||
设置元素的 CSS 滤镜效果（如模糊、灰度等）。
|
||
**示例**
|
||
|
||
```typescript
|
||
item.setFilter('blur(5px)'); // 添加模糊效果
|
||
```
|
||
|
||
---
|
||
|
||
## 受保护方法说明
|
||
|
||
### `render`
|
||
|
||
```typescript
|
||
protected abstract render(canvas: MotaOffscreenCanvas2D, transform: Transform): void;
|
||
```
|
||
|
||
**描述**
|
||
抽象渲染方法，子类必须实现此方法以定义具体渲染逻辑。
|
||
**示例**
|
||
|
||
```typescript
|
||
class CustomItem extends RenderItem {
|
||
protected render(canvas: MotaOffscreenCanvas2D) {
|
||
canvas.ctx.fillStyle = 'red';
|
||
canvas.ctx.fillRect(0, 0, this.width, this.height);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `isActionInElement`
|
||
|
||
```typescript
|
||
protected isActionInElement(x: number, y: number): boolean;
|
||
```
|
||
|
||
**描述**
|
||
判断坐标点是否在元素范围内（可覆盖实现自定义碰撞检测）。
|
||
**默认行为**
|
||
检测坐标是否在 `[0, width] x [0, height]` 矩形内。
|
||
|
||
---
|
||
|
||
## 静态方法说明
|
||
|
||
### `RenderItem.ticker`
|
||
|
||
**类型**
|
||
|
||
```typescript
|
||
const ticker: Ticker;
|
||
```
|
||
|
||
**描述**
|
||
全局动画帧管理器，用于处理所有委托的动画帧函数。
|
||
|
||
---
|
||
|
||
## 事件说明
|
||
|
||
事件继承自 [ERenderItemActionEvent](./Event.md#erenderitemactionevent)
|
||
|
||
| 事件名 | 参数类型 | 说明 |
|
||
| -------------- | ------------------------- | ------------------ |
|
||
| `beforeRender` | `Transform` | 渲染前触发 |
|
||
| `afterRender` | `Transform` | 渲染后触发 |
|
||
| `destroy` | `[]` | 元素销毁时触发 |
|
||
| `transform` | `[RenderItem, Transform]` | 变换矩阵更新时触发 |
|
||
|
||
---
|
||
|
||
## 总使用示例
|
||
|
||
::: code-group
|
||
|
||
```typescript [基础操作]
|
||
// 创建元素（以 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);
|
||
```
|
||
|
||
```typescript [创建自定义元素]
|
||
// 创建自定义可交互元素
|
||
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` 模型生成并微调。
|
||
|
||
---
|