幻灯片

admin

以下是 `幻灯片.js`（Slideshow/Slider）组件的详细使用文档，涵盖所有主要API、参数、用法和注意事项。

---

# 幻灯片组件（Slider/Slideshow）使用文档

## 简介

幻灯片组件是基于 PixiJS 8.x 的图片/内容轮播组件，支持图片、文本、自定义容器、指示器、自动播放、动画切换等功能，适合用于展示型页面、Banner、产品轮播等场景。

---

## 1. 初始化

```js
const slider = new 幻灯片();
slider.初始化(x, y, width, height, options);
```

- **x, y**：左上角坐标（默认 0, 0）
- **width, height**：幻灯片区域宽高
- **options**：可选配置对象，详见下表

| 选项名             | 说明                         | 默认值      |
|--------------------|------------------------------|-------------|
| 宽度               | 幻灯片宽度                   | 600         |
| 高度               | 幻灯片高度                   | 300         |
| 背景颜色           | 背景色（16进制数）           | 0xf8f8f8    |
| 边框颜色           | 边框颜色                     | 0xcccccc    |
| 边框宽度           | 边框线宽                     | 1           |
| 圆角               | 圆角半径                     | 4           |
| 指示器颜色         | 指示器未选中颜色             | 0xcccccc    |
| 指示器选中颜色     | 指示器选中颜色               | 0x4a90e2    |
| 指示器大小         | 指示器圆点大小               | 10          |
| 指示器间距         | 指示器圆点间距               | 8           |
| 指示器位置         | 指示器位置: 'top'/'bottom'/'left'/'right' | 'bottom' |
| 指示器可见         | 是否显示指示器               | true        |
| 自动播放           | 是否自动播放                 | false       |
| 播放间隔           | 自动播放间隔（毫秒）         | 3000        |
| 过渡动画           | 过渡动画类型: 'slide'/'fade' | 'slide'     |
| 过渡时间           | 过渡动画时长（毫秒）         | 500         |
| 允许循环           | 是否循环播放                 | true        |
| 幻灯片列表         | 幻灯片项目数组               | []          |
| 调试模式           | 控制台输出调试信息           | false       |

---

## 2. 添加到舞台

```js
app.stage.addChild(slider.容器);
```
- `slider.容器` 是 PixiJS 的 `Container`，可直接 addChild。

---

## 3. 幻灯片数据结构

每个幻灯片项目支持以下字段：

- **图片**：图片URL或PixiJS纹理对象
- **图片填充模式**：'cover'（默认）、'contain'、'original'
- **文本**：显示文本内容
- **字体**、**字号**、**文本颜色**：文本样式
- **背景颜色**：单张幻灯片的背景色
- **自定义容器**：PixiJS Container，可自定义内容
- **不自动居中**：自定义容器时禁用自动居中

**示例：**
```js
const slides = [
    { 文本: '欢迎使用幻灯片', 字体: 'Arial', 字号: 32, 文本颜色: 0x2266aa, 背景颜色: 0xe6f7ff },
    { 图片: 'https://picsum.photos/id/1018/800/500', 图片填充模式: 'cover' },
    { 图片: 'https://picsum.photos/id/1015/800/500', 图片填充模式: 'contain' },
    { 图片: 'https://picsum.photos/id/1019/400/300', 图片填充模式: 'original' },
    { 自定义容器: myPixiContainer }
];
```

---

## 4. 主要API

### 初始化

```js
slider.初始化(x, y, width, height, options);
```

### 控制播放

```js
slider.上一张();   // 切换到上一张
slider.下一张();   // 切换到下一张
slider.切换到(index); // 切换到指定索引
slider.设置自动播放(true/false, intervalMs); // 启用/禁用自动播放，可选间隔
```

### 动态操作

```js
slider.插入项目(item, index); // 在指定位置插入幻灯片
slider.删除项目(index);       // 删除指定索引的幻灯片
slider.更新项目(index, newData); // 更新指定幻灯片数据
slider.获取当前索引();        // 获取当前显示的索引
slider.获取当前项目();        // 获取当前幻灯片数据
```

### 样式与选项

```js
slider.设置选项(key, value); // 动态设置选项，如 slider.设置选项('指示器颜色', 0xff0000)
slider.设置指示器颜色(普通色, 选中色); // 单独设置指示器颜色
slider.设置宽高(类型, 宽, 高); // 0=固定像素, 1=百分比, 3=最大不超过父容器
slider.设置位置(x, y);
```

---

## 5. 事件

- **切换**：`slider.容器.on('切换', (index, data)=>{})`  
  切换幻灯片时触发，参数为新索引和幻灯片数据。
- **项目点击**：`slider.容器.on('项目点击', (data, index)=>{})`  
  点击幻灯片内容时触发。

---

## 6. 用法示例

```js
const app = new PIXI.Application();
await app.init({ width: 1000, height: 600, background: '#222', resizeTo: window });
document.body.appendChild(app.canvas || app.view);

const slides = [
    { 文本: '第一张', 字体: 'Arial', 字号: 32, 文本颜色: 0x2266aa, 背景颜色: 0xe6f7ff },
    { 图片: 'https://picsum.photos/id/1018/800/500', 图片填充模式: 'cover' }
];

const slider = new 幻灯片();
slider.初始化(100, 80, 800, 400, {
    背景颜色: 0xffffff,
    边框颜色: 0xcccccc,
    边框宽度: 2,
    圆角: 8,
    指示器位置: 'bottom',
    指示器颜色: 0xcccccc,
    指示器选中颜色: 0x4a90e2,
    过渡动画: 'slide',
    过渡时间: 500,
    自动播放: false,
    播放间隔: 3000,
    幻灯片列表: slides
});
app.stage.addChild(slider.容器);

// 控制
document.getElementById('prevBtn').onclick = ()=>slider.上一张();
document.getElementById('nextBtn').onclick = ()=>slider.下一张();
document.getElementById('toggleAuto').onclick = ()=>{
    slider.选项.自动播放 = !slider.选项.自动播放;
    slider._控制自动播放 && slider._控制自动播放();
};
```

---

## 7. 注意事项

- **图片填充模式**：  
  - `'cover'`：填满区域，可能裁剪
  - `'contain'`：完整显示，可能留白
  - `'original'`：原始尺寸，居中
- **自定义容器**：  
  - 需设置好宽高，便于自动居中
- **自动播放**：  
  - 鼠标悬停时会自动暂停，移开后恢复
- **事件监听**：  
  - 推荐用 PixiJS 的事件系统监听 `slider.容器` 上的自定义事件

---

## 8. 销毁

```js
slider.销毁 && slider.销毁();
```
- 释放所有 PixiJS 对象和内存。

---