Pandona-Engine/guide/essentials/elements.md

元素系统

PE引擎提供了丰富的内置元素类型，让你能够快速创建各种UI组件和视觉元素。元素是构成PE应用界面的基本单位。

元素类型概览

PE引擎目前支持以下几种内置元素类型：

1. Sprite（精灵） - 用于显示图像或创建基本图形
2. Box（盒子） - 用于创建矩形区域
3. Text（文本） - 用于显示文本内容
4. HTML - 用于嵌入原生HTML内容
5. SVG - 用于创建矢量图形

创建元素

在PE中，所有元素都通过应用实例的create方法创建：

// 通用创建方法
const element = game.create(type, options)

Sprite（精灵）

Sprite是最常用的元素类型，可以用来显示图像或创建基本图形。

// 创建一个默认的sprite
const sprite = game.create('sprite')

// 创建带配置的sprite
const spriteWithConfig = game.create('sprite', {
  x: 100,
  y: 100,
  width: 50,
  height: 50
})

// 设置位置和尺寸
sprite.setPosition(200, 200)
sprite.setSize(100, 100)

// 添加样式
sprite.element.style.backgroundColor = '#3498db'
sprite.element.style.borderRadius = '50%'

Box（盒子）

Box元素用于创建矩形区域，常用于创建按钮、面板等UI组件。

// 创建一个box
const box = game.create('box', {
  x: 100,
  y: 100,
  width: 200,
  height: 100
})

// Box元素的DOM元素可以直接操作样式
box.element.style.backgroundColor = '#e74c3c'
box.element.style.borderRadius = '8px'

Text（文本）

Text元素用于显示文本内容。

// 创建文本元素
const text = game.create('text', {
  text: 'Hello PE!',
  x: 100,
  y: 100
})

// 更新文本内容
text.setText('新的文本内容')

// 设置文本样式
text.element.style.color = '#ffffff'
text.element.style.fontSize = '24px'
text.element.style.fontWeight = 'bold'

HTML元素

HTML元素允许你嵌入原生HTML内容。

// 创建HTML元素
const htmlElement = game.create('html', {
  html: '<div class="custom-html">这是HTML内容</div>',
  x: 100,
  y: 100
})

// 更新HTML内容
htmlElement.setHtml('<div class="updated-html">更新的内容</div>')

SVG元素

SVG元素用于创建矢量图形。

// 创建SVG元素
const svgElement = game.create('svg', {
  x: 100,
  y: 100,
  width: 200,
  height: 200,
  content: '<circle cx="100" cy="100" r="50" fill="#3498db" />'
})

元素的通用方法和属性

所有PE元素都有一些通用的方法和属性：

位置和尺寸

// 设置位置
element.setPosition(100, 200)

// 设置尺寸
element.setSize(300, 150)

// 获取位置
const x = element.getX()
const y = element.getY()

// 获取尺寸
const width = element.getWidth()
const height = element.getHeight()

样式操作

// 设置单个样式属性
element.setStyle('backgroundColor', '#3498db')

// 设置多个样式属性
element.setStyles({
  backgroundColor: '#3498db',
  borderRadius: '8px',
  border: '2px solid #2980b9'
})

// 添加CSS类
element.addClass('my-class')

// 移除CSS类
element.removeClass('my-class')

// 检查是否包含CSS类
if (element.hasClass('my-class')) {
  // 执行相应操作
}

显示和隐藏

// 隐藏元素
element.hide()

// 显示元素
element.show()

// 切换显示状态
element.toggle()

在场景模板中使用元素

在PE的场景系统中，你也可以直接在模板中定义元素：

<sence>
  <!-- 使用sprite元素 -->
  <sprite class="player" x="100" y="100" width="50" height="50"></sprite>
  
  <!-- 使用box元素 -->
  <box class="panel" x="200" y="200" width="300" height="200">面板内容</box>
  
  <!-- 使用text元素 -->
  <text class="title" x="100" y="50">欢迎使用PE引擎</text>
  
  <!-- 使用循环创建多个元素 -->
  <box for="{item} in menuItems" 
       class="menu-item" 
       x="{item.x}" 
       y="{item.y}"
       @click="handleMenuClick(item.id)">
    {{ item.label }}
  </box>
</sence>

对应的样式文件（.less）：

.player {
  background-color: #3498db;
  border-radius: 50%;
  transition: all 0.3s ease;
}

.player:hover {
  transform: scale(1.1);
}

.panel {
  background-color: #ecf0f1;
  border: 2px solid #bdc3c7;
  border-radius: 8px;
  display: flex;
  align-items: center;
  justify-content: center;
}

.title {
  color: #2c3e50;
  font-size: 24px;
  font-weight: bold;
}

.menu-item {
  width: 150px;
  height: 40px;
  background-color: #e74c3c;
  color: white;
  display: flex;
  align-items: center;
  justify-content: center;
  border-radius: 4px;
  cursor: pointer;
  margin: 5px 0;
}

元素的事件处理

PE元素支持丰富的事件处理：

// 添加点击事件
element.element.addEventListener('click', (event) => {
  console.log('元素被点击了')
})

// 添加鼠标移入事件
element.element.addEventListener('mouseenter', (event) => {
  element.setStyle('backgroundColor', '#e74c3c')
})

// 添加鼠标移出事件
element.element.addEventListener('mouseleave', (event) => {
  element.setStyle('backgroundColor', '#3498db')
})

// 在场景模板中直接绑定事件
// <box @click="handleClick" @mouseenter="handleMouseEnter">点击我</box>

自定义元素

除了内置元素，你还可以创建自定义元素：

// 创建自定义元素类
class CustomElement extends BaseElement {
  constructor(x, y, width, height, engineId) {
    super(x, y, width, height, engineId)
    
    // 初始化自定义元素
    this.element.style.backgroundColor = '#9b59b6'
    this.element.style.borderRadius = '10px'
  }
  
  // 自定义方法
  animateColor() {
    const colors = ['#9b59b6', '#3498db', '#e74c3c', '#2ecc71']
    let index = 0
    
    setInterval(() => {
      this.element.style.backgroundColor = colors[index % colors.length]
      index++
    }, 1000)
  }
}

// 注册自定义元素
// 在场景中使用
// <custom-element x="100" y="100" width="100" height="100"></custom-element>

通过以上内容，你已经了解了PE引擎的元素系统。在下一章节中，我们将深入探讨场景系统的使用。