场景框

admin

# 场景框.js 详细使用文档

## 概述

场景框是一个基于 PixiJS 的可视化编辑容器，提供了丰富的交互功能，包括对象选择、移动、缩放、对齐等。它适用于构建可视化编辑器、设计工具或交互式应用程序。

## 基本用法

### 初始化

```javascript
// 创建场景框实例
var 我的场景框 = new 场景框();

// 初始化场景框
我的场景框.初始化(x, y, 宽度, 高度, 选项);

// 添加到 PixiJS 应用
pixiApp.stage.addChild(我的场景框.容器);
```

### 初始化参数

- `x`: 场景框 X 坐标
- `y`: 场景框 Y 坐标
- `宽度`: 场景框宽度
- `高度`: 场景框高度
- `选项`: 配置选项对象

### 配置选项

```javascript
{
    // 调试相关
    调试模式: true,                // 是否显示调试信息

    // 舞台相关
    舞台宽度: 2000,               // 舞台宽度
    舞台高度: 1500,               // 舞台高度
    舞台背景颜色: 0xFFFFFF,       // 舞台背景颜色
    舞台边框颜色: 0xCCCCCC,       // 舞台边框颜色
    舞台边框宽度: 1,              // 舞台边框宽度

    // 网格相关
    显示网格: true,               // 是否显示网格
    网格大小: 20,                 // 网格大小
    网格颜色: 0xCCCCCC,           // 网格颜色
    网格透明度: 0.3,              // 网格透明度

    // 选中相关
    显示选中边框: true,           // 是否显示选中边框
    选中边框颜色: 0x4A90E2,       // 选中边框颜色
    选中边框宽度: 2,              // 选中边框宽度
    选中边框透明度: 1.0,          // 选中边框透明度
    选中边框虚线: [5, 5],         // 选中边框虚线样式
    选中背景颜色: 0x4A90E2,       // 选中背景颜色
    选中背景透明度: 0.1,          // 选中背景透明度

    // 控制点相关
    显示控制点: true,             // 是否显示控制点
    控制点颜色: 0x4A90E2,         // 控制点颜色
    控制点大小: 8,                // 控制点大小

    // 框选相关
    选中框选边框颜色: 0x4A90E2,   // 框选边框颜色
    选中框选边框宽度: 1,          // 框选边框宽度
    选中框选边框透明度: 1.0,      // 框选边框透明度
    选中颜色: 0x4A90E2,           // 框选区域颜色
    选中透明度: 0.1,              // 框选区域透明度

    // 缩放相关
    缩放最小值: 0.1,              // 最小缩放比例
    缩放最大值: 5.0,              // 最大缩放比例
    缩放速度: 0.1,                // 缩放速度

    // 对齐相关
    启用对齐: true,               // 是否启用对齐功能
    对齐距离: 5,                  // 对齐吸附距离
    对齐线颜色: 0xFF0000,         // 对齐线颜色
    对齐线宽度: 1,                // 对齐线宽度
    对齐线透明度: 0.8             // 对齐线透明度
}
```

## 核心功能

### 对象管理

```javascript
// 添加对象
var 对象 = 我的场景框.添加对象(显示对象, x, y);

// 删除对象
我的场景框.删除对象(对象);

// 获取所有对象
var 所有对象 = 我的场景框.获取所有对象();

// 获取对象容器
var 对象容器 = 我的场景框.获取对象容器();
```

### 选择操作

```javascript
// 全选
我的场景框.全选();

// 删除选中对象
var 删除数量 = 我的场景框.删除选中对象();

// 添加选中变化监听器
我的场景框.添加选中变化监听器(function() {
    // 当选中对象变化时调用
    console.log('选中对象变化');
});

// 获取当前选中对象列表
var 选中对象列表 = 我的场景框.选中对象列表;
```

### 视图控制

```javascript
// 设置缩放
我的场景框.设置缩放(缩放比例);

// 设置视图位置
我的场景框.设置视图位置(x, y);

// 重置视图（回到原始位置和缩放）
我的场景框.重置视图();

// 居中视图（将舞台居中显示）
我的场景框.居中视图();
```

### 外观设置

```javascript
// 设置舞台选项
我的场景框.设置舞台选项({
    舞台宽度: 2000,
    舞台高度: 1500,
    舞台背景颜色: 0xFFFFFF
});

// 设置网格选项
我的场景框.设置网格选项({
    显示网格: true,
    网格大小: 20,
    网格颜色: 0xCCCCCC,
    网格透明度: 0.3
});

// 设置选中边框选项
我的场景框.设置选中边框选项({
    显示选中边框: true,
    选中边框颜色: 0x4A90E2,
    选中边框宽度: 2
});

// 设置虚线样式
我的场景框.设置虚线样式([5, 5]);
```

### 对齐功能

```javascript
// 设置对齐选项
我的场景框.设置对齐选项({
    启用对齐: true,
    对齐距离: 5,
    对齐线颜色: 0xFF0000
});

// 显示对齐线
我的场景框.显示对齐线(x, y, 是否水平线);

// 隐藏对齐线
我的场景框.隐藏对齐线();
```

### 资源管理

```javascript
// 销毁场景框，释放资源
我的场景框.销毁();
```

## 交互操作

场景框支持以下用户交互：

1. **选择对象**：
   - 左键点击选择单个对象
   - Shift + 左键点击添加/移除选择
   - 左键拖拽框选多个对象

2. **移动对象**：
   - 选中后直接拖拽
   - 使用键盘方向键微调位置

3. **缩放对象**：
   - 拖拽控制点调整大小
   - 角点控制点可同时调整宽高
   - 边缘控制点单独调整宽度或高度

4. **场景导航**：
   - 鼠标滚轮：缩放场景
   - Shift + 滚轮：垂直滚动
   - Alt + 滚轮：水平滚动
   - 右键拖拽：平移场景

5. **对齐辅助**：
   - 移动对象时自动显示对齐线
   - 接近其他对象边缘时自动吸附

## 事件系统

场景框内部实现了完整的事件处理系统，处理用户交互并触发相应的功能。主要事件包括：

- 鼠标按下：开始选择、移动或框选操作
- 鼠标移动：更新选择框、移动对象或调整大小
- 鼠标抬起：完成操作，更新选中状态
- 鼠标滚轮：控制缩放或滚动
- 键盘事件：辅助操作（如方向键移动、删除键等）

## 高级功能

### 自定义组件集成

场景框设计为可以与自定义组件无缝集成。自定义组件需要满足以下条件：

1. 包含一个 `容器` 属性，指向 PIXI.Container 实例
2. 可选实现 `设置位置(x, y)` 方法
3. 可选实现 `设置宽高(宽, 高)` 方法

### 嵌套组件支持

场景框支持嵌套组件结构，可以在容器内添加子组件，并保持正确的事件传递和选择行为。

### 热点设置

所有添加到场景框的对象热点(pivot)都会被设置为(0,0)，确保定位准确一致。

## 最佳实践

1. **组件设计**：
   - 确保所有组件都有一个主容器属性 `容器`
   - 实现 `设置位置` 和 `设置宽高` 方法以支持拖拽和缩放
   - 保持热点(pivot)为(0,0)以确保准确定位

2. **性能优化**：
   - 限制场景中对象的数量
   - 对于复杂组件，考虑使用缓存或优化渲染
   - 大型场景考虑使用对象池管理

3. **事件处理**：
   - 确保子组件的事件不会被父容器阻止
   - 使用 `e.stopPropagation()` 控制事件冒泡
   - 避免在全局范围内添加过多事件监听器

## 示例代码

```javascript
// 创建PixiJS应用
const pixiApp = new PIXI.Application();
await pixiApp.init({
    width: container.clientWidth,
    height: container.clientHeight,
    backgroundColor: 0xffffff,
    antialias: true
});
document.getElementById('container').appendChild(pixiApp.canvas);

// 创建场景框
const 我的场景框 = new 场景框();
我的场景框.初始化(0, 0, container.clientWidth, container.clientHeight, {
    调试模式: true,
    舞台宽度: 2000,
    舞台高度: 1500,
    网格大小: 20,
    网格透明度: 0.3
});

// 添加场景框到应用
pixiApp.stage.addChild(我的场景框.容器);

// 添加自定义组件
const 按钮组件 = new 按钮();
按钮组件.初始化(100, 100, 120, 40, {
    文本: '测试按钮',
    背景颜色: 0x4a90e2
});
我的场景框.添加对象(按钮组件.容器);

// 监听选中变化
我的场景框.添加选中变化监听器(function() {
    if (我的场景框.选中对象列表.length > 0) {
        console.log('选中了对象:', 我的场景框.选中对象列表);
    }
});
```

## 注意事项

1. 场景框依赖于 PixiJS v8 或更高版本
2. 所有坐标都基于左上角(0,0)点
3. 对象的交互性通过 `eventMode = 'static'` 启用
4. 在销毁场景框时，需要调用 `销毁()` 方法释放资源