初始化提交

2025-10-03 16:49:53 +08:00
parent 157ca32e2d
commit bdd67a65fa
1066 changed files with 373311 additions and 261 deletions
--- a/guide/essentials/elements.md
+++ b/guide/essentials/elements.md
@@ -0,0 +1,303 @@
+# 元素系统
+
+PE引擎提供了丰富的内置元素类型，让你能够快速创建各种UI组件和视觉元素。元素是构成PE应用界面的基本单位。
+
+## 元素类型概览
+
+PE引擎目前支持以下几种内置元素类型：
+
+1. **Sprite（精灵）** - 用于显示图像或创建基本图形
+2. **Box（盒子）** - 用于创建矩形区域
+3. **Text（文本）** - 用于显示文本内容
+4. **HTML** - 用于嵌入原生HTML内容
+5. **SVG** - 用于创建矢量图形
+
+## 创建元素
+
+在PE中，所有元素都通过应用实例的`create`方法创建：
+
+```javascript
+// 通用创建方法
+const element = game.create(type, options)
+```
+
+### Sprite（精灵）
+
+Sprite是最常用的元素类型，可以用来显示图像或创建基本图形。
+
+```javascript
+// 创建一个默认的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组件。
+
+```javascript
+// 创建一个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元素用于显示文本内容。
+
+```javascript
+// 创建文本元素
+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内容。
+
+```javascript
+// 创建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元素用于创建矢量图形。
+
+```javascript
+// 创建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元素都有一些通用的方法和属性：
+
+### 位置和尺寸
+
+```javascript
+// 设置位置
+element.setPosition(100, 200)
+
+// 设置尺寸
+element.setSize(300, 150)
+
+// 获取位置
+const x = element.getX()
+const y = element.getY()
+
+// 获取尺寸
+const width = element.getWidth()
+const height = element.getHeight()
+```
+
+### 样式操作
+
+```javascript
+// 设置单个样式属性
+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')) {
+  // 执行相应操作
+}
+```
+
+### 显示和隐藏
+
+```javascript
+// 隐藏元素
+element.hide()
+
+// 显示元素
+element.show()
+
+// 切换显示状态
+element.toggle()
+```
+
+## 在场景模板中使用元素
+
+在PE的场景系统中，你也可以直接在模板中定义元素：
+
+```html
+<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）：
+
+```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元素支持丰富的事件处理：
+
+```javascript
+// 添加点击事件
+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>
+```
+
+## 自定义元素
+
+除了内置元素，你还可以创建自定义元素：
+
+```javascript
+// 创建自定义元素类
+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引擎的元素系统。在下一章节中，我们将深入探讨场景系统的使用。