属性框组件

文档创建者:admin
浏览次数:22
最后更新:2025-06-21


# 属性框组件(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助手帮你定制!


您需要登录后才可以回帖 登录 | 立即注册

本版积分规则