|
|
# 列表框组件文档
## 概述
列表框是一个多列多行数据展示组件，支持表头、表格线、行选择、滚动等功能。类似电子表格，但针对PIXI环境优化，支持完全自定义单元格内容。
## 创建与初始化
```javascript
// 创建实例
var myList = new 列表框();
// 初始化
myList.初始化(x坐标, y坐标, 宽度, 高度, 选项);
// 添加到PIXI舞台
app.stage.addChild(myList.获取容器());
```
## 配置选项
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| 宽度 | Number | 400 | 列表框宽度 |
| 高度 | Number | 300 | 列表框高度 |
| 背景颜色 | Number | 0xf8f8f8 | 背景颜色 |
| 边框颜色 | Number | 0xcccccc | 边框颜色 |
| 边框宽度 | Number | 1 | 边框宽度 |
| 圆角 | Number | 4 | 圆角大小 |
| 行高度 | Number | 30 | 默认行高度 |
| 行间距 | Number | 2 | 行之间的间距 |
| 列间距 | Number | 10 | 列之间的间距 |
| 选中颜色 | Number | 0x4a90e2 | 选中行背景颜色 |
| 悬停颜色 | Number | 0xe8e8e8 | 鼠标悬停时行背景颜色 |
| 文本颜色 | Number | 0x333333 | 文本颜色 |
| 文本大小 | Number | 14 | 文本字体大小 |
| 文本字体 | String | 'Arial' | 文本字体 |
| 显示表头 | Boolean | true | 是否显示表头 |
| 表头高度 | Number | 24 | 表头高度 |
| 表头颜色 | Number | 0xe0e0e0 | 表头背景颜色 |
| 表头文本颜色 | Number | 0x333333 | 表头文本颜色 |
| 滚动条宽度 | Number | 6 | 滚动条宽度 |
| 滚动条颜色 | Number | 0x999999 | 滚动条颜色 |
| 滚动条透明度 | Number | 0.8 | 滚动条透明度 |
| 滚动步长 | Number | 40 | 鼠标滚轮滚动步长 |
| 额外行高 | Number | 0 | 全局额外行高补偿 |
| 隔行变色 | Boolean | false | 是否隔行变色 |
| 奇数行颜色 | Number | 0xf5f5f5 | 奇数行背景色 |
| 偶数行颜色 | Number | 0xffffff | 偶数行背景色 |
| 网格线 | Boolean | false | 是否显示网格线 |
| 网格线颜色 | Number | 0xdddddd | 网格线颜色 |
| 数据列表 | Array | [] | 行数据列表 |
| 表头数据 | Array | [] | 列定义数据 |
## 表头数据格式
表头数据是一个对象数组，每个对象定义一列的属性：
```javascript
let 表头数据 = [
{ 标题: '序号', 键: 'id', 宽度: 50, 对齐: 'center' },
{ 标题: '名称', 键: 'name', 宽度: 150 },
{ 标题: '类型', 键: 'type', 宽度: 100 },
{ 标题: '创建时间', 键: 'time', 宽度: 180 }
]
```
| 属性 | 类型 | 说明 |
|------|------|------|
| 标题 | String | 列标题文本 |
| 键 | String | 对应行数据中的属性名 |
| 宽度 | Number | 列宽度 |
| 对齐 | String | 文本对齐方式，可选 'left'、'center'、'right' |
## 行数据格式
行数据是一个对象数组，每个对象包含与表头键名对应的数据：
```javascript
let 行数据 = [
{ id: 1, name: '项目A', type: '文档', time: '2023-05-15' },
{ id: 2, name: '项目B', type: '图像', time: '2023-05-16' }
]
```
### 自定义单元格
任何单元格的值可以是文本或数值，也可以是PIXI.Container对象：
```javascript
{
id: 3,
name: '项目C',
type: (function() {
// 创建自定义容器
let container = new PIXI.Container();
// 添加图标
let icon = new PIXI.Graphics();
icon.beginFill(0xff0000);
icon.drawCircle(0, 0, 5);
icon.endFill();
// 添加文本
let text = new PIXI.Text('自定义', { fontSize: 14 });
text.position.set(10, 0);
container.addChild(icon, text);
return container;
})(),
time: '2023-05-18'
}
```
### 自定义整行
通过提供`自定义容器`属性，可以完全自定义一行的渲染：
```javascript
{
自定义容器: (function() {
let container = new PIXI.Container();
// 创建自定义行内容...
return container;
})(),
// 其他数据属性仍然可以保留，但不会用于渲染
id: 4,
name: '自定义行'
}
```
### 自定义行高
每行可以设置独立的行高：
```javascript
{
id: 5,
name: '高行',
自定义行高: 60 // 单位：像素
}
```
## API方法
### 基础方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| 初始化 | (x, y, 宽, 高, 选项) | - | 初始化列表框 |
| 设置宽高 | (类型, 宽, 高) | - | 设置组件宽高，类型：0固定、1百分比、3最大不超父容器 |
| 设置位置 | (x, y) | - | 设置组件位置 |
| 设置X坐标 | (x) | - | 设置X坐标 |
| 设置Y坐标 | (y) | - | 设置Y坐标 |
| 获取位置 | () | {x, y} | 获取组件位置 |
| 获取容器 | () | PIXI.Container | 获取组件容器对象 |
| 销毁 | () | - | 销毁组件 |
### 数据操作方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| 设置数据列表 | (数据列表) | - | 设置整个数据列表 |
| 设置表头数据 | (表头数据) | - | 设置表头数据 |
| 添加行 | (行数据, 选中) | Number | 添加一行，返回新行索引 |
| 插入行 | (位置索引, 行数据, 选中) | Number | 在指定位置插入行，返回插入行索引 |
| 删除行 | (行索引) | Boolean | 删除指定行，返回是否成功 |
| 更新行 | (行索引, 新数据) | Boolean | 更新指定行的多个字段，返回是否成功 |
| 更新单元格 | (行索引, 列键, 新值) | Boolean | 更新单个单元格的值，返回是否成功 |
| 清空 | () | - | 清空所有数据 |
### 选择相关方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| 选择行 | (行容器) | - | 选择指定行容器 |
| 选择行索引 | (索引) | - | 通过索引选择行 |
| 获取选中行 | () | Object/null | 获取选中行的数据 |
| 获取选中索引 | () | Number/null | 获取选中行的索引 |
### 样式设置方法
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| 设置行间距 | (间距) | - | 设置行间距(像素) |
| 设置额外行高 | (像素) | - | 设置全局额外行高补偿 |
## 事件
通过监听列表框容器的事件可以响应用户交互：
```javascript
myList.获取容器().on('行选择', function(行数据, 行索引) {
console.log('选中行:', 行索引, 行数据);
});
```
| 事件名称 | 回调参数 | 说明 |
|---------|----------|------|
| 行选择 | (行数据, 行索引) | 当用户选择一行时触发 |
## 完整使用示例
```javascript
// 创建PIXI应用
const app = new PIXI.Application({
width: 800,
height: 600,
backgroundColor: 0xf0f0f0
});
document.body.appendChild(app.view);
// 创建列表框
const myList = new 列表框();
// 定义表头
const 表头 = [
{ 标题: '序号', 键: 'id', 宽度: 50, 对齐: 'center' },
{ 标题: '名称', 键: 'name', 宽度: 150 },
{ 标题: '类型', 键: 'type', 宽度: 100 },
{ 标题: '时间', 键: 'time', 宽度: 120 }
];
// 初始化列表框
myList.初始化(50, 50, 500, 400, {
表头数据: 表头,
网格线: true,
隔行变色: true
});
// 添加到舞台
app.stage.addChild(myList.获取容器());
// 添加测试数据
myList.添加行({ id: 1, name: '项目A', type: '文档', time: '10:30' }, true);
myList.添加行({ id: 2, name: '项目B', type: '图像', time: '11:45' });
myList.添加行({ id: 3, name: '项目C', type: '视频', time: '13:20' });
// 添加一个自定义单元格的行
myList.添加行({
id: 4,
name: '项目D',
type: (function() {
let container = new PIXI.Container();
let icon = new PIXI.Graphics();
icon.beginFill(0xff3300);
icon.drawCircle(0, 0, 6);
icon.endFill();
icon.position.set(5, 8);
let text = new PIXI.Text('重要', {
fontSize: 12,
fill: 0xff0000
});
text.position.set(15, 2);
container.addChild(icon, text);
return container;
})(),
time: '14:10'
});
// 添加一个自定义整行
myList.添加行({
自定义容器: (function() {
let container = new PIXI.Container();
let bg = new PIXI.Graphics();
bg.beginFill(0xfffbe6);
bg.drawRect(0, 0, 480, 40);
bg.endFill();
let text = new PIXI.Text('✨ 自定义特殊行', {
fontSize: 16,
fill: 0x995500,
fontWeight: 'bold'
});
text.position.set(20, 10);
container.addChild(bg, text);
return container;
})()
});
// 监听选择事件
myList.获取容器().on('行选择', function(行数据, 行索引) {
console.log('选中:', 行索引, 行数据);
});
// 响应式布局示例
window.addEventListener('resize', function() {
// 宽度为窗口宽度的80%，高度为窗口高度的70%
myList.设置宽高(1, '80%', '70%');
});
```
## 注意事项
1. **性能考虑**：
- 对于大量数据，建议分批加载或使用虚拟滚动
- 复杂自定义容器可能影响性能，尽量复用容器
2. **自定义单元格**：
- 自定义容器的坐标系原点是单元格内左上角
- 容器的尺寸应与单元格相适应
3. **事件处理**：
- 行选择事件(`行选择`)在用户点击行时触发
- 可通过`myList.获取容器().on('行选择', callback)`监听
4. **布局适配**：
- `设置宽高(1, '100%', '100%')`可实现全屏适配
- 当使用百分比宽高时，确保父容器有明确的尺寸
5. **销毁组件**：
- 不再使用时调用`销毁()`方法释放资源
- 注意移除事件监听器以避免内存泄漏
|
|
发表
组件文档
32 人阅读
|
0 人回复
