|
# 属性框组件(PropertyBox)使用文档
## 简介
属性框(PropertyBox)是基于 PixiJS 8.x 的分组属性面板组件,支持分组折叠、内容自定义、滚动条、丰富的样式和布局调整,适合用于属性编辑器、面板、工具箱等场景。
---
## 1. 初始化
```js
const propBox = new 属性框();
propBox.初始化(x, y, width, height, options);
```
- **x, y**:左上角坐标(默认 0, 0)
- **width, height**:初始宽高(可选,省略则用默认)
- **options**:可选配置对象,支持以下字段:
| 选项名 | 说明 | 默认值 |
|--------------------|------------------------------|-------------|
| 宽度 | 组件宽度 | 280 |
| 高度 | 组件高度 | 400 |
| 背景颜色 | 背景色(16进制数) | 0x1e1e1e |
| 背景透明度 | 背景透明度 0~1 | 0.85 |
| 边框颜色 | 边框颜色 | 0x555555 |
| 边框透明度 | 边框透明度 0~1 | 1 |
| 边框宽度 | 边框线宽 | 1 |
| 圆角 | 圆角半径 | 0 |
| 标题高度 | 分组标题栏高度 | 28 |
| 标题背景颜色 | 标题栏背景色 | 0x2a2a2a |
| 标题文字颜色 | 标题栏文字颜色 | 0xffffff |
| 标题字体大小 | 标题栏字号 | 16 |
| 标题字体 | 标题栏字体 | 'Arial' |
| 标题左边距/右边距 | 标题栏左右边距 | 6/6 |
| 标题背景左/右边距 | 标题背景额外左右留白 | 0/0 |
| 标题文字像素对齐 | 标题文字是否像素对齐 | true |
| 折叠图标位置 | 'left' 或 'right' | 'left' |
| 折叠图标大小 | 折叠三角形大小 | 8 |
| 折叠图标颜色 | 折叠三角形颜色 | 0xffffff |
| 折叠图标透明度 | 折叠三角形透明度 | 1 |
| 折叠图标偏移X/Y | 折叠图标XY偏移 | 6/0 |
| 分组内容上/下/左/右边距 | 分组内容区内边距 | 8/8/8/8 |
| 分组间距 | 分组之间的垂直间隔 | 4 |
| 项目默认高度 | 单条项目默认高度 | 24 |
| 项目行间距 | 相邻项目垂直间距 | 4 |
| 启用内容遮罩 | 是否为分组内容启用遮罩 | true |
| 可拖动 | 是否允许整体拖动 | false |
| 拖动阈值 | 拖动判定的最小距离 | 5 |
| 滚动条宽度 | 滚动条宽度 | 10 |
| 滚动条颜色 | 滚动条颜色 | 0x000000 |
| 滚动条透明度 | 滚动条透明度 | 0.1 |
| 滚动步长 | 滚轮每次滚动的像素 | 20 |
| 调试模式 | 控制台输出调试信息 | false |
| 显示调试边框 | 显示内容区调试边框 | false |
---
## 2. 添加到舞台
```js
app.stage.addChild(propBox.获取容器());
```
- `propBox.获取容器()` 返回 PixiJS 的 `Container`,可直接 addChild。
---
## 3. 添加分组
```js
const group = propBox.添加分组('分组标题', false, { 上边距: 12, 下边距: 12 });
```
- **'分组标题'**:分组显示的标题文本
- **false**:是否初始折叠(true=折叠,false=展开)
- **分组选项**:可选,覆盖全局边距/遮罩等
### 分组句柄API
- `group.添加对象(obj, index)`:向分组内容区添加显示对象(PIXI.DisplayObject),可指定插入位置
- `group.删除对象(obj)`:从分组内容区移除对象
- `group.设置对象行高(obj, h)`:设置某对象的行高(用于自定义高度的项目)
- `group.折叠()` / `group.展开()`:折叠/展开分组
- `group.获取容器()`:获取分组内容区容器(可直接 addChild)
- `group.设置标题(txt)`:修改分组标题文本
- `group.设置标题样式(opt)`:单独设置本组标题样式(颜色、字体、字号、背景等)
- `group.设置边距(cfg)`:单独设置本组内容区边距
---
## 4. 添加/管理内容
### 添加对象
```js
group.添加对象(new PIXI.Text('属性项'));
```
或
```js
propBox.添加对象(分组索引, obj, index);
```
### 删除对象
```js
group.删除对象(obj);
```
### 设置对象行高
```js
group.设置对象行高(obj, 40);
```
---
## 5. 折叠/展开分组
```js
group.折叠();
group.展开();
```
- 也可点击标题栏切换折叠状态。
---
## 6. 设置/调整样式
### 设置背景色/边框
```js
propBox.设置背景颜色(0x333333, 0.9);
propBox.设置边框颜色(0xff0000, 0.8);
propBox.设置边框大小(2);
```
### 设置折叠图标样式
```js
propBox.设置折叠图标({ 位置: 'right', 大小: 12, 颜色: 0x00ccff });
```
### 设置标题栏样式(全局)
```js
propBox.设置标题样式({ 字体: '微软雅黑', 字号: 18, 文字颜色: 0x00ccff, 背景颜色: 0x222222 });
```
### 设置标题栏边距
```js
propBox.设置标题栏边距({ 左边距: 12, 右边距: 12 });
```
### 设置分组内容边距
```js
propBox.设置分组边距(分组索引, { 上边距: 16, 下边距: 16, 左边距: 20, 右边距: 20 });
```
或
```js
group.设置边距({ 上边距: 16, 下边距: 16 });
```
### 设置分组间距
```js
propBox.设置分组间距(8);
```
---
## 7. 尺寸与布局
### 设置宽高
```js
// 类型: 0=固定像素, 1=百分比, 3=最大不超过父容器
propBox.设置宽高(0, 320, 500);
propBox.设置宽高(1, '80', '60'); // 百分比
propBox.设置宽高(3, 400, 600); // 最大不超过父容器
```
### 设置位置
```js
propBox.设置位置(x, y);
```
### 强制刷新布局
```js
propBox.更新布局();
```
- 外部动态添加内容后可手动调用。
---
## 8. 滚动条
- 内容超出高度时自动显示滚动条,支持鼠标滚轮和拖动滑块滚动。
- 可用 `propBox.设置滚动条可见(true/false)` 控制滚动条显示。
---
## 9. 销毁
```js
propBox.销毁();
```
- 释放所有 PixiJS 对象和内存。
---
## 10. 其它说明
- **分组内容区**:每个分组的 `内容` 容器可直接 addChild 自定义显示对象。
- **分组内容遮罩**:默认启用,防止内容溢出。
- **拖动支持**:可选,设置 `可拖动: true` 后可整体拖动属性框。
- **调试模式**:`调试模式: true` 时控制台输出详细信息,`显示调试边框: true` 时显示内容区边框。
- **像素对齐**:标题文字可设置 `标题文字像素对齐`,避免模糊。
---
## 11. 示例
```js
const propBox = new 属性框().初始化(50, 50, 320, 480, { 背景颜色: 0x222222 });
app.stage.addChild(propBox.获取容器());
const group1 = propBox.添加分组('基本属性');
group1.添加对象(new PIXI.Text('名称:'));
group1.添加对象(new PIXI.Text('类型:'));
const group2 = propBox.添加分组('高级设置', true);
group2.添加对象(new PIXI.Text('只读:'));
group2.展开();
propBox.设置背景颜色(0x333333, 0.95);
propBox.设置折叠图标({ 位置: 'right', 大小: 10, 颜色: 0xff9900 });
```
---
## 12. 常见问题
- **内容溢出/遮挡?**
检查分组内容边距和遮罩设置,或手动调用 `propBox.更新布局()`。
- **分组内容动态变化后高度不对?**
添加/删除内容后建议调用 `group.刷新分组()` 或 `propBox.更新布局()`。
- **滚动条不显示?**
只有内容超出高度时才显示,或用 `propBox.设置滚动条可见(true)` 强制显示。
- **标题样式/分组样式不生效?**
全局样式用 `propBox.设置标题样式`,单组样式用 `group.设置标题样式`。
---
如需更复杂的用法或定制功能,可联系开发者或让AI助手帮你定制!
|
|