# CustomScrollView

**Repository Path**: maoyinhang/CustomScrollView

## Basic Information

- **Project Name**: CustomScrollView
- **Description**: Unity列表组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CustomScrollView

一个基于 Unity UGUI 的通用滚动列表框架，支持横向/纵向排列、可变 Item 尺寸、对象复用、嵌套滚动等。

## 环境

- **引擎**: Unity 2022.3 LTS (Tuanjie 1.8.5)
- **语言**: C#
- **依赖**: [DOTween](http://dotween.demigiant.com/)（已包含在 `Assets/Plugins/Demigiant/` 中）

## 快速开始

1. Clone 本仓库
2. 在 Unity 中打开场景 `Assets/Example/Example01/Scenes/SampleScene.unity`

## 目录结构

```
Assets/
├── Scripts/
│   ├── Common/
│   │   ├── UIEventListener.cs    # UI 事件监听器
│   │   └── UISubBehaviour.cs     # UI 子行为基类
│   └── Grid/
│       ├── CustomGrid.cs         # 网格布局基类（横向/纵向）
│       └── CustomItem.cs         # Cell 基类 & ICustomData 接口
├── Example/
│   └── Example01/
│       ├── Scenes/
│       │   └── SampleScene.unity # 嵌套列表示例场景
│       └── Scripts/
│           ├── MainScrollTable.cs  # 外围列表（垂直，嵌套子列表）
│           ├── MainCell.cs         # 外围列表 Cell
│           ├── MainItemData.cs     # 外围列表数据模型
│           ├── SubScrollTable.cs   # 内嵌列表（水平）
│           ├── SubCell.cs          # 内嵌列表 Cell
│           ├── SubItemData.cs      # 内嵌列表数据模型
│           └── UIFormViewTest.cs   # 示例入口脚本
│   └── Example02/
│       ├── Scenes/
│       │   └── Example02.scene       # 无限循列表示例场景
│       └── Scripts/
│           ├── LoopScrollTable.cs    # 循环列表（enableLoop=true）
│           ├── LoopCell.cs           # 循环列表 Cell
│           ├── LoopItemData.cs       # 循环列表数据模型
│           └── Example02.cs          # 示例入口脚本
├── Plugins/
│   └── Demigiant/DOTween/        # DOTween 插件
└── Resources/
    └── DOTweenSettings.asset     # DOTween 全局配置
```

## 核心架构

```
ICustomData              ← 数据接口（标记脏数据以便刷新）
    ↑
CustomItem<TData,TGrid>  ← Cell 基类（绑定数据、持有引用）
    ↑
CustomGrid<TData,TItem,TGrid>  ← 网格布局基类
                                • 对象池复用
                                • 可变尺寸
                                • 自动排列/回收
                                • 聚焦定位
                                • 无限循环（enableLoop）
```

### 关键类型

| 类型 | 命名空间 | 说明 |
|------|----------|------|
| `CustomGrid<TData,TItem,TGrid>` | `UIPlus` | 核心布局引擎，管理对象复用、排列、回收、循环 |
| `CustomItem<TData,TGrid>` | `UIPlus` | Cell 基类，提供 `Refresh(data)` 刷新接口 |
| `ICustomData` | `UIPlus` | 数据接口，`IsDirty` 标记变更以触发 UI 刷新 |

## 特性

- **对象复用**：仅创建可视区域内的 Cell，滚动时自动回收复用
- **可变尺寸**：通过 `useVariableItemSize` 控制，或子类重写 `GetItemHeight`/`GetItemWidth`
- **嵌套滚动**：支持外层垂直 + 内层水平嵌套（见 Example01 示例）
- **DOTween 动画**：Cell 出场缩放/淡入动画，内置交错延迟支持
- **滚动动画**：支持带缓动的滚动到指定位置或底部
- **数据脏标记**：`ICustomData.IsDirty` 机制，仅变更的数据触发 UI 刷新

## 使用示例

### 定义数据模型

```csharp
using UIPlus;

public class MyItemData : ICustomData
{
    public string Title;
    public bool IsDirty { get; set; }
}
```

### 定义 Cell

```csharp
using UnityEngine.UI;
using UIPlus;

public class MyCell : CustomItem<MyItemData, MyScrollTable>
{
    public Text titleText;

    public override void Refresh(MyItemData data)
    {
        base.Refresh(data);
        titleText.text = data.Title;
    }
}
```

### 定义列表

```csharp
using UnityEngine;
using UIPlus;

public class MyScrollTable : CustomGrid<MyItemData, MyCell, MyScrollTable>
{
    protected override bool useVariableItemSize => true;

    protected override MyCell CreateGridItem(GameObject go)
    {
        return go.GetComponent<MyCell>() ?? go.AddComponent<MyCell>();
    }

    protected override GameObject GetItemObj()
    {
        // 返回预制体引用
        return mItemPrefab;
    }
}
```