超级列表框

admin

# 超级列表框组件文档

## 基本信息
超级列表框是一个支持网格布局的高级列表组件，每个格子支持自定义容器，可横向/纵向/混合排列。

## 初始化与配置

### 初始化
```javascript
var 列表框 = new 超级列表框();
列表框.初始化(x, y, 宽度, 高度, 选项);
```

### 配置选项
```javascript
{
    宽度: 400,           // 列表框宽度
    高度: 300,           // 列表框高度
    背景颜色: 0xf8f8f8,  // 背景颜色
    边框颜色: 0xcccccc,  // 边框颜色
    边框宽度: 1,         // 边框宽度
    圆角: 4,             // 圆角大小
    单元格宽度: 100,     // 默认单元格宽度
    单元格高度: 100,     // 默认单元格高度
    横向间距: 10,        // 单元格横向间距
    纵向间距: 10,        // 单元格纵向间距
    选中颜色: 0x4a90e2,  // 选中单元格背景颜色
    悬停颜色: 0xe8e8e8,  // 悬停单元格背景颜色
    布局模式: '纵向',    // 布局模式: '横向', '纵向', '网格'
    网格列数: 3,         // 网格模式时每行的列数
    允许穿透: false,     // 是否允许穿透
    调试模式: false,     // 是否启用调试模式
    单元格列表: [],      // 单元格数据列表
    自适应单元格: false, // 是否根据列表尺寸自动计算单元格宽度
}
```

## 滚动相关配置
```javascript
{
    滚动条宽度: 6,       // 滚动条宽度
    滚动条颜色: 0x999999, // 滚动条颜色
    滚动条透明度: 0.8,    // 滚动条透明度
    滚动步长: 40,         // 鼠标滚轮滚动步长
    允许拖动: true,       // 是否允许拖动
    边缘留白: 10,         // 四周留白
    允许水平滚动: true,   // 是否允许水平滚动
    允许垂直滚动: true,   // 是否允许垂直滚动
    滚动速度系数: 1.0,    // 滚动速度系数，值越大滚动越快
    平滑过渡系数: 0.25,   // 平滑过渡系数，值越大过渡越快
}
```

## 回弹与动画效果配置
```javascript
{
    回弹效果: true,       // 是否启用回弹效果
    回弹强度: 0.2,        // 回弹强度 (0-1)
    回弹阻尼: 0.92,       // 回弹阻尼系数，值越大越慢
    回弹缓动函数: 'Cubic.Out', // 回弹缓动函数类型
    回弹基础时间: 300,     // 回弹动画基础持续时间(毫秒)
    回弹最大时间: 600,     // 回弹动画最大持续时间(毫秒)
    回弹过渡系数: 0.15,   // 回弹过渡系数，值越小越平滑
    惯性系数: 800,        // 惯性滑动系数，值越大滑动距离越长
    惯性持续时间: 800,    // 惯性滑动持续时间(毫秒)
    惯性缓动函数: 'Cubic.Out', // 惯性滑动缓动函数
    动画帧率: 60,         // 动画帧率，值越高越流畅
    边界拖动系数: 0.5,    // 边界拖动系数
}
```

## 主要方法

### 数据操作
```javascript
// 设置数据
列表框.设置数据(单元格列表);

// 添加单元格
列表框.添加单元格(单元格数据, 是否选中);

// 插入单元格
列表框.插入单元格(位置索引, 单元格数据, 是否选中);

// 更新单元格
列表框.更新单元格(索引, 新数据);

// 删除单元格
列表框.删除单元格(索引);

// 清空列表
列表框.清空();
```

### 选择与查找
```javascript
// 选择单元格
列表框.选择单元格(单元格容器);

// 根据索引选择单元格
列表框.选择索引(索引);

// 获取选中数据
列表框.获取选中数据();

// 获取选中索引
列表框.获取选中索引();

// 查找单元格
列表框.查找单元格(条件函数);

// 滚动到指定单元格
列表框.滚动到单元格(索引);
```

### 布局设置
```javascript
// 设置布局模式
列表框.设置布局模式(模式); // '横向', '纵向', '网格'

// 设置网格列数
列表框.设置网格列数(列数);

// 设置自适应单元格
列表框.设置自适应单元格(启用);
```

### 滚动控制
```javascript
// 设置滚动速度
列表框.设置滚动速度(速度系数);

// 设置平滑过渡速度
列表框.设置平滑过渡速度(平滑系数);

// 设置回弹效果
列表框.设置回弹效果(启用, 强度, 阻尼, 缓动函数, 基础时间, 最大时间);

// 设置动画参数
列表框.设置动画参数(帧率, 平滑系数, 回弹平滑系数);

// 设置边界拖动系数
列表框.设置边界拖动系数(系数);

// 设置滚动条显示
列表框.设置滚动条显示(显示);

// 获取滚动条显示状态
列表框.获取滚动条显示();
```

### 尺寸与位置
```javascript
// 设置组件宽高
列表框.设置宽高(宽, 高);

// 设置组件位置
列表框.设置位置(x, y);

// 获取容器对象
列表框.获取容器();
```

### 资源管理
```javascript
// 销毁组件
列表框.销毁();
```

## 事件监听
可以通过容器的emit事件监听用户交互：
```javascript
列表框.获取容器().on('单元格点击', function(单元格数据, 索引) {
    // 处理单元格点击事件
});

列表框.获取容器().on('单元格选择', function(单元格数据, 索引) {
    // 处理单元格选择事件
});

列表框.获取容器().on('单元格鼠标进入', function(单元格数据, 索引) {
    // 处理单元格鼠标进入事件
});

列表框.获取容器().on('单元格鼠标离开', function(单元格数据, 索引) {
    // 处理单元格鼠标离开事件
});
```



### 新增方法和事件：

1. **设置滚动进度**：
   - `设置垂直滚动进度(进度)` - 设置垂直滚动位置，参数为0-1之间的值
   - `设置水平滚动进度(进度)` - 设置水平滚动位置，参数为0-1之间的值

2. **获取滚动进度**：
   - `获取垂直滚动进度()` - 返回当前垂直滚动位置的进度值（0-1之间）
   - `获取水平滚动进度()` - 返回当前水平滚动位置的进度值（0-1之间）

3. **滚动进度事件**：
   - `垂直滚动进度变化` - 当垂直滚动位置变化时触发，参数为当前进度值
   - `水平滚动进度变化` - 当水平滚动位置变化时触发，参数为当前进度值

### 使用示例：

```javascript
// 创建和初始化超级列表框
var 列表框 = new 超级列表框();
列表框.初始化(x, y, 宽度, 高度, 选项);
列表框.设置数据(数据列表);

// 隐藏内置滚动条
列表框.设置滚动条显示(false);

// 监听滚动进度变化事件
列表框.获取容器().on('垂直滚动进度变化', function(进度) {
    // 更新外部自定义滚动条位置
    自定义滚动条.position.y = 起始Y + 进度 * 可滑动高度;
});

// 设置外部滚动条的拖动事件
自定义滚动条.on('拖动', function(位置) {
    // 计算进度值 (0-1之间)
    var 进度 = (位置.y - 起始Y) / 可滑动高度;
   
    // 设置列表框的滚动位置
    列表框.设置垂直滚动进度(进度);
});
```

这些新增功能使超级列表框能够更好地与外部自定义UI元素（如图片制作的滚动条）集成，满足您提到的需求。您可以隐藏内置滚动条，使用自定义的图片滚动条，并通过这些新方法和事件保持它们的同步。

## 性能优化
组件使用虚拟列表技术，只渲染可视区域内的单元格，对于超出可视区域的单元格会创建占位符，以提高大数据量下的性能表现。