|
|
# 属性框组件（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助手帮你定制！
|
|
发表
组件文档
32 人阅读
|
0 人回复
