|
以下是 `幻灯片.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 对象和内存。
---
|
|