|
|
# 资源管理器组件使用文档
## 概述
资源管理器是一个基于PixiJS的可视化文件资源浏览组件，提供左侧树形文件夹导航和右侧缩略图预览的双面板布局。支持拖拽上传、多种文件类型预览、自定义样式和默认纹理设置等功能。
## 基本使用
### 创建和初始化
```javascript
// 引入依赖
import { 资源管理器 } from './资源管理器.js';
// 创建实例
const explorer = new 资源管理器();
// 初始化（必需）
explorer.初始化(x, y, 宽度, 高度, 配置选项);
```
### 基本示例
```javascript
// 创建PIXI应用
const app = new PIXI.Application({
width: 1200,
height: 800,
backgroundColor: 0x1a1a1a
});
document.body.appendChild(app.view);
// 创建资源管理器
const explorer = new 资源管理器();
explorer.初始化(50, 50, 1100, 700);
app.stage.addChild(explorer.获取容器());
// 设置数据
const data = [
{
文本: "我的文件夹",
文件列表: [
{ name: "图片.jpg", url: "path/to/image.jpg", type: "image" },
{ name: "文档.txt", content: "文件内容", type: "text" }
]
}
];
explorer.设置目录数据(data);
```
## 配置选项
### 初始化配置
```javascript
const 配置 = {
// 基础尺寸
宽度: 800, // 组件总宽度
高度: 280, // 组件总高度
左侧宽度: 250, // 左侧树形面板宽度
// 背景和边框
背景颜色: 0x2c2c2c, // 主背景颜色
背景透明度: 0.9, // 背景透明度
边框颜色: 0x444444, // 边框颜色
边框宽度: 1, // 边框宽度
边框透明度: 1, // 边框透明度
圆角: 0, // 外框圆角
// 分隔线
分隔线颜色: 0x666666, // 左右面板分隔线颜色
分隔线粗细: 1, // 分隔线宽度
// 缩略图设置
缩略宽度: 120, // 缩略图宽度
缩略高度: 120, // 缩略图高度
预览间距: 16, // 缩略图间距
// 文字设置
字体: 'Arial', // 字体名称
字号: 14, // 字体大小
文字颜色: 0xffffff, // 文字颜色
// 缩略图外观
缩略背景颜色: 0x3a3a3a, // 缩略图背景色
缩略背景透明度: 1, // 缩略图背景透明度
缩略悬停颜色: 0x505050, // 悬停时背景色
缩略悬停透明度: 0.6, // 悬停时透明度
缩略选中边颜色: 0x2980b9, // 选中时边框色
缩略边框宽度: 2, // 缩略图边框宽度
缩略圆角: 6, // 缩略图圆角
// 左侧树形设置
左侧背景颜色: null, // 左侧背景色（null则跟随主背景）
左侧文字颜色: 0xcccccc, // 左侧文字颜色
// 选中效果
缩略选中覆盖颜色: 0x000000, // 选中覆盖色
缩略选中覆盖透明度: 0.2, // 选中覆盖透明度
// 右侧设置
右侧背景颜色: null, // 右侧背景色（null则跟随主背景）
缩略描边颜色: 0x2980b9, // 缩略图描边色
外框圆角: 0, // 外框圆角
列表悬停颜色: 0x505050, // 列表悬停色
// 默认纹理配置
默认纹理: null, // 默认纹理对象
默认纹理URL: null, // 默认纹理URL
默认emoji: '✖️', // 默认emoji
默认emoji颜色: 0xff0000, // 默认emoji颜色
默认emoji大小: 64, // 默认emoji大小
};
explorer.初始化(0, 0, 800, 600, 配置);
```
## 核心API
### 基础方法
#### 初始化
```javascript
explorer.初始化(x, y, 宽度, 高度, 配置选项)
```
- **参数**：
- `x` (number): X坐标位置
- `y` (number): Y坐标位置
- `宽度` (number): 组件宽度
- `高度` (number): 组件高度
- `配置选项` (object): 可选配置对象
#### 设置目录数据
```javascript
explorer.设置目录数据(树数据)
```
- **参数**：
- `树数据` (array): 树形结构数据
- **数据格式**：
```javascript
[
{
文本: "文件夹名称",
文件列表: [
{
name: "文件名.jpg",
url: "文件URL",
type: "image", // 可选，自动检测
content: "文件内容" // 文本文件内容
}
]
}
]
```
#### 获取容器
```javascript
const container = explorer.获取容器()
```
- **返回**：PIXI.Container对象
### 样式设置API
#### 设置缩略样式
```javascript
explorer.设置缩略样式({
圆角: 8,
背景颜色: 0x3a3a3a,
背景透明度: 0.8,
边框宽度: 2,
边框颜色: 0x2980b9,
选中覆盖颜色: 0x000000,
选中覆盖透明度: 0.3
})
```
#### 设置区域样式
```javascript
explorer.设置区域样式({
左背景: 0x2a2a2a, // 左侧背景色
左边框颜色: 0x444444, // 左侧边框色
左边框宽度: 1, // 左侧边框宽度
左背景右间距: 5, // 左侧背景右间距
左文本偏移: 10, // 左侧文本水平偏移
右背景: 0x3a3a3a, // 右侧背景色
右边框颜色: 0x555555, // 右侧边框色
右边框宽度: 1 // 右侧边框宽度
})
```
#### 设置左树交互样式
```javascript
explorer.设置左树交互样式({
选中颜色: 0x2980b9,
悬停颜色: 0x505050,
选中透明度: 0.8,
悬停透明度: 0.6
})
```
#### 设置列表样式
```javascript
// 设置选中颜色
explorer.设置列表选中色(0x2980b9);
// 设置悬停颜色
explorer.设置列表悬停色(0x505050);
// 设置悬停透明度
explorer.设置列表悬停透明度(0.6);
// 设置列表框悬停颜色
explorer.设置列表框悬停颜色(0x505050);
// 设置列表框悬浮样式
explorer.设置列表框悬浮样式({
颜色: 0x505050,
透明度: 0.6,
偏移X: 0,
偏移Y: 0
});
```
### 默认纹理API
#### 设置默认纹理对象
```javascript
// 先加载纹理
PIXI.Assets.load('path/to/texture.png').then(texture => {
explorer.设置默认纹理(texture);
});
```
#### 设置默认纹理URL
```javascript
explorer.设置默认纹理URL('https://example.com/default-image.png');
```
#### 设置默认emoji
```javascript
explorer.设置默认emoji('❌', 0xff0000, 64);
// 参数：emoji字符, 颜色(十六进制), 字体大小
```
#### 清除默认纹理
```javascript
explorer.清除默认纹理();
```
#### 获取默认纹理配置
```javascript
const config = explorer.获取默认纹理配置();
console.log(config);
// 返回：{默认纹理, 默认纹理URL, 默认emoji, 默认emoji颜色, 默认emoji大小}
```
## 文件类型支持
### 自动检测的文件类型
| 扩展名 | 类型 | 预览方式 |
|--------|------|----------|
| .png, .jpg, .jpeg, .gif, .webp, .bmp | image | 缩略图预览 |
| .mp4, .webm, .ogg, .mov | video | 视频图标 |
| .mp3, .wav, .ogg, .flac | audio | 音频图标 |
| .json | json | 文本预览 |
| .txt, .md, .log, .csv | text | 文本预览 |
| 文件夹 | folder | 文件夹图标 |
### 自定义文件类型
```javascript
const fileData = {
name: "custom.file",
url: "path/to/file",
type: "image", // 强制指定类型
content: "文件内容" // 文本文件内容
};
```
## 事件处理
### 节点选择事件
```javascript
// 监听左侧树形选择
explorer._树形.容器.on('节点选择', (节点数据) => {
console.log('选中节点:', 节点数据);
// 节点数据包含：文本, 文件列表等
});
```
### 单元格点击事件
```javascript
// 监听右侧缩略图点击
explorer._列表框.获取容器().on('单元格点击', (单元格数据, 索引) => {
console.log('点击缩略图:', 单元格数据);
});
```
## 拖拽功能
### 自动支持
- 组件自动支持文件拖拽上传
- 支持多文件同时拖拽
- 自动创建对象URL并显示预览
### 拖拽数据格式
```javascript
// 拖拽的文件会自动转换为以下格式
{
name: "文件名.jpg",
type: "image/jpeg",
objectURL: "blob:http://...",
文件引用: File对象
}
```
## 高级用法
### 动态更新数据
```javascript
// 更新整个目录结构
const newData = [
{
文本: "新文件夹",
文件列表: [
{ name: "新文件.jpg", url: "new/path.jpg", type: "image" }
]
}
];
explorer.设置目录数据(newData);
```
### 自定义预览窗口
```javascript
// 组件内部已实现预览窗口，支持：
// - 图片大图预览
// - 文本内容预览
// - 视频播放
// - 音频播放
```
### 响应式布局
```javascript
// 监听窗口大小变化
window.addEventListener('resize', () => {
const newWidth = window.innerWidth - 100;
const newHeight = window.innerHeight - 100;
explorer.初始化(50, 50, newWidth, newHeight);
});
```
## 性能优化
### 建议配置
```javascript
// 对于大量文件的优化配置
const 优化配置 = {
缩略宽度: 80, // 减小缩略图尺寸
缩略高度: 80,
预览间距: 8, // 减小间距
默认emoji大小: 32, // 减小emoji大小
};
```
### 内存管理
```javascript
// 清理资源
function cleanup() {
// 清理对象URL
explorer._列表框.获取数据().forEach(item => {
if (item.内容 && item.内容.objectURL) {
URL.revokeObjectURL(item.内容.objectURL);
}
});
}
```
## 注意事项
### 1. 依赖要求
- 必须引入PixiJS v7+
- 需要树形框组件 (`树形框.js`)
- 需要超级列表框组件 (`超级列表框.js`)
- 需要信息框组件 (`信息框.js`)
### 2. 文件URL处理
- 支持本地文件路径
- 支持网络URL
- 支持Blob URL（拖拽文件）
- 图片加载失败时使用默认纹理
### 3. 样式优先级
- 默认纹理优先级：纹理对象 > 纹理URL > emoji
- 样式设置会立即生效并刷新现有缩略图
### 4. 浏览器兼容性
- 支持现代浏览器的拖拽API
- 支持Canvas 2D渲染
- 需要支持ES6+语法
### 5. 性能考虑
- 大量文件时建议减小缩略图尺寸
- 网络图片建议使用CDN
- 及时清理不需要的对象URL
## 错误处理
### 常见错误及解决方案
1. **图片加载失败**
- 自动使用默认纹理
- 检查URL有效性
- 确认跨域设置
2. **组件初始化失败**
- 确认PixiJS已正确加载
- 检查依赖组件是否存在
- 验证配置参数格式
3. **拖拽功能异常**
- 检查浏览器拖拽API支持
- 确认文件权限设置
- 验证文件类型支持
## 完整示例
```javascript
// 完整的资源管理器使用示例
const app = new PIXI.Application({
width: 1200,
height: 800,
backgroundColor: 0x1a1a1a
});
document.body.appendChild(app.view);
// 创建资源管理器
const explorer = new 资源管理器();
// 初始化配置
const config = {
宽度: 1100,
高度: 700,
左侧宽度: 300,
背景颜色: 0x2c2c2c,
缩略宽度: 100,
缩略高度: 100,
默认emoji: '⚠️',
默认emoji颜色: 0xffa500
};
explorer.初始化(50, 50, config.宽度, config.高度, config);
// 设置默认纹理
explorer.设置默认纹理URL('https://example.com/error-image.png');
// 设置样式
explorer.设置区域样式({
左背景: 0x2a2a2a,
右背景: 0x3a3a3a,
左边框宽度: 1,
右边框宽度: 1
});
// 添加到舞台
app.stage.addChild(explorer.获取容器());
// 设置数据
const data = [
{
文本: "图片文件夹",
文件列表: [
{ name: "风景.jpg", url: "https://picsum.photos/400/300", type: "image" },
{ name: "头像.png", url: "https://picsum.photos/200/200", type: "image" }
]
},
{
文本: "文档文件夹",
文件列表: [
{ name: "说明.txt", content: "这是一个说明文档\n包含多行内容", type: "text" },
{ name: "配置.json", content: '{"name": "test", "value": 123}', type: "json" }
]
}
];
explorer.设置目录数据(data);
// 监听事件
explorer._树形.容器.on('节点选择', (节点数据) => {
console.log('选中文件夹:', 节点数据.文本);
});
```
这个文档涵盖了资源管理器组件的所有主要功能和使用方法。根据具体需求，您可以组合使用这些API来实现自定义的文件浏览体验。 |
|
发表
组件文档
36 人阅读
|
0 人回复
