|
|
# 场景框.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. 在销毁场景框时，需要调用 `销毁()` 方法释放资源
|
|
发表
组件文档
48 人阅读
|
1 人回复
