cssEngine/README.md

DOM 渲染引擎

这个轻量级 JavaScript 渲染引擎使用 DOM 元素创建 2D 场景，支持精灵、容器、文本、HTML 和 SVG 等元素，提供简单直观的 API 进行场景管理。

功能特性

• 🎭 创建可自定义尺寸的舞台容器
• 🖼️ 支持加载和显示图像精灵
• 📦 创建容器元素用于分组管理
• ✏️ 文本元素创建和样式设置
• 🌐 支持原生 HTML 内容嵌入
• 🎨 SVG 矢量图形支持
• 📍 精确控制元素位置和尺寸
• 🎭 简单的事件绑定机制

快速开始

基本用法

// 创建引擎实例
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 参考

引擎初始化

const engine = new Engine(elementSelector, options);

参数	类型	默认值	说明
elementSelector	string	'body'	挂载舞台的 DOM 选择器
options.width	number	800	舞台宽度(px)
options.height	number	600	舞台高度(px)
options.background	string	'transparent'	舞台背景色

资源加载

engine.Load(imageUrl)
  .then(img => { /* 使用图像 */ })
  .catch(error => { /* 处理错误 */ });

创建元素

精灵 (CreateSprite)

const sprite = engine.CreateSprite(imgElement, x, y, width, height);

• 支持位置和尺寸控制
• 支持事件绑定

容器 (CreateBox)

const container = engine.CreateBox(x, y, width, height);

• 用于元素分组管理
• 支持嵌套结构

文本 (CreateText)

const text = engine.CreateText('Hello', 50, 50);
text.setColor('#ff0000');
text.setFont('bold 24px Arial');

HTML 元素 (CreateHtml)

const html = engine.CreateHtml('<button>Click</button>', 300, 200);

SVG 元素 (CreateSvg)

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()

销毁引擎

engine.Destroy();

使用示例

创建游戏角色

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 面板

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 操作，无需额外依赖。