预览器文档

admin

以下是 `my/yulanqi.js`（项目预览框）组件的详细使用 API 文档，涵盖其构造方法、初始化、主要功能方法、参数说明、事件与回调等：

---

# 项目预览框（yulanqi.js）API 文档

## 1. 构造与初始化

### 构造函数

```js
const 预览框 = new 项目预览框();
```

### 初始化

```js
预览框.初始化(app, sceneFrame, [折叠状态回调]);
```

- **app**：PIXI.Application 实例（主 PIXI 应用）
- **sceneFrame**：场景框实例（需包含舞台容器等属性）
- **折叠状态回调**（可选）：`function(展开状态)`，展开状态为 `true` 表示展开，`false` 表示折叠

---

## 2. 主要方法

### 2.1 显示与隐藏

- `预览框.显示()`
  - 显示预览框
- `预览框.隐藏()`
  - 隐藏预览框

### 2.2 销毁

- `预览框.销毁()`
  - 移除事件监听，销毁所有 PIXI 对象，清理定时器

### 2.3 位置与尺寸

- `预览框.设置位置(x, y)`
  - 设置预览框左上角在主舞台的位置（像素）

- `预览框.设置宽高(mode, width, height)`
  - 设置预览框宽高
    - `mode`:
      - `0`：绝对像素（width, height 为数值）
      - `1`：百分比（width, height 可为 "80%" 字符串）
    - 兼容旧写法：`预览框.设置宽高(width, height)`，等价于 mode=0

### 2.4 折叠/展开相关

- `预览框.折叠()`
  - 折叠预览框，仅显示折叠按钮

- `预览框.展开()`
  - 展开预览框，恢复全部内容显示

- `预览框.获取展开状态()`
  - 返回当前是否为展开状态（`true` 展开，`false` 折叠）

- `预览框.设置折叠状态回调(fn)`
  - 设置折叠/展开状态变化时的回调函数，参数为 `true`（展开）或 `false`（折叠）

### 2.5 预览内容同步

- `预览框.强制同步()`
  - 强制将主场景内容同步到预览器（如遇到同步异常可手动调用）

- `预览框.重建预览器()`
  - 重新克隆主场景内容，重建预览舞台（如遇到结构性变化可手动调用）

---

## 3. 主要功能说明

- **设备分辨率预览**：支持多种移动设备、平板、PC 分辨率切换，支持旋转、缩放。
- **实时同步**：主场景对象变动（增删改、层级、属性）会自动同步到预览舞台。
- **对象微调**：在预览器中点击对象后，可用方向键微调其坐标，改动会同步回主场景。
- **折叠/展开**：可折叠为极简模式，仅保留一个按钮，节省屏幕空间。
- **状态栏/底栏**：模拟移动设备顶部状态栏和底部栏（底栏为简化版）。

---

## 4. 事件与回调

- **折叠状态回调**  
  初始化或通过 `设置折叠状态回调` 传入，签名如下：
  ```js
  function(展开状态) {
    // 展开状态为 true 表示展开，false 表示折叠
  }
  ```

---

## 5. 典型用法示例

```js
const 预览框 = new 项目预览框();
预览框.初始化(app, sceneFrame, function(isExpanded){
    console.log('预览框展开状态:', isExpanded);
});
预览框.设置位置(100, 50);
预览框.设置宽高(0, 400, 700); // 绝对像素
// 或
预览框.设置宽高(1, "80%", "90%"); // 百分比

// 折叠/展开
预览框.折叠();
预览框.展开();
console.log(预览框.获取展开状态());

// 强制同步
预览框.强制同步();
```

---

## 6. 其他说明

- 设备分辨率、旋转、缩放等操作均可通过界面按钮完成。
- 预览框会自动监听主场景对象的增删、属性变化、选中变化等事件，保持实时同步。
- 方向键微调仅对当前在预览器中选中的对象生效，并同步回主场景。

---

如需更详细的参数或扩展用法，可查阅源码注释或补充具体需求！