面板框设计理念

admin

您说得对，面板框组件目前缺少与其他组件一致的 `设置宽高` 方法，无法支持三种尺寸设置模式（固定像素、百分比、最大不超父容器）。

我会为面板框组件添加这个方法：


我发现面板框.js文件中的设置宽度和设置高度方法被移除了，让我添加回来并保留设置宽高方法：


现在我需要更新使用文档，包含新增的设置宽高方法：

# 面板框 (Panel Frame) 使用文档 - 更新版

## 基本介绍
面板框组件提供可拖动、可缩放、带标题栏的面板容器，支持动画特效，可用于创建对话框、信息面板、设置窗口等界面元素。

## 创建与初始化

### 基本创建方式
```javascript
// 创建面板框实例
var 面板 = new 面板框();

// 初始化面板框
面板.初始化({
    宽度: 400,
    高度: 300,
    标题文本: '面板标题',
    标题对齐: 'center'
});

// 添加到舞台
app.stage.addChild(面板.获取容器());
```

### 配置选项
初始化时可传入以下选项：

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| 宽度 | Number | 400 | 面板宽度 |
| 高度 | Number | 300 | 面板高度 |
| 背景颜色 | Number | 0xf8f8f8 | 背景颜色 (十六进制) |
| 边框颜色 | Number | 0xcccccc | 边框颜色 |
| 边框宽度 | Number | 1 | 边框宽度 |
| 圆角 | Number | 4 | 圆角大小 |
| 标题栏高度 | Number | 32 | 标题栏高度 |
| 标题栏颜色 | Number | 0xe0e0e0 | 标题栏背景颜色 |
| 标题文本 | String | '面板' | 标题文本 |
| 标题颜色 | Number | 0x333333 | 标题文本颜色 |
| 标题字体 | String | 'Arial' | 标题字体 |
| 标题大小 | Number | 14 | 标题字体大小 |
| 标题对齐 | String | 'left' | 标题对齐方式: 'left', 'center', 'right' |
| 标题左边距 | Number | 10 | 标题左边距 |
| 允许拖动 | Boolean | true | 是否允许整个面板被拖动 |
| 允许标题拖动 | Boolean | true | 是否允许通过标题栏拖动 |
| 允许缩放 | Boolean | true | 是否允许缩放大小 |
| 缩放手柄大小 | Number | 16 | 缩放手柄区域大小 |
| 缩放手柄颜色 | Number | 0xcccccc | 缩放手柄颜色 |
| 最小宽度 | Number | 100 | 最小允许宽度 |
| 最小高度 | Number | 100 | 最小允许高度 |
| 允许穿透 | Boolean | false | 是否允许穿透 |
| 调试模式 | Boolean | false | 是否启用调试模式 |

## 方法列表

### 位置相关

```javascript
// 设置面板位置
面板.设置位置(x, y);

// 单独设置X坐标
面板.设置X坐标(x);

// 单独设置Y坐标
面板.设置Y坐标(y);

// 获取位置
var 位置 = 面板.获取位置(); // 返回 {x, y}
```

### 尺寸相关

```javascript
// 设置面板尺寸 - 固定像素
面板.设置尺寸(宽度, 高度);

// 单独设置宽度
面板.设置宽度(宽度);

// 单独设置高度
面板.设置高度(高度);

// 高级尺寸设置（支持三种模式）
面板.设置宽高(类型, 宽度, 高度);
// 类型:
//   0 - 固定像素 (如: 设置宽高(0, 400, 300))
//   1 - 百分比/混合 (如: 设置宽高(1, '50%', '70%'))
//   3 - 最大不超父容器 (如: 设置宽高(3, 500, 400))
```

### 内容管理

```javascript
// 添加内容到面板
面板.添加内容(元素); // 元素可以是任何PIXI显示对象

// 清空面板内容
面板.清空内容();

// 获取内容容器
var 内容容器 = 面板.获取内容容器();
```

### 标题管理

```javascript
// 设置标题文本
面板.设置标题('新标题');
```

### 动画效果

```javascript
// 显示面板（带动画）
面板.显示(动画类型, 持续时间);
// 动画类型: '无', '渐显', '缩放', '弹出'
// 持续时间: 毫秒，默认300

// 隐藏面板（带动画）
面板.隐藏(动画类型, 持续时间);
// 动画类型: '无', '渐隐', '缩小', '收起'
// 持续时间: 毫秒，默认300
```

### 其他

```javascript
// 获取容器对象
var 容器 = 面板.获取容器();

// 销毁面板
面板.销毁();
```

## 事件监听

```javascript
// 监听面板尺寸变化事件
面板.获取容器().on('尺寸更新', function(尺寸) {
    console.log('面板尺寸已更新:', 尺寸.宽度, 尺寸.高度);
});
```

## 使用示例

### 基本用法示例

```javascript
// 创建面板框实例
var 面板 = new 面板框();
面板.初始化({
    宽度: 400,
    高度: 300,
    标题文本: '示例面板',
    标题对齐: 'center',
    背景颜色: 0xffffff,
    边框颜色: 0x3498db,
    标题栏颜色: 0x3498db,
    标题颜色: 0xffffff
});

// 设置面板位置
面板.设置位置(100, 100);

// 添加到舞台
app.stage.addChild(面板.获取容器());

// 添加内容
var 文本 = new PIXI.Text('这是面板内容', {
    fontFamily: 'Arial',
    fontSize: 16,
    fill: 0x333333
});
文本.position.set(20, 20);
面板.添加内容(文本);
```

### 尺寸设置示例

```javascript
// 创建面板
var 面板 = new 面板框();
面板.初始化({ 标题文本: '自适应面板' });
app.stage.addChild(面板.获取容器());

// 设置固定像素尺寸
面板.设置宽高(0, 400, 300);

// 设置为窗口一半大小（百分比）
面板.设置宽高(1, '50%', '50%');

// 设置最大尺寸（不超过窗口）
面板.设置宽高(3, 800, 600);

// 窗口大小变化时自动调整面板尺寸
window.addEventListener('resize', function() {
    面板.设置宽高(1, '60%', '70%');
});
```

### 动画效果示例

```javascript
// 创建显示按钮
var 显示按钮 = new 按钮();
显示按钮.初始化(50, 50, 120, 40, {
    文本: '显示面板',
    背景颜色: 0x2ecc71
});
app.stage.addChild(显示按钮.获取容器());

// 创建隐藏按钮
var 隐藏按钮 = new 按钮();
隐藏按钮.初始化(20, 60, 120, 40, {
    文本: '关闭面板',
    背景颜色: 0xe74c3c
});

// 添加点击事件
显示按钮.获取容器().on('点击', function() {
    面板.显示('弹出', 500); // 使用弹出动画，持续500毫秒
});

// 将隐藏按钮添加到面板内
面板.添加内容(隐藏按钮.获取容器());

// 添加隐藏按钮的点击事件
隐藏按钮.获取容器().on('点击', function() {
    面板.隐藏('渐隐', 300); // 使用渐隐动画，持续300毫秒
});
```

### 嵌套组件示例

```javascript
// 创建面板
var 面板 = new 面板框();
面板.初始化({
    宽度: 500,
    高度: 400,
    标题文本: '列表面板'
});
面板.设置位置(200, 150);
app.stage.addChild(面板.获取容器());

// 在面板中添加列表框
var 列表 = new 列表框();
列表.初始化({
    宽度: 480,
    高度: 320,
    数据列表: [
        { 文本: '项目1', 值: 1 },
        { 文本: '项目2', 值: 2 },
        { 文本: '项目3', 值: 3 }
    ],
    表头数据: [
        { 文本: '名称', 宽度: 240 },
        { 文本: '值', 宽度: 240 }
    ]
});
列表.设置位置(10, 10);
面板.添加内容(列表.获取容器());

// 监听面板尺寸变化事件，动态调整列表尺寸
面板.获取容器().on('尺寸更新', function(尺寸) {
    // 更新列表框尺寸 - 使用类型0（固定像素）
    列表.设置宽高(0, 尺寸.宽度 - 20, 尺寸.高度 - 面板.选项.标题栏高度 - 20);
});
```

## 注意事项

1. 面板默认支持通过标题栏拖动，可通过设置 `允许标题拖动: false` 禁用
2. 面板默认支持通过右下角缩放手柄调整大小，可通过设置 `允许缩放: false` 禁用
3. 添加到面板的内容，其坐标系相对于面板内容区域的左上角
4. 销毁面板时，会自动清除所有内部组件和事件监听
5. 设置宽高方法支持三种类型（0,1,3），可满足不同场景的尺寸需求

admin

确保所有添加的内容都被限制在面板区域内。


现在面板框组件已经添加了内容遮罩功能，确保内部组件不会超出面板边界。这里是对新功能的解释：

## 新增功能说明

1. **内容遮罩**：
   - 默认启用，可通过 `设置内容遮罩(true/false)` 方法开启或关闭
   - 所有添加到面板的内容如果超出范围，会被自动裁剪
   - 遮罩会随着面板尺寸变化自动调整

2. **内容超出检测**：
   - 添加内容时会检测是否超出面板范围
   - 如果超出，会在调试模式下输出提示信息
   - 超出部分会被遮罩裁剪，不会显示在面板外

3. **自动调整内容尺寸**：
   - 新增 `自动调整内容(元素)` 方法
   - 可自动缩放内容以适应面板大小
   - 可调整单个元素或所有内容元素

## 使用示例

### 使用内容遮罩（默认开启）

```javascript
// 创建面板
var 面板 = new 面板框();
面板.初始化({
    宽度: 400,
    高度: 300,
    标题文本: '内容遮罩示例'
});
app.stage.addChild(面板.获取容器());

// 添加超出范围的内容（会被自动裁剪）
var 大图 = new PIXI.Graphics();
大图.beginFill(0xff0000);
大图.drawRect(0, 0, 600, 400); // 超出面板范围
大图.endFill();
面板.添加内容(大图);
```

### 禁用内容遮罩

```javascript
// 禁用内容遮罩（内容可超出面板范围）
面板.设置内容遮罩(false);
```

### 自动调整内容尺寸

```javascript
// 添加内容后自动调整大小
var 列表 = new 列表框();
列表.初始化({
    宽度: 600, // 大于面板宽度
    高度: 500  // 大于面板高度
});
面板.添加内容(列表.获取容器());

// 自动缩放列表适应面板
面板.自动调整内容(列表.获取容器());
```

### 监听面板尺寸变化并自动调整内容

```javascript
// 监听面板尺寸变化，自动调整内容
面板.获取容器().on('尺寸更新', function(尺寸) {
    // 使用内容遮罩确保内容不超出
    // 或主动调整内容大小
    面板.自动调整内容();
});
```

现在面板框组件更加完善，可以确保内容始终保持在面板范围内，无论是通过遮罩裁剪还是自动调整尺寸的方式。

admin

1. **初始化时设置透明度**：
```javascript
var 面板 = new 面板框();
面板.初始化({
    宽度: 400,
    高度: 300,
    缩放手柄透明度: 0.5  // 设置半透明
});
```

2. **动态修改透明度**：
```javascript
// 单独设置透明度
面板.设置缩放手柄透明度(0.3);  // 设置为30%不透明度

// 同时设置颜色和透明度
面板.设置缩放手柄颜色(0xff0000, 0.7);  // 设置为红色，70%不透明度
```

3. **特殊效果示例**：
```javascript
// 鼠标悬停时增加透明度，离开时降低透明度
面板.缩放手柄.on('pointerover', function() {
    面板.设置缩放手柄透明度(1.0);  // 鼠标悬停时完全不透明
});

面板.缩放手柄.on('pointerout', function() {
    面板.设置缩放手柄透明度(0.3);  // 鼠标离开时设为半透明
});
```

透明度值范围为0-1，其中0表示完全透明（不可见），1表示完全不透明。这样您就可以根据需要灵活控制缩放手柄的显示效果了。

admin

已成功添加了背景透明度设置功能。现在面板框组件支持以下透明度相关功能：

1. 添加了三个新透明度选项属性：
   - `背景透明度`：控制面板背景的透明度
   - `边框透明度`：控制边框的透明度
   - `标题栏透明度`：控制标题栏的透明度

2. 所有绘图操作都已更新，现在在调用 `beginFill` 和 `lineStyle` 时会应用透明度参数

3. 添加了三个新方法：
   - `设置背景颜色(颜色, 透明度)`：设置背景颜色和透明度
   - `设置背景透明度(透明度)`：单独设置背景透明度
   - `设置标题栏颜色(颜色, 透明度)`：设置标题栏颜色和透明度

您现在可以通过初始化选项设置透明度或使用这些方法在运行时动态调整透明度。

admin

已添加了设置边框透明度的方法。现在面板框组件完整支持所有元素的透明度设置：

1. 背景透明度：通过 `设置背景透明度(透明度)` 或 `设置背景颜色(颜色, 透明度)` 设置
2. 边框透明度：通过 `设置边框透明度(透明度)` 或 `设置边框颜色(颜色, 透明度)` 设置
3. 标题栏透明度：通过 `设置标题栏颜色(颜色, 透明度)` 设置
4. 缩放手柄透明度：通过 `设置缩放手柄透明度(透明度)` 设置

所有这些透明度值都可以在初始化时通过选项设置，也可以在运行时使用相应的方法动态调整。这样面板框组件就有了完整的透明度控制功能。