165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
# DOM 渲染引擎
|
||
|
||
这个轻量级 JavaScript 渲染引擎使用 DOM 元素创建 2D 场景，支持精灵、容器、文本、HTML 和 SVG 等元素，提供简单直观的 API 进行场景管理。
|
||
|
||
## 功能特性
|
||
|
||
- 🎭 创建可自定义尺寸的舞台容器
|
||
- 🖼️ 支持加载和显示图像精灵
|
||
- 📦 创建容器元素用于分组管理
|
||
- ✏️ 文本元素创建和样式设置
|
||
- 🌐 支持原生 HTML 内容嵌入
|
||
- 🎨 SVG 矢量图形支持
|
||
- 📍 精确控制元素位置和尺寸
|
||
- 🎭 简单的事件绑定机制
|
||
|
||
## 快速开始
|
||
|
||
### 基本用法
|
||
|
||
```javascript
|
||
// 创建引擎实例
|
||
const game = new Engine('#game-container', {
|
||
width: 800,
|
||
height: 600,
|
||
background: '#f0f0f0'
|
||
});
|
||
|
||
// 加载资源
|
||
game.Load('character.png')
|
||
.then(img => {
|
||
// 创建精灵
|
||
const player = game.CreateSprite(img, 100, 100, 50, 50);
|
||
|
||
// 添加到舞台
|
||
game.stage.add(player);
|
||
|
||
// 绑定点击事件
|
||
player.on('click', () => {
|
||
player.setPosition(200, 150);
|
||
});
|
||
});
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### 引擎初始化
|
||
```javascript
|
||
const engine = new Engine(elementSelector, options);
|
||
```
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|---------|------|
|
||
| `elementSelector` | string | `'body'` | 挂载舞台的 DOM 选择器 |
|
||
| `options.width` | number | 800 | 舞台宽度(px) |
|
||
| `options.height` | number | 600 | 舞台高度(px) |
|
||
| `options.background` | string | `'transparent'` | 舞台背景色 |
|
||
|
||
### 资源加载
|
||
```javascript
|
||
engine.Load(imageUrl)
|
||
.then(img => { /* 使用图像 */ })
|
||
.catch(error => { /* 处理错误 */ });
|
||
```
|
||
|
||
### 创建元素
|
||
|
||
#### 精灵 (CreateSprite)
|
||
```javascript
|
||
const sprite = engine.CreateSprite(imgElement, x, y, width, height);
|
||
```
|
||
- 支持位置和尺寸控制
|
||
- 支持事件绑定
|
||
|
||
#### 容器 (CreateBox)
|
||
```javascript
|
||
const container = engine.CreateBox(x, y, width, height);
|
||
```
|
||
- 用于元素分组管理
|
||
- 支持嵌套结构
|
||
|
||
#### 文本 (CreateText)
|
||
```javascript
|
||
const text = engine.CreateText('Hello', 50, 50);
|
||
text.setColor('#ff0000');
|
||
text.setFont('bold 24px Arial');
|
||
```
|
||
|
||
#### HTML 元素 (CreateHtml)
|
||
```javascript
|
||
const html = engine.CreateHtml('<button>Click</button>', 300, 200);
|
||
```
|
||
|
||
#### SVG 元素 (CreateSvg)
|
||
```javascript
|
||
const svg = engine.CreateSvg(400, 300, 100, 100, '<circle cx="50" cy="50" r="40"/>');
|
||
```
|
||
|
||
### 元素通用方法
|
||
所有创建的元素支持以下方法：
|
||
|
||
| 方法 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `setPosition(x, y)` | 设置元素位置 | `sprite.setPosition(150, 200)` |
|
||
| `setSize(width, height)` | 设置元素尺寸 | `box.setSize(100, 80)` |
|
||
| `setStyle(cssText)` | 添加自定义样式 | `text.setStyle('opacity: 0.8;')` |
|
||
| `add(child)` | 添加子元素 | `container.add(sprite)` |
|
||
| `remove(child)` | 移除子元素 | `container.remove(sprite)` |
|
||
| `on(event, callback)` | 绑定事件 | `sprite.on('click', handleClick)` |
|
||
| `off(event, callback)` | 解绑事件 | `sprite.off('click', handleClick)` |
|
||
| `hide()` | 隐藏元素 | `sprite.hide()` |
|
||
| `show()` | 显示元素 | `sprite.show()` |
|
||
|
||
### 销毁引擎
|
||
```javascript
|
||
engine.Destroy();
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 创建游戏角色
|
||
```javascript
|
||
const game = new Engine('#game', {
|
||
width: 1024,
|
||
height: 768
|
||
});
|
||
|
||
game.Load('player.png').then(playerImg => {
|
||
const player = game.CreateSprite(playerImg, 512, 384, 64, 64);
|
||
|
||
// 添加角色名标签
|
||
const nameTag = game.CreateText('Player 1', 0, -20);
|
||
nameTag.setColor('gold');
|
||
nameTag.setFont('bold 14px sans-serif');
|
||
|
||
player.add(nameTag);
|
||
game.stage.add(player);
|
||
});
|
||
```
|
||
|
||
### 创建 UI 面板
|
||
```javascript
|
||
const panel = game.CreateBox(50, 50, 200, 300);
|
||
panel.setStyle('background: rgba(0,0,0,0.7); border-radius: 10px;');
|
||
|
||
const title = game.CreateText('控制面板', 20, 20);
|
||
title.setStyle('font-size: 20px; color: white;');
|
||
|
||
const button = game.CreateHtml(
|
||
'<button style="padding: 8px 16px; background: blue; color: white;">开始</button>',
|
||
50, 80
|
||
);
|
||
|
||
panel.add(title);
|
||
panel.add(button);
|
||
game.stage.add(panel);
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 所有元素位置基于舞台左上角(0,0)计算
|
||
2. 使用 `Destroy()` 方法会完全移除舞台并清理内存
|
||
3. 图像元素自动添加 `user-drag: none` 防止拖动
|
||
4. 舞台默认启用硬件加速 (`transform: translateZ(0)`)
|
||
5. 每个引擎实例有唯一ID标识 (`data-engine-id`)
|
||
|
||
这个轻量级引擎适合创建简单的 2D 界面和游戏原型，使用原生 DOM 操作，无需额外依赖。 |