AlicizaX/Client/Assets/Books/UIExtension/RecyclerView.md

# RecyclerView 专业手册

> 📌 本文档基于 `Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView` 的运行时 API 编写，重点说明业务侧可直接调用的能力；文中提到的 `private` / `internal` 成员仅用于解释内部机制，不属于业务层 API。
>
> ⚠️ `SetAdapter()`、`Reset()`、`Refresh()`、`RequestLayout()` 已收敛为框架内部流程；业务层请通过 `UGList`、`UGListCreateHelper`、`UGList.Data`、`Adapter.SetList()`、`Notify*()` 等正式入口驱动列表更新，不要手动调用这些底层方法。所有 UI 相关调用仍应统一放在 Unity 主线程。
>
> 💡 `RecyclerView` 的 `LayoutManager` 与 `Scroller` 通过 Inspector 序列化引用配置，业务代码通常只“读取与使用”，不建议在运行中直接替换类型。

## 目录

- [模块概览](#overview)
- [基础概念与共享示例类型](#basics)
- [容器（RecyclerView）](#container)
  - [API 说明](#container-api)
  - [初始化与刷新](#container-init)
  - [定位与焦点控制](#container-focus)
- [适配器（Adapter / GroupAdapter / LoopAdapter / MixedAdapter）](#adapter)
  - [API 说明](#adapter-api)
  - [基础数据更新](#adapter-data)
  - [多模板、分组与循环](#adapter-advanced)
- [布局（LayoutManager 系列）](#layout)
  - [API 说明](#layout-api)
  - [线性与网格布局](#layout-basic)
  - [分页、圆环与异构长度布局](#layout-advanced)
- [滚动器（Scroller / CircleScroller）](#scroller)
  - [API 说明](#scroller-api)
  - [程序化滚动](#scroller-programmatic)
  - [惯性、吸附与自动播放](#scroller-advanced)
- [视图池（ViewProvider / ObjectPool）](#pool)
  - [API 说明](#pool-api)
  - [预热与复用](#pool-basic)
  - [多模板对象池配置](#pool-mixed)
- [导航（RecyclerNavigation）](#navigation)
  - [API 说明](#navigation-api)
  - [列表内导航](#navigation-inner)
  - [列表入口与焦点恢复](#navigation-entry)
- [业务包装层（UGList / UGListExtensions）](#uglist)
  - [API 说明](#uglist-api)
  - [快速创建与滚动扩展](#uglist-basic)
  - [业务封装示例](#uglist-advanced)
- [场景专题](#scenarios)
  - [大量列表项复用（含对象池配置）](#scenario-massive)
  - [多模板混排](#scenario-mixed)
  - [分页加载（加载态、空态、错误态）](#scenario-paging)
  - [轮播与循环滚动（自动播放、手动切换）](#scenario-carousel)
  - [手柄/键盘导航结合列表滚动](#scenario-nav-scroll)
- [FAQ](#faq)
- [Anti-patterns](#anti-patterns)
- [性能优化建议](#performance)
- [交付前检查清单](#checklist)

<a id="overview"></a>
## 模块概览

`RecyclerView` 是一套面向 Unity UGUI 的高性能列表组件，职责拆分如下：

- 容器：`RecyclerView` 负责模板、可见区、滚动同步、滚动条、焦点恢复。
- 适配器：`Adapter<T>` 家族负责数据量、模板选择、视图绑定、局部刷新。
- 布局：`LayoutManager` 家族负责位置计算、可见区间与索引转换。
- 滚动器：`Scroller` 家族负责拖拽、滚轮、惯性、吸附与平滑滚动。
- 视图池：`ViewProvider` + `ObjectPool` 负责创建、回收、预热与统计。
- 导航：`RecyclerNavigationController` 家族负责手柄/键盘在列表内的可达性。
- 业务包装层：`UGList` 家族负责降低泛型与注册样板代码。

> 💡 一般调用顺序是：准备模板与布局 → 创建业务包装层/适配器包装 → 注册 `ItemRender` → 赋值数据；后续布局计算、池预热与首屏刷新由框架自动完成。

> ⚠️ 如果 `Templates` 为空、`LayoutManager` 未配置或 `Content` 解析失败，`RecyclerView` 会在首次运行时抛出错误或记录错误日志。

<a id="basics"></a>
## 基础概念与共享示例类型

本节给出后续示例默认共用的最小类型。除非某个示例额外声明了自己的 `Data` / `Holder` / `Render`，否则都可以直接与以下代码一起编译。

### 示例基础类型

#### 共享类型代码
```csharp
using AlicizaX.UI;
using UnityEngine;
using UnityEngine.EventSystems;
using UnityEngine.UI;

namespace RecyclerViewBookSamples
{
    [System.Serializable]
    public sealed class DemoSimpleData : ISimpleViewData
    {
        public string Title;
        public string Subtitle;
        public Sprite Icon;
    }

    [System.Serializable]
    public sealed class DemoMixedData : IMixedViewData
    {
        public string TemplateName { get; set; } // 必须与模板名完全一致
        public string Title;
        public string Subtitle;
        public Sprite Icon;
    }

    [System.Serializable]
    public sealed class DemoGroupData : IGroupViewData
    {
        public string TemplateName { get; set; } // 组头与普通项共用此字段
        public bool Expanded { get; set; }       // 组头展开状态
        public int Type { get; set; }            // 分组键
        public string Title;
    }

    public sealed class DemoItemHolder : ViewHolder
    {
        public Text title;
        public Text subtitle;
        public Image icon;
        public Button actionButton;
        public GameObject selectedMarker;
    }

    public sealed class DemoStateHolder : ViewHolder
    {
        public Text message;
        public Button retryButton;
    }

    public sealed class DemoSimpleRender : ItemRender<DemoSimpleData, DemoItemHolder>
    {
        protected override void OnBind(DemoSimpleData data, int index)
        {
            Holder.title.text = $"{index + 1}. {data.Title}";     // 绑定标题
            Holder.subtitle.text = data.Subtitle;                 // 绑定副标题
            Holder.icon.sprite = data.Icon;                       // 绑定图标
        }

        protected override void OnSelectionChanged(bool selected)
        {
            if (Holder.selectedMarker != null)
            {
                Holder.selectedMarker.SetActive(selected);        // 显示选中态
            }
        }
    }

    public sealed class DemoMixedRender : ItemRender<DemoMixedData, DemoItemHolder>
    {
        protected override void OnBind(DemoMixedData data, int index)
        {
            Holder.title.text = $"{index + 1}. {data.Title}";     // 绑定标题
            Holder.subtitle.text = data.Subtitle;                 // 绑定副标题
            Holder.icon.sprite = data.Icon;                       // 绑定图标
        }
    }
}
```

> 📌 所有示例都默认你已经在 Inspector 中把模板预制体上的 `Text`、`Image`、`Button` 等引用拖好。

<a id="container"></a>
## 容器（RecyclerView）

`RecyclerView` 是系统的中心节点：它管理模板、内容区域、当前适配器、布局、滚动器、滚动条以及焦点导航。

<a id="container-api"></a>
### API 说明

#### 类型：`RecyclerView`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/RecyclerView.cs`

**属性**

| 成员名 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Direction` | `Direction` | `Direction.Vertical`（未序列化时） | 主滚动方向。 | 与 `LayoutManager`、`Scroller` 的方向必须一致。 |
| `Alignment` | `Alignment` | `Alignment.Left`（未序列化时） | 交叉轴对齐方式。 | `Alignment.Center` 会影响内容偏移计算。 |
| `Spacing` | `Vector2` | `Vector2.zero` | Item 间距。 | 竖向列表通常使用 `y`；横向列表通常使用 `x`。 |
| `Padding` | `Vector2` | `Vector2.zero` | 内容内边距。 | 只影响布局计算，不会自动改模板尺寸。 |
| `Scroll` | `bool` | `false` | 是否启用滚动。 | 关闭后 `ScrollTo*()` 直接失效。 |
| `Snap` | `bool` | `false` | 是否在停下后吸附到最近项。 | 只有 `Scroll == true` 时才会真正生效。 |
| `ScrollSpeed` | `float` | `7f` | 平滑滚动速度。 | 建议保持在 `0.5f ~ 50f`。 |
| `WheelSpeed` | `float` | `30f` | 滚轮速度。 | 建议保持在 `1f ~ 50f`。 |
| `ShowScrollBarOnlyWhenScrollable` | `bool` | `false` | 是否仅在内容溢出时显示滚动条。 | 仅对横向/纵向方向生效。 |
| `Templates` | `ViewHolder[]` | `null` | 视图模板集合。 | 不能为空；多模板时模板名必须唯一。 |
| `Content` | `RectTransform` | `null`，首次访问时尝试取第一个子节点 | 内容容器。 | 第一个子节点必须有 `RectTransform`。 |
| `Scrollbar` | `Scrollbar` | `null` | 关联滚动条。 | 仅在启用滚动条时使用。 |
| `Scroller` | `Scroller` | `null` | 当前滚动器实例。 | 通常由 Inspector 指定为 `Scroller` 或 `CircleScroller`。 |
| `ViewProvider` | `ViewProvider` | 懒加载 | 模板创建/回收提供器。 | 依赖 `Templates` 正常初始化。 |
| `PoolStats` | `string` | `string.Empty` | 当前视图池统计文本。 | 仅用于诊断，格式不保证长期稳定。 |
| `LayoutManager` | `LayoutManager` | `null` | 当前布局实例。 | 必须先配置，否则列表初始化时无法完成绑定。 |
| `NavigationController` | `RecyclerNavigationController` | 懒加载 | 列表导航控制器。 | 仅在导航场景下用到。 |

**事件**

| 事件名 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `OnIndexChanged` | `Action<int>` | `null` | 当前逻辑索引变化时触发。 | 对循环列表返回的是“真实索引”。 |
| `OnScrollValueChanged` | `Action` | `null` | 滚动位置变化时触发。 | 高频事件，不要在回调里做重活。 |

> 💡 业务层如需感知当前焦点项，请监听 `OnIndexChanged`；如需读写业务选中态，请使用 `Adapter.ChoiceIndex`。

**方法**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `TryFocusIndex(int index, bool smooth = false, ScrollAlignment alignment = ScrollAlignment.Center)` | `bool` | `smooth=false`, `alignment=Center` | 滚动并聚焦目标项。 | 目标索引必须在适配器合法范围内。 |
| `TryFocusEntry(MoveDirection entryDirection)` | `bool` | 无 | 从外部把焦点“送入”列表。 | 空列表返回 `false`。 |
| `GetScrollPosition()` | `float` | 无 | 获取当前滚动偏移。 | 没有滚动器时返回 `0`。 |
| `ScrollTo(int index, bool smooth = false)` | `void` | `smooth=false` | 滚到指定项。 | 依赖 `Scroll == true` 且 `Scroller != null`。 |
| `ScrollToWithAlignment(int index, ScrollAlignment alignment, float offset = 0f, bool smooth = false, float duration = 0.3f)` | `void` | `offset=0f`, `smooth=false`, `duration=0.3f` | 以指定对齐方式滚动到目标项。 | `duration` 仅在 `smooth=true` 时有意义。 |

#### 参数：`TryFocusIndex(int index, bool smooth = false, ScrollAlignment alignment = ScrollAlignment.Center)`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `index` | `int` | 无 | 目标数据索引。 |
| `smooth` | `bool` | `false` | 是否先平滑滚动到可见区再聚焦。 |
| `alignment` | `ScrollAlignment` | `ScrollAlignment.Center` | 聚焦时目标项的对齐方式。 |

- 返回值：`bool`，成功定位并设置焦点时为 `true`。
- 使用限制：空列表、越界索引或没有可聚焦对象都会返回 `false`。

#### 参数：`ScrollToWithAlignment(...)`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `index` | `int` | 无 | 目标索引。 |
| `alignment` | `ScrollAlignment` | 无 | 目标项停靠位置。 |
| `offset` | `float` | `0f` | 在对齐结果基础上的附加偏移。 |
| `smooth` | `bool` | `false` | 是否平滑滚动。 |
| `duration` | `float` | `0.3f` | 平滑滚动时长。 |

- 返回值：无。
- 使用限制：`Scroll == false`、`Scroller == null` 或目标索引非法时无效果。

> ⚠️ `ScrollTo()` / `TryFocusIndex()` 依赖列表已通过 `UGList.Data`、`Adapter.SetList()` 或 `Notify*()` 完成一次正式更新；布局与刷新会随这些入口自动完成，业务层不要额外手动补 `RequestLayout()` / `Refresh()`。

<a id="container-init"></a>
### 初始化与刷新

#### 示例 1：基础纵向列表初始化
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class BasicRecyclerViewDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: 绑定 LinearLayoutManager + Scroller

    private UGList<DemoSimpleData> list;

    private void Awake()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();      // 注册默认模板渲染器
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "邮件", Subtitle = "今天 09:00" },
            new DemoSimpleData { Title = "任务", Subtitle = "今天 10:30" },
            new DemoSimpleData { Title = "公告", Subtitle = "今天 14:00" },
        };
    }
}
```

#### 示例 2：异步拉取后再刷新容器
```csharp
using System.Collections;
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class AsyncRecyclerViewDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;   // Inspector: 模板与 LayoutManager 已配置

    private UGList<DemoSimpleData> list;
    private Adapter<DemoSimpleData> adapter;

    private IEnumerator Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        adapter = list.Adapter;

        yield return new WaitForSeconds(0.5f);           // 模拟网络请求

        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "远程数据 A", Subtitle = "加载完成" },
            new DemoSimpleData { Title = "远程数据 B", Subtitle = "加载完成" },
        };                                               // 赋值后框架自动布局并刷新
    }
}
```

#### 示例 3：空数据与安全刷新
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class EmptyStateRecyclerViewDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;

    private void OnEnable()
    {
        list ??= UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>();          // 空列表也是合法输入

        bool focused = recyclerView.TryFocusIndex(0);    // 空列表会返回 false
        Debug.Log($"Focus result: {focused}");
    }
}
```

<a id="container-focus"></a>
### 定位与焦点控制

#### 示例 1：按钮驱动滚动到指定项
```csharp
using AlicizaX.UI;
using UnityEngine;
using UnityEngine.UI;

public sealed class ScrollToIndexDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    [SerializeField] private Button jumpButton;

    private void Awake()
    {
        jumpButton.onClick.AddListener(() =>
        {
            recyclerView.ScrollToWithAlignment(
                index: 10,
                alignment: ScrollAlignment.Center,
                offset: 0f,
                smooth: true,
                duration: 0.25f);                        // 以 0.25 秒平滑滚到中间
        });
    }
}
```

#### 示例 2：打开面板时恢复焦点
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class FocusRecoveryDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    [SerializeField] private int lastSelectedIndex = 4;

    private void OnEnable()
    {
        recyclerView.TryFocusIndex(lastSelectedIndex, true, ScrollAlignment.Center);
    }
}
```

#### 示例 3：监听焦点索引变化
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class FocusTraceDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index =>
            Debug.Log($"Focused data index: {index}");
    }
}
```

<a id="adapter"></a>
## 适配器（Adapter / GroupAdapter / LoopAdapter / MixedAdapter）

适配器负责把数据对象映射为模板名、绑定流程和局部刷新操作，是业务层最常直接扩展的模块。

<a id="adapter-api"></a>
### API 说明

#### 类型：`Adapter<T>`（`where T : ISimpleViewData`）

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/Adapter/Adapter.cs`

**构造与状态**

| 成员名 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Adapter(RecyclerView recyclerView)` | 构造函数 | `list = new List<T>()` | 创建空适配器。 | `recyclerView` 不能为空。 |
| `Adapter(RecyclerView recyclerView, List<T> list)` | 构造函数 | `list ?? new List<T>()` | 创建带初始数据的适配器。 | 传入 `null` 会被替换为空列表。 |
| `ChoiceIndex` | `int` | `-1` | 当前选择索引。 | 超出范围会被自动收敛。 |

**查询与绑定**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GetItemCount()` | `int` | 无 | 当前布局项数量。 | 普通列表等于数据量；循环列表可能不是。 |
| `GetRealCount()` | `int` | 无 | 真实数据量。 | 循环列表场景优先用它。 |
| `GetViewName(int index)` | `string` | 无 | 返回模板名。 | 单模板默认返回空字符串。 |
| `OnBindViewHolder(ViewHolder viewHolder, int index)` | `void` | 无 | 绑定 Holder。 | 必须先注册与模板匹配的 `ItemRender`。 |
| `OnRecycleViewHolder(ViewHolder viewHolder)` | `void` | 无 | 回收前清理绑定。 | 业务层通常无需手动调用。 |
| `GetData(int index)` | `T` | 无 | 返回数据项。 | 越界返回 `default`。 |

**刷新通知**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `NotifyDataChanged()` | `void` | 无 | 全量刷新。 | 代价最高。 |
| `SetList(List<T> list)` | `void` | 无 | 替换整个数据源。 | 会触发 `RecyclerView.Reset()`。 |
| `NotifyItemChanged(int index, bool relayout = false)` | `void` | `relayout=false` | 刷新单项。 | 仅当项尺寸不变时推荐 `relayout=false`。 |
| `NotifyItemRangeChanged(int index, int count, bool relayout = false)` | `void` | `relayout=false` | 刷新区间。 | `count <= 0` 直接返回。 |
| `NotifyItemInserted(int index)` | `void` | 无 | 通知插入。 | 当前实现会重新请求布局并刷新。 |
| `NotifyItemRangeInserted(int index, int count)` | `void` | 无 | 通知批量插入。 | `count <= 0` 直接返回。 |
| `NotifyItemRemoved(int index)` | `void` | 无 | 通知删除。 | 当前实现会重新请求布局并刷新。 |
| `NotifyItemRangeRemoved(int index, int count)` | `void` | 无 | 通知批量删除。 | `count <= 0` 直接返回。 |

**渲染器注册**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `RegisterItemRender<TItemRender>(string viewName = "")` | `void` | `viewName=""` | 以泛型注册渲染器。 | 空字符串表示默认模板。 |
| `RegisterItemRender(Type itemRenderType, string viewName = "")` | `void` | `viewName=""` | 以运行时类型注册渲染器。 | 类型必须继承 `ItemRenderBase`。 |
| `UnregisterItemRender(string viewName = "")` | `bool` | `viewName=""` | 注销渲染器。 | 注销后相关缓存会被释放。 |
| `ClearItemRenderRegistrations()` | `void` | 无 | 清空所有注册。 | 适合切换整套模板时使用。 |

**集合操作**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Add(T item)` | `void` | 无 | 末尾追加。 | 自动触发插入通知。 |
| `AddRange(IEnumerable<T> collection)` | `void` | 无 | 批量追加。 | `collection == null` 时忽略。 |
| `Insert(int index, T item)` | `void` | 无 | 指定位置插入。 | 越界由 `List<T>` 自己抛错。 |
| `InsertRange(int index, IEnumerable<T> collection)` | `void` | 无 | 批量插入。 | `collection == null` 时忽略。 |
| `Remove(T item)` | `void` | 无 | 删除首个匹配项。 | 找不到时等价于 `RemoveAt(-1)`，最终无效果。 |
| `RemoveAt(int index)` | `void` | 无 | 删除指定索引。 | 越界直接返回。 |
| `RemoveRange(int index, int count)` | `void` | 无 | 删除区间。 | 参数必须满足 `List<T>.RemoveRange` 要求。 |
| `RemoveAll(Predicate<T> match)` | `void` | 无 | 条件删除。 | 始终触发全量刷新。 |
| `Clear()` | `void` | 无 | 清空列表。 | 空列表时直接返回。 |
| `Reverse()` / `Reverse(int index, int count)` | `void` | 无 | 反转顺序。 | 最终触发全量刷新。 |
| `Sort(Comparison<T> comparison)` | `void` | 无 | 排序。 | 最终触发全量刷新。 |

#### 类型：`GroupAdapter<TData>`（`where TData : IGroupViewData, new()`）

| 方法/成员 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GroupAdapter(RecyclerView recyclerView, string groupViewName)` | 构造函数 | 无 | 指定组头模板名。 | `NotifyDataChanged()` 前必须传非空模板名。 |
| `Expand(int index)` | `void` | 无 | 展开组头后的子项。 | `index` 必须指向组头。 |
| `Collapse(int index)` | `void` | 无 | 收起某组。 | 不会改原始 `list`，只改展示列表。 |
| `Activate(int index)` | `void` | 无 | 组头时切换展开；普通项时切换选中。 | 常用于点击事件。 |

#### 类型：`LoopAdapter<T>`

| 方法/成员 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GetItemCount()` | `int` | 无 | 有数据时返回 `int.MaxValue`。 | 只适合循环/轮播场景。 |
| `GetRealCount()` | `int` | 无 | 返回真实数据量。 | 业务逻辑应优先使用此值。 |
| `OnBindViewHolder(...)` | `void` | 无 | 绑定时对索引做取模。 | 数据为空时不绑定。 |

#### 类型：`MixedAdapter<TData>`（`where TData : IMixedViewData`）

| 方法/成员 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GetViewName(int index)` | `string` | 无 | 返回 `TemplateName`。 | 模板名必须与 `Templates[].name` 一致。 |

#### 参数：`RegisterItemRender(Type itemRenderType, string viewName = "")`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `itemRenderType` | `Type` | 无 | 渲染器运行时类型。 |
| `viewName` | `string` | `""` | 关联模板名；空字符串表示默认模板。 |

- 返回值：无。
- 使用限制：类型必须可实例化，且继承自 `ItemRenderBase`。

#### 参数：`NotifyItemChanged(int index, bool relayout = false)`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `index` | `int` | 无 | 目标数据索引。 |
| `relayout` | `bool` | `false` | 是否重新计算布局。 |

- 返回值：无。
- 使用限制：如果文本高度、图片尺寸、模板类型发生变化，应该传 `relayout=true`。

<a id="adapter-data"></a>
### 基础数据更新

#### 示例 1：通过 `UGList.Adapter` 进行增删改
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class AdapterCrudDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;
    private Adapter<DemoSimpleData> adapter;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>();
        adapter = list.Adapter;

        adapter.Add(new DemoSimpleData { Title = "第一条", Subtitle = "Add()" }); // 自动触发插入
        adapter.Add(new DemoSimpleData { Title = "第二条", Subtitle = "Add()" });
        adapter.Insert(1, new DemoSimpleData { Title = "插入项", Subtitle = "Insert()" });
    }
}
```

#### 示例 2：差量刷新单项与区间
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class AdapterPartialRefreshDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;
    private Adapter<DemoSimpleData> adapter;
    private readonly List<DemoSimpleData> data = new();

    private void Start()
    {
        data.Add(new DemoSimpleData { Title = "HP", Subtitle = "100" });
        data.Add(new DemoSimpleData { Title = "MP", Subtitle = "60" });
        data.Add(new DemoSimpleData { Title = "SP", Subtitle = "30" });

        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = data;
        adapter = list.Adapter;
    }

    public void UpdateHud()
    {
        data[0].Subtitle = "95";
        adapter.NotifyItemChanged(0);                    // 尺寸不变，只重绑可见项

        data[1].Subtitle = "58";
        data[2].Subtitle = "28";
        adapter.NotifyItemRangeChanged(1, 2);            // 批量局部刷新
    }
}
```

#### 示例 3：尺寸变化时强制重布局
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class AdapterRelayoutDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;
    private Adapter<DemoSimpleData> adapter;
    private readonly List<DemoSimpleData> data = new();

    private void Start()
    {
        data.Add(new DemoSimpleData { Title = "短文本", Subtitle = "1 行" });
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = data;
        adapter = list.Adapter;
    }

    public void ExpandText()
    {
        data[0].Subtitle = "这一条文本被拉长后可能导致高度变化，因此需要 relayout=true。";
        adapter.NotifyItemChanged(0, relayout: true);   // 尺寸变化时必须重布局
    }
}
```

<a id="adapter-advanced"></a>
### 多模板、分组与循环

#### 示例 1：多模板注册与绑定
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class DemoLargeHolder : ViewHolder
{
    public UnityEngine.UI.Text title;
    public UnityEngine.UI.Text subtitle;
}

public sealed class DemoLargeRender : ItemRender<DemoMixedData, DemoLargeHolder>
{
    protected override void OnBind(DemoMixedData data, int index)
    {
        Holder.title.text = $"[L] {data.Title}";        // 大卡片模板
        Holder.subtitle.text = data.Subtitle;
    }
}

public sealed class MixedAdapterDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: Templates 含 DemoItemHolder 与 DemoLargeHolder

    private UGMixedList<DemoMixedData> list;

    private void Start()
    {
        list = UGListCreateHelper.CreateMixed<DemoMixedData>(recyclerView);
        list.RegisterItemRender<DemoMixedRender>("SmallItem"); // 绑定小模板
        list.RegisterItemRender<DemoLargeRender>("LargeItem");  // 绑定大模板

        list.Data = new List<DemoMixedData>
        {
            new DemoMixedData { TemplateName = "LargeItem", Title = "头图", Subtitle = "大卡片" },
            new DemoMixedData { TemplateName = "SmallItem", Title = "正文 A", Subtitle = "小卡片" },
            new DemoMixedData { TemplateName = "SmallItem", Title = "正文 B", Subtitle = "小卡片" },
        };
    }
}
```

#### 示例 2：分组展开/收起
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class GroupHeaderRender : ItemRender<DemoGroupData, DemoItemHolder>
{
    protected override void OnBind(DemoGroupData data, int index)
    {
        Holder.title.text = data.Expanded ? $"▼ {data.Title}" : $"▶ {data.Title}";
        Holder.subtitle.text = $"Type = {data.Type}";
    }
}

public sealed class GroupItemRender : ItemRender<DemoGroupData, DemoItemHolder>
{
    protected override void OnBind(DemoGroupData data, int index)
    {
        Holder.title.text = data.Title;
        Holder.subtitle.text = $"Group {data.Type}";
    }
}

public sealed class GroupAdapterDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGGroupList<DemoGroupData> list;

    private void Start()
    {
        list = UGListCreateHelper.CreateGroup<DemoGroupData>(recyclerView, "GroupHeader");
        list.RegisterItemRender<GroupHeaderRender>("GroupHeader");
        list.RegisterItemRender<GroupItemRender>("GroupItem");

        list.Data = new List<DemoGroupData>
        {
            new DemoGroupData { TemplateName = "GroupItem", Type = 1, Title = "剑" },
            new DemoGroupData { TemplateName = "GroupItem", Type = 1, Title = "盾" },
            new DemoGroupData { TemplateName = "GroupItem", Type = 2, Title = "药水" },
        };
    }

    public void ToggleFirstGroup()
    {
        list.Adapter.Activate(0);                        // 组头位置会切换 Expanded
    }
}
```

#### 示例 3：循环适配器的虚拟索引
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class LoopAdapterDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGLoopList<DemoSimpleData> list;
    private int virtualIndex;

    private void Start()
    {
        list = UGListCreateHelper.CreateLoop<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "Banner A" },
            new DemoSimpleData { Title = "Banner B" },
            new DemoSimpleData { Title = "Banner C" },
        };

        virtualIndex = list.Adapter.GetRealCount() * 100; // 从中间起步，便于双向循环
        recyclerView.ScrollToWithAlignment(virtualIndex, ScrollAlignment.Center);
    }

    public void MoveNext()
    {
        virtualIndex += 1;                               // 维护虚拟索引，而不是只用真实索引
        recyclerView.ScrollToWithAlignment(virtualIndex, ScrollAlignment.Center, 0f, true, 0.2f);
    }
}
```

<a id="layout"></a>
## 布局（LayoutManager 系列）

布局器只负责“算位置”，不负责数据绑定。它决定内容尺寸、可见区间、索引到坐标的映射以及吸附基准。

<a id="layout-api"></a>
### API 说明

#### 类型：`LayoutManager`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/Layout/LayoutManager.cs`

**核心属性**

| 成员名 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `ViewportSize` | `Vector2` | 运行时计算 | 视口尺寸。 | 只有执行过 `SetContentSize()` 后才可靠。 |
| `ContentSize` | `Vector2` | 运行时计算 | 内容总尺寸。 | 滚动条与滚动范围都依赖此值。 |
| `ContentOffset` | `Vector2` | 运行时计算 | 内容对齐偏移。 | 与 `Alignment` 有关。 |
| `ViewportOffset` | `Vector2` | 运行时计算 | 视口偏移。 | 分页/居中场景常用。 |
| `Adapter` | `IAdapter` | `null` | 当前适配器。 | 由容器内部绑定流程注入。 |
| `ViewProvider` | `ViewProvider` | `null` | 当前视图提供器。 | 由容器内部绑定流程注入。 |
| `RecyclerView` | `RecyclerView` | `null` | 所属列表。 | 由容器内部绑定流程注入。 |
| `Direction` | `Direction` | `Direction.Vertical` | 主轴方向。 | 应与容器一致。 |
| `Alignment` | `Alignment` | `Alignment.Left` | 对齐方式。 | `Center` 会改变偏移计算。 |
| `Spacing` | `Vector2` | `Vector2.zero` | 间距。 | 按方向使用对应轴。 |
| `Padding` | `Vector2` | `Vector2.zero` | 内边距。 | 直接参与内容尺寸计算。 |
| `Unit` | `int` | `1` | 每次创建/回收的步进量。 | 网格通常等于一行或一列的元素数。 |
| `ScrollPosition` | `float` | 运行时读取 | 当前滚动位置。 | 只读，来自 `RecyclerView.GetScrollPosition()`。 |

**通用方法**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `SetContentSize()` | `void` | 无 | 计算视口、内容、偏移。 | 由容器内部布局流程调用。 |
| `UpdateLayout()` | `void` | 无 | 重新布局当前可见 Holder。 | 仅操作已创建视图。 |
| `Layout(ViewHolder viewHolder, int index)` | `void` | 无 | 将指定 Holder 摆放到目标位置。 | 默认按 `CalculatePosition()` 放置。 |
| `CalculateContentSize()` | `Vector2` | 无 | 计算内容总尺寸。 | 由具体布局实现。 |
| `CalculatePosition(int index)` | `Vector2` | 无 | 计算指定索引位置。 | 由具体布局实现。 |
| `CalculateContentOffset()` | `Vector2` | 无 | 计算内容偏移。 | 与对齐方式强相关。 |
| `CalculateViewportOffset()` | `Vector2` | 无 | 计算视口偏移。 | 分页与居中布局更明显。 |
| `GetStartIndex()` / `GetEndIndex()` | `int` | 无 | 当前滚动位置的可见区间。 | `end < start` 时表示当前无需创建项。 |
| `IndexToPosition(int index)` | `float` | 无 | 索引转滚动位置。 | 吸附与 `ScrollTo` 都依赖它。 |
| `PositionToIndex(float position)` | `int` | 无 | 滚动位置转最近索引。 | 吸附时用来找最近项。 |
| `DoItemAnimation()` | `void` | 无 | 执行布局相关动画。 | `PageLayoutManager`、`CircleLayoutManager` 会覆写。 |

#### 类型：布局派生类

| 类型 | 主要特性 | 默认值 | 使用限制 |
| --- | --- | --- | --- |
| `LinearLayoutManager` | 等尺寸线性布局。 | 无额外字段 | 适合单列/单行列表。 |
| `GridLayoutManager` | 网格布局。 | `cellCount = 1` | `cellCount` 通过 Inspector 配置。 |
| `PageLayoutManager` | 分页式线性布局，带缩放动画。 | `minScale = 0.9f` | 常与 `Snap` 联用。 |
| `CircleLayoutManager` | 圆环布局。 | `circleDirection = Positive` | `intervalAngle` 在运行时按项数重算。 |
| `MixedLayoutManager` | 支持不同模板尺寸的异构布局。 | 内部缓存为空 | 最适合多模板或变高度列表。 |

#### 参数：`IndexToPosition(int index)`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `index` | `int` | 无 | 目标布局索引。 |

- 返回值：`float`，滚动器目标位置。
- 使用限制：越界时通常被实现类收敛到合法范围，但业务层仍应传递有效索引。

<a id="layout-basic"></a>
### 线性与网格布局

#### 示例 1：线性列表
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class LinearLayoutDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LayoutManager = LinearLayoutManager

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "线性列表 1" },
            new DemoSimpleData { Title = "线性列表 2" },
            new DemoSimpleData { Title = "线性列表 3" },
        };
    }
}
```

#### 示例 2：网格背包
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class GridInventoryDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LayoutManager = GridLayoutManager, cellCount = 4

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();

        var items = new List<DemoSimpleData>();
        for (int i = 0; i < 20; i++)
        {
            items.Add(new DemoSimpleData { Title = $"格子 {i + 1}", Subtitle = $"Index={i}" });
        }

        list.Data = items;
    }
}
```

#### 示例 3：空网格的边界结果
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class EmptyGridDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private void Start()
    {
        var list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>();          // 空网格
    }
}
```

<a id="layout-advanced"></a>
### 分页、圆环与异构长度布局

#### 示例 1：分页卡片
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class PageLayoutDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LayoutManager = PageLayoutManager, Snap = true

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "Page 1" },
            new DemoSimpleData { Title = "Page 2" },
            new DemoSimpleData { Title = "Page 3" },
        };
    }
}
```

#### 示例 2：圆环菜单
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class CircleMenuDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LayoutManager = CircleLayoutManager, Scroller = CircleScroller

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "装备" },
            new DemoSimpleData { Title = "技能" },
            new DemoSimpleData { Title = "任务" },
            new DemoSimpleData { Title = "地图" },
        };
    }
}
```

#### 示例 3：异构长度列表
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class MixedLayoutDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LayoutManager = MixedLayoutManager

    private UGMixedList<DemoMixedData> list;

    private void Start()
    {
        list = UGListCreateHelper.CreateMixed<DemoMixedData>(recyclerView);
        list.RegisterItemRender<DemoMixedRender>("SmallItem");
        list.RegisterItemRender<DemoMixedRender>("LargeItem"); // 两个模板尺寸不同

        list.Data = new List<DemoMixedData>
        {
            new DemoMixedData { TemplateName = "LargeItem", Title = "长卡片" },
            new DemoMixedData { TemplateName = "SmallItem", Title = "短卡片 A" },
            new DemoMixedData { TemplateName = "SmallItem", Title = "短卡片 B" },
        };
    }
}
```

<a id="scroller"></a>
## 滚动器（Scroller / CircleScroller）

滚动器负责手势输入与位移变化；布局负责“每个位移意味着什么”。二者解耦后，滚动和显示方式可以灵活组合。

<a id="scroller-api"></a>
### API 说明

#### 类型：`Scroller`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/Scroller/Scroller.cs`

**属性**

| 成员名 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Position` | `float` | `0f` | 当前滚动位置。 | 直接赋值不会自动刷新 UI，通常由 `RecyclerView` 驱动。 |
| `Velocity` | `float` | 只读 | 当前速度。 | 仅用于诊断或自定义效果。 |
| `Direction` | `Direction` | `Direction.Vertical` | 滚动方向。 | 应与容器方向一致。 |
| `ContentSize` | `Vector2` | `Vector2.zero` | 内容尺寸。 | 由容器内部布局流程同步更新。 |
| `ViewSize` | `Vector2` | `Vector2.zero` | 视口尺寸。 | 由容器内部布局流程同步更新。 |
| `ScrollSpeed` | `float` | `1f` | `MoveTo` 速度。 | 外部通常通过 `RecyclerView.ScrollSpeed` 配置。 |
| `WheelSpeed` | `float` | `30f` | 滚轮速度。 | 过大容易导致过冲。 |
| `Snap` | `bool` | `false` | 是否启用吸附模式。 | 吸附由容器在停止时完成。 |
| `MaxPosition` | `float` | 只读 | 最大合法滚动位置。 | 由内容和视口尺寸计算。 |
| `ViewLength` | `float` | 只读 | 视口主轴长度。 | 用于边缘阻尼。 |
| `OnValueChanged` | `ScrollerEvent` | 新实例 | 位移变化事件。 | 高频事件。 |
| `OnMoveStoped` | `MoveStopEvent` | 新实例 | 惯性/动画停止事件。 | 拼写保留源码 `Stoped`。 |
| `OnDragging` | `DraggingEvent` | 新实例 | 拖拽开始/结束事件。 | 参数为是否正在拖拽。 |
| `dragStopTime` | `float` | `0f` | 最近一次拖拽时间戳。 | 通常仅供调试。 |

**方法**

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `ScrollTo(float position, bool smooth = false)` | `void` | `smooth=false` | 滚到目标位置。 | 不主动夹取范围，推荐经由 `RecyclerView` 调用。 |
| `ScrollToDuration(float position, float duration)` | `void` | 无 | 按固定时长滚动。 | `duration <= 0` 时立即到位。 |
| `ScrollToRatio(float ratio)` | `void` | 无 | 以归一化滚动条值滚动。 | 通常由滚动条驱动。 |
| `OnBeginDrag(...)` / `OnDrag(...)` / `OnEndDrag(...)` | `void` | 无 | 处理拖拽输入。 | 通常由 Unity 事件系统自动调用。 |
| `OnScroll(PointerEventData eventData)` | `void` | 无 | 处理鼠标滚轮。 | 横向列表读取 `scrollDelta.x`。 |

#### 类型：`CircleScroller`

| 方法/成员 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GetDelta(PointerEventData eventData)` | `float` | 无 | 根据环形中心计算拖拽方向。 | 仅适合圆环布局。 |
| `Elastic()` | `void` | 无 | 被覆写为空实现。 | 圆环一般不需要边界回弹。 |

#### 参数：`ScrollTo(float position, bool smooth = false)`

| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `position` | `float` | 无 | 目标滚动位置。 |
| `smooth` | `bool` | `false` | 是否使用平滑补间。 |

- 返回值：无。
- 使用限制：该方法不会主动把 `position` 夹到 `0 ~ MaxPosition`，需要上层自行保证。

<a id="scroller-programmatic"></a>
### 程序化滚动

#### 示例 1：立即滚动与平滑滚动
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class ProgrammaticScrollDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    public void JumpToTop()
    {
        recyclerView.ScrollTo(0, smooth: false);         // 立即跳到顶部
    }

    public void SmoothToMiddle()
    {
        recyclerView.ScrollToWithAlignment(15, ScrollAlignment.Center, 0f, true, 0.35f);
    }
}
```

#### 示例 2：按固定时长滚动
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class TimedScrollDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    public void ScrollByDuration()
    {
        if (recyclerView.Scroller == null)
        {
            return;
        }

        float target = Mathf.Min(recyclerView.Scroller.MaxPosition, 320f);
        recyclerView.Scroller.ScrollToDuration(target, 0.5f); // 0.5 秒到位
    }
}
```

#### 示例 3：无滚动能力时的防御式调用
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class ScrollGuardDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    public void TryScroll()
    {
        if (!recyclerView.Scroll || recyclerView.Scroller == null)
        {
            Debug.Log("Scroll disabled, ignore request."); // 避免空滚动器导致误判
            return;
        }

        recyclerView.ScrollToWithAlignment(2, ScrollAlignment.Start);
    }
}
```

<a id="scroller-advanced"></a>
### 惯性、吸附与自动播放

#### 示例 1：分页列表的吸附体验
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class SnapPageDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;  // Inspector: Snap = true, LayoutManager = PageLayoutManager

    private void Awake()
    {
        recyclerView.Scroll = true;                      // 启用滚动
        recyclerView.Snap = true;                        // 停止时自动吸附最近项
        recyclerView.ScrollSpeed = 10f;                  // 提高分页吸附速度
    }
}
```

#### 示例 2：自动播放轮播
```csharp
using System.Collections;
using AlicizaX.UI;
using UnityEngine;

public sealed class AutoPlayDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private int nextIndex;
    private Coroutine autoPlayCoroutine;

    private void OnEnable()
    {
        autoPlayCoroutine = StartCoroutine(AutoPlay());
    }

    private void OnDisable()
    {
        if (autoPlayCoroutine != null)
        {
            StopCoroutine(autoPlayCoroutine);            // 面板关闭时停止自动滚动
        }
    }

    private IEnumerator AutoPlay()
    {
        while (true)
        {
            yield return new WaitForSeconds(3f);
            recyclerView.ScrollToWithAlignment(nextIndex, ScrollAlignment.Center, 0f, true, 0.25f);
            nextIndex += 1;                              // 循环列表可持续递增
        }
    }
}
```

#### 示例 3：手动上一页 / 下一页
```csharp
using AlicizaX.UI;
using UnityEngine;
using UnityEngine.UI;

public sealed class PagerButtonsDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    [SerializeField] private Button prevButton;
    [SerializeField] private Button nextButton;
    private int currentIndex;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index => currentIndex = Mathf.Max(index, 0);

        prevButton.onClick.AddListener(() =>
        {
            recyclerView.ScrollToWithAlignment(Mathf.Max(currentIndex - 1, 0), ScrollAlignment.Center, 0f, true, 0.2f);
        });

        nextButton.onClick.AddListener(() =>
        {
            recyclerView.ScrollToWithAlignment(currentIndex + 1, ScrollAlignment.Center, 0f, true, 0.2f);
        });
    }
}
```

<a id="pool"></a>
## 视图池（ViewProvider / ObjectPool）

视图池是 `RecyclerView` 性能表现的核心：它让“大列表”只保留可见区对象，其他对象进入可复用池而不是销毁重建。

<a id="pool-api"></a>
### API 说明

#### 类型：`ViewProvider`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/ViewProvider/ViewProvider.cs`

| 方法/成员 | 返回值/类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Adapter` | `IAdapter` | `null` | 当前适配器。 | 由容器注入。 |
| `LayoutManager` | `LayoutManager` | `null` | 当前布局器。 | 由容器注入。 |
| `ViewHolders` | `IReadOnlyList<ViewHolder>` | 空集合 | 当前可见 Holder 集。 | 只读视图。 |
| `PoolStats` | `string` | 抽象成员 | 对象池统计。 | 用于诊断。 |
| `GetTemplate(string viewName)` | `ViewHolder` | 无 | 获取模板。 | 多模板时名字必须命中。 |
| `GetTemplates()` | `ViewHolder[]` | 无 | 获取所有模板。 | 模板不能为空。 |
| `Allocate(string viewName)` | `ViewHolder` | 无 | 从池中取出一个 Holder。 | 通常不手动调用。 |
| `Free(string viewName, ViewHolder viewHolder)` | `void` | 无 | 归还 Holder。 | 通常不手动调用。 |
| `Reset()` | `void` | 无 | 清空可见项并销毁池。 | 常用于彻底重建。 |
| `PreparePool()` | `void` | 无 | 依据可见区预热池。 | 由容器内部布局流程触发。 |
| `CreateViewHolder(int index)` | `void` | 无 | 创建一个 `Unit` 批次的 Holder。 | `index` 为布局起点。 |
| `RemoveViewHolder(int index)` | `void` | 无 | 回收一个 `Unit` 批次的 Holder。 | `index` 为布局起点。 |
| `GetViewHolder(int index)` | `ViewHolder` | 无 | 根据布局索引查找 Holder。 | 不可见时返回 `null`。 |
| `GetViewHolderByDataIndex(int dataIndex)` | `ViewHolder` | 无 | 根据数据索引查找 Holder。 | 循环列表可能存在多个映射。 |
| `TryGetViewHoldersByDataIndex(...)` | `bool` | 无 | 获取某数据索引对应的所有 Holder。 | 适合循环列表。 |
| `CalculateViewSize(int index)` | `Vector2` | 无 | 按模板估算尺寸。 | 依赖 `GetViewName(index)` 正确。 |

#### 类型：`SimpleViewProvider`

| 成员 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| 内部池 | `ObjectPool<ViewHolder>` | `initialSize = 0`, `maxSize = 1` | 单模板池。 | 实际容量会在 `PreparePool()` 中扩容。 |
| `PoolStats` | `string` | 实时统计 | 命中、未命中、销毁、活跃等信息。 | 文本格式仅用于日志。 |

#### 类型：`MixedViewProvider`

| 成员 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| 内部池 | `MixedObjectPool<ViewHolder>` | 每类型默认上限 `10` | 多模板池。 | 模板名必须唯一。 |
| `PoolStats` | `string` | 实时统计 | 当前命中、未命中、销毁信息。 | 细粒度活跃数需看 `MixedObjectPool`。 |

#### 类型：`ObjectPool<T>`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/ObjectPool/ObjectPool.cs`

| 方法/成员 | 返回值/类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `ObjectPool(IObjectFactory<T> factory)` | 构造函数 | `maxSize = Environment.ProcessorCount * 2` | 用 CPU 数量推导上限。 | 初始大小为 `0`。 |
| `ObjectPool(IObjectFactory<T> factory, int maxSize)` | 构造函数 | `initialSize = 0` | 指定最大池容量。 | `maxSize` 需大于等于 `0`。 |
| `ObjectPool(IObjectFactory<T> factory, int initialSize, int maxSize)` | 构造函数 | 无 | 指定预热数量与上限。 | `maxSize < initialSize` 会抛异常。 |
| `Allocate()` | `T` | 无 | 取对象。 | 空池时会创建新对象。 |
| `Free(T obj)` | `void` | 无 | 归还对象。 | 超过上限时会销毁。 |
| `EnsureCapacity(int value)` | `void` | 无 | 调大池上限。 | `value <= 0` 抛异常。 |
| `Warm(int count)` | `void` | 无 | 预热到目标数量。 | 实际不会超过 `maxSize`。 |
| `Dispose()` | `void` | 无 | 销毁所有空闲对象。 | 活跃对象不受影响。 |
| `MaxSize` | `int` | 构造决定 | 当前最大容量。 | 可被 `EnsureCapacity()` 提高。 |
| `ActiveCount` / `InactiveCount` | `int` | `0` | 活跃 / 闲置数量。 | 用于评估是否需要调容量。 |
| `HitCount` / `MissCount` / `DestroyCount` | `int` | `0` | 命中、未命中、销毁统计。 | 用于调优。 |
| `PeakActive` | `int` | `0` | 历史峰值活跃数。 | 可作为容量基线。 |

#### 类型：`MixedObjectPool<T>`

| 方法/成员 | 返回值/类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `MixedObjectPool(IMixedObjectFactory<T> factory)` | 构造函数 | `defaultMaxSizePerType = 10` | 使用默认每类型容量。 | `factory` 不能为空。 |
| `MixedObjectPool(IMixedObjectFactory<T> factory, int defaultMaxSizePerType)` | 构造函数 | 无 | 显式指定每类型默认容量。 | `defaultMaxSizePerType <= 0` 抛异常。 |
| `Allocate(string typeName)` | `T` | 无 | 取指定模板类型对象。 | `typeName` 必须存在。 |
| `Free(string typeName, T obj)` | `void` | 无 | 归还指定类型对象。 | 超出该类型上限时会销毁。 |
| `SetMaxSize(string typeName, int value)` | `void` | 无 | 设置单类型上限。 | 不会自动创建对象。 |
| `EnsureCapacity(string typeName, int value)` | `void` | 无 | 单类型扩容。 | `value <= 0` 抛异常。 |
| `Warm(string typeName, int count)` | `void` | 无 | 单类型预热。 | 实际不会超过该类型上限。 |
| `GetActiveCount(string typeName)` | `int` | `0` | 当前活跃数。 | 适合按模板调优。 |
| `GetPeakActiveCount(string typeName)` | `int` | `0` | 历史峰值活跃数。 | 可用于回写容量。 |

<a id="pool-basic"></a>
### 预热与复用

#### 示例 1：依赖内建 `PreparePool()` 自动预热
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class BuiltinPoolWarmDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private void Start()
    {
        var list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();

        var data = new List<DemoSimpleData>();
        for (int i = 0; i < 200; i++)
        {
            data.Add(new DemoSimpleData { Title = $"行 {i + 1}" });
        }

        list.Data = data;
        Debug.Log(recyclerView.PoolStats);               // 输出当前池统计
    }
}
```

#### 示例 2：直接使用 `ObjectPool<T>` 自定义容量
```csharp
using AlicizaX.UI;
using UnityEngine;
using UnityEngine.UI;

public sealed class DemoPoolHolder : ViewHolder
{
    public Text title;
}

public sealed class DemoPoolFactory : IObjectFactory<DemoPoolHolder>
{
    private readonly DemoPoolHolder template;
    private readonly Transform parent;

    public DemoPoolFactory(DemoPoolHolder template, Transform parent)
    {
        this.template = template;
        this.parent = parent;
    }

    public DemoPoolHolder Create()
    {
        return Object.Instantiate(template, parent);    // 池空时创建
    }

    public void Reset(DemoPoolHolder obj)
    {
        obj.gameObject.SetActive(false);                // 归还时隐藏
    }

    public bool Validate(DemoPoolHolder obj)
    {
        return obj != null;                             // 被销毁对象不再回池
    }

    public void Destroy(DemoPoolHolder obj)
    {
        Object.Destroy(obj.gameObject);                 // 超上限时销毁
    }
}

public sealed class ObjectPoolDemo : MonoBehaviour
{
    [SerializeField] private DemoPoolHolder template;
    [SerializeField] private Transform parent;

    private ObjectPool<DemoPoolHolder> pool;

    private void Awake()
    {
        pool = new ObjectPool<DemoPoolHolder>(new DemoPoolFactory(template, parent), initialSize: 8, maxSize: 32);
        pool.Warm(16);                                  // 预热到 16 个
        pool.EnsureCapacity(48);                        // 动态扩容到 48
    }

    private void Start()
    {
        DemoPoolHolder holder = pool.Allocate();
        holder.title.text = "From pool";
        pool.Free(holder);                              // 归还后进入闲置栈

        Debug.Log($"hit={pool.HitCount}, miss={pool.MissCount}, inactive={pool.InactiveCount}");
    }
}
```

#### 示例 3：校验失败时自动销毁
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class PoolValidateDemo : MonoBehaviour
{
    [SerializeField] private DemoPoolHolder template;
    [SerializeField] private Transform parent;

    private ObjectPool<DemoPoolHolder> pool;

    private void Start()
    {
        pool = new ObjectPool<DemoPoolHolder>(new DemoPoolFactory(template, parent), 1, 2);

        DemoPoolHolder holder = pool.Allocate();
        Destroy(holder.gameObject);                     // 模拟外部错误销毁
        pool.Free(holder);                              // Validate 失败后不会重新入池
    }
}
```

<a id="pool-mixed"></a>
### 多模板对象池配置

#### 示例 1：按模板类型分别预热
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using UnityEngine;

public sealed class MixedPoolDemo : MonoBehaviour
{
    [SerializeField] private DemoPoolHolder smallTemplate;
    [SerializeField] private DemoPoolHolder largeTemplate;
    [SerializeField] private Transform parent;

    private MixedObjectPool<DemoPoolHolder> pool;

    private void Awake()
    {
        var templates = new Dictionary<string, DemoPoolHolder>
        {
            ["SmallItem"] = smallTemplate,
            ["LargeItem"] = largeTemplate,
        };

        pool = new MixedObjectPool<DemoPoolHolder>(
            new UnityMixedComponentFactory<DemoPoolHolder>(templates, parent),
            defaultMaxSizePerType: 6);

        pool.EnsureCapacity("SmallItem", 24);           // 小卡片出现频率更高
        pool.EnsureCapacity("LargeItem", 8);            // 大卡片数量更少
        pool.Warm("SmallItem", 16);
        pool.Warm("LargeItem", 4);
    }
}
```

#### 示例 2：根据峰值活跃数回写容量
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class MixedPoolTuningDemo : MonoBehaviour
{
    public void PrintRecommendation(MixedObjectPool<DemoPoolHolder> pool)
    {
        int peak = pool.GetPeakActiveCount("SmallItem");
        int recommended = peak + 2;                     // 峰值 + buffer
        Debug.Log($"Recommended SmallItem capacity = {recommended}");
    }
}
```

<a id="navigation"></a>
## 导航（RecyclerNavigation）

导航模块负责把 `EventSystem` 的移动事件转成“列表内跳转 + 必要滚动 + 焦点恢复”。

<a id="navigation-api"></a>
### API 说明

#### 类型：`RecyclerNavigationController`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/Navigation/RecyclerNavigationController.cs`

| 方法/成员 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `RecyclerNavigationController(RecyclerView recyclerView)` | 构造函数 | 无 | 创建导航控制器。 | 一般由 `RecyclerView.NavigationController` 懒加载。 |
| `TryMove(ViewHolder currentHolder, MoveDirection direction, RecyclerNavigationOptions options)` | `bool` | 无 | 尝试从当前项移动到下一个项。 | `currentHolder` 不能为空，空列表返回 `false`。 |

#### 类型：`RecyclerNavigationBridge`

| 成员/方法 | 类型/返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `defaultEntryDirection` | `MoveDirection` | `MoveDirection.Down` | 列表首次接收焦点时的进入方向。 | Inspector 配置。 |
| `OnSelect(...)` | `void` | 无 | 当桥节点被选中时尝试进入列表。 | 挂在 `RecyclerView` 同节点上。 |
| `OnMove(...)` | `void` | 无 | 当桥节点收到方向键时尝试进入列表。 | 失败后才回落到原 `Selectable` 行为。 |
| `OnSubmit(...)` | `void` | 无 | 提交键进入列表。 | 常用于确认键。 |

#### 类型：`RecyclerNavigationOptions`

| 成员 | 类型 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Wrap` | `bool` | 构造决定 | 是否允许首尾环绕。 | 对非循环列表通常应关闭。 |
| `SmoothScroll` | `bool` | 构造决定 | 导航时是否平滑滚动。 | 开启后焦点会等待滚动完成。 |
| `Alignment` | `ScrollAlignment` | 构造决定 | 导航触发滚动时的对齐方式。 | 常用 `Center`。 |
| `Clamped` | `RecyclerNavigationOptions` | `wrap=false, smooth=false, alignment=Center` | 不环绕方案。 | 静态只读。 |
| `Circular` | `RecyclerNavigationOptions` | `wrap=true, smooth=false, alignment=Center` | 允许环绕方案。 | 静态只读。 |

#### 类型：`ItemInteractionProxy` / `RecyclerItemSelectable`

| 成员/方法 | 类型/返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `GetSelectable()` | `Selectable` | 无 | 返回真正参与导航的焦点锚点。 | 若节点上没有 `Selectable` 会自动补 `RecyclerItemSelectable`。 |
| `Bind(IItemInteractionHost)` | `void` | 无 | 绑定交互宿主。 | 由 `ItemRender` 内部驱动。 |
| `Clear()` | `void` | 无 | 清理交互宿主与状态。 | 回收时自动调用。 |

<a id="navigation-inner"></a>
### 列表内导航

#### 示例 1：ItemRender 启用点击、移动与提交
```csharp
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;
using UnityEngine.EventSystems;

public sealed class NavigableItemRender : ItemRender<DemoSimpleData, DemoItemHolder>
{
    public override ItemInteractionFlags InteractionFlags =>
        ItemInteractionFlags.PointerClick |
        ItemInteractionFlags.Select |
        ItemInteractionFlags.Move |
        ItemInteractionFlags.Submit;

    protected override void OnBind(DemoSimpleData data, int index)
    {
        Holder.title.text = data.Title;
        Holder.subtitle.text = $"可导航项 {index}";
    }

    protected override void OnPointerClick(PointerEventData eventData)
    {
        Debug.Log($"Clicked {CurrentIndex}");            // 点击时选择当前项
    }

    protected override void OnSubmit(BaseEventData eventData)
    {
        Debug.Log($"Submit {CurrentIndex}");             // 回车 / A 键确认
    }
}
```

#### 示例 2：主动驱动导航器移动
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class ManualNavigationDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    private int currentIndex;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index => currentIndex = Mathf.Max(index, 0);
    }

    private void Update()
    {
        if (!Input.GetKeyDown(KeyCode.RightArrow))
        {
            return;
        }

        var current = EventSystem.current?.currentSelectedGameObject?.GetComponentInParent<ViewHolder>();
        if (current == null)
        {
            recyclerView.TryFocusIndex(currentIndex, false, ScrollAlignment.Center);
            return;
        }

        recyclerView.NavigationController.TryMove(current, MoveDirection.Right, RecyclerNavigationOptions.Clamped);
    }
}
```

#### 示例 3：环绕导航与钳制导航
```csharp
using AlicizaX.UI;
using RecyclerViewBookSamples;

public sealed class CircularNavigableRender : ItemRender<DemoSimpleData, DemoItemHolder>
{
    public override ItemInteractionFlags InteractionFlags =>
        ItemInteractionFlags.Select | ItemInteractionFlags.Move;

    protected override RecyclerNavigationOptions NavigationOptions =>
        RecyclerNavigationOptions.Circular;              // 到尾部后回到头部

    protected override void OnBind(DemoSimpleData data, int index)
    {
        Holder.title.text = data.Title;
    }
}
```

<a id="navigation-entry"></a>
### 列表入口与焦点恢复

#### 示例 1：外部按钮把焦点送入列表
```csharp
using AlicizaX.UI;
using UnityEngine;
using UnityEngine.EventSystems;
using UnityEngine.UI;

public sealed class EntryBridgeDemo : MonoBehaviour
{
    [SerializeField] private Button entryButton;
    [SerializeField] private RecyclerView recyclerView;

    private void Awake()
    {
        entryButton.onClick.AddListener(() =>
        {
            EventSystem.current.SetSelectedGameObject(recyclerView.gameObject); // 选中桥节点
            recyclerView.TryFocusEntry(MoveDirection.Down);                     // 然后进入列表
        });
    }
}
```

#### 示例 2：重新打开面板时恢复上次项
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class NavigationRestoreDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private int lastIndex;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index => lastIndex = index; // 记录上次选中索引
    }

    private void OnEnable()
    {
        recyclerView.TryFocusIndex(lastIndex, smooth: true);       // 平滑恢复焦点
    }
}
```

#### 示例 3：空列表时避免错误进入
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class EmptyNavigationGuardDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    public void TryEnter()
    {
        if (!recyclerView.TryFocusEntry(MoveDirection.Down))
        {
            Debug.Log("List is empty or not ready.");              // 空列表不强行进入
        }
    }
}
```

<a id="uglist"></a>
## 业务包装层（UGList / UGListExtensions）

`UGList` 家族是官方提供的“业务友好包装层”，适合绝大多数游戏页面。它把适配器创建、内部绑定流程和常见滚动操作做了简化。

<a id="uglist-api"></a>
### API 说明

#### 类型：`UGListBase<TData, TAdapter>`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/UGList.cs`

| 成员/方法 | 类型/返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `RecyclerView` | `RecyclerView` | 构造注入 | 关联容器。 | 只读。 |
| `Adapter` | `TAdapter` | 构造注入 | 关联适配器。 | 只读。 |
| `Data` | `List<TData>` | `null` | 当前数据集合。 | 赋值时会调用 `_adapter.SetList()`。 |
| `RegisterItemRender<TItemRender>(string viewName = "")` | `void` | `viewName=""` | 注册渲染器。 | 空字符串表示默认模板。 |
| `RegisterItemRender(Type itemRenderType, string viewName = "")` | `void` | `viewName=""` | 运行时注册渲染器。 | 类型需继承 `ItemRenderBase`。 |
| `UnregisterItemRender(string viewName = "")` | `bool` | `viewName=""` | 注销渲染器。 | 成功返回 `true`。 |
| `ClearItemRenderRegistrations()` | `void` | 无 | 清空注册。 | 适合切换整套模板。 |

#### 类型：具体包装类

| 类型 | 适配器类型 | 说明 | 使用限制 |
| --- | --- | --- | --- |
| `UGList<TData>` | `Adapter<TData>` | 单模板普通列表。 | `TData : ISimpleViewData` |
| `UGGroupList<TData>` | `GroupAdapter<TData>` | 分组列表。 | `TData : class, IGroupViewData, new()` |
| `UGLoopList<TData>` | `LoopAdapter<TData>` | 循环列表。 | `TData : ISimpleViewData, new()` |
| `UGMixedList<TData>` | `MixedAdapter<TData>` | 多模板列表。 | `TData : IMixedViewData` |

#### 类型：`UGListCreateHelper`

| 方法 | 返回值 | 默认参数 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `Create<TData>(RecyclerView recyclerView)` | `UGList<TData>` | 无 | 创建普通列表包装。 | `TData : ISimpleViewData` |
| `CreateGroup<TData>(RecyclerView recyclerView, string groupViewName)` | `UGGroupList<TData>` | 无 | 创建分组列表包装。 | 必须提供组头模板名。 |
| `CreateLoop<TData>(RecyclerView recyclerView)` | `UGLoopList<TData>` | 无 | 创建循环列表包装。 | `TData : ISimpleViewData, new()` |
| `CreateMixed<TData>(RecyclerView recyclerView)` | `UGMixedList<TData>` | 无 | 创建多模板列表包装。 | `TData : IMixedViewData` |

#### 类型：`UGListExtensions`

源码位置：`Packages/com.alicizax.unity.ui.extension/Runtime/RecyclerView/UGListExtensions.cs`

| 成员/方法 | 返回值 | 默认值 | 说明 | 使用限制 |
| --- | --- | --- | --- | --- |
| `DebugScrollTo` | `bool` | `false` | 输出滚动定位日志。 | 仅用于调试。 |
| `ScrollTo(...)` | `void` | `alignment=Start, offset=0f, smooth=false, duration=0.3f` | 包装 `RecyclerView.ScrollToWithAlignment()`。 | `ugList.RecyclerView` 为空时打印警告。 |
| `ScrollToStart(...)` | `void` | `offset=0f, smooth=false, duration=0.3f` | 滚到起始端。 | 同上。 |
| `ScrollToCenter(...)` | `void` | `offset=0f, smooth=false, duration=0.3f` | 滚到中间。 | 同上。 |
| `ScrollToEnd(...)` | `void` | `offset=0f, smooth=false, duration=0.3f` | 滚到末端。 | 同上。 |

<a id="uglist-basic"></a>
### 快速创建与滚动扩展

#### 示例 1：`UGList` 最简创建
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class QuickUgListDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "快速创建 1" },
            new DemoSimpleData { Title = "快速创建 2" },
        };
    }
}
```

#### 示例 2：使用扩展方法滚动
```csharp
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class UgListExtensionsDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
    }

    public void CenterItem(int index)
    {
        list.ScrollToCenter(index, offset: 0f, smooth: true, duration: 0.2f); // 使用扩展方法
    }
}
```

#### 示例 3：打开滚动定位调试日志
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class UgListDebugDemo : MonoBehaviour
{
    private void Awake()
    {
        UGListExtensions.DebugScrollTo = true;          // 打开定位日志
    }
}
```

<a id="uglist-advanced"></a>
### 业务封装示例

#### 示例 1：业务侧封装统一入口
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class MailListFacade
{
    private readonly UGList<DemoSimpleData> list;

    public MailListFacade(RecyclerView recyclerView)
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
    }

    public void SetMails(List<DemoSimpleData> mails)
    {
        list.Data = mails;                              // 统一数据入口
    }

    public void FocusFirstUnread()
    {
        list.RecyclerView.TryFocusIndex(0, true, ScrollAlignment.Center);
    }
}
```

#### 示例 2：封装“刷新 + 保留焦点”
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;

public sealed class FocusAwareFacade
{
    private readonly UGList<DemoSimpleData> list;
    private int lastIndex;

    public FocusAwareFacade(RecyclerView recyclerView)
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        recyclerView.OnIndexChanged += index => lastIndex = index;
    }

    public void Replace(List<DemoSimpleData> data)
    {
        list.Data = data;
        list.RecyclerView.TryFocusIndex(lastIndex, false); // 数据刷新后恢复焦点
    }
}
```

<a id="scenarios"></a>
## 场景专题

本节给出更贴近业务的完整场景脚本，重点覆盖性能与交互要求较高的页面。

<a id="scenario-massive"></a>
### 大量列表项复用（含对象池配置）

#### 示例 1：一万条数据的大列表
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class MassiveListDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: LinearLayoutManager + Scroller

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();

        var rows = new List<DemoSimpleData>(10000);
        for (int i = 0; i < 10000; i++)
        {
            rows.Add(new DemoSimpleData
            {
                Title = $"战利品 {i + 1}",
                Subtitle = $"ID = {100000 + i}",
            });
        }

        list.Data = rows;
        Debug.Log(recyclerView.PoolStats);               // 观察命中、未命中和活跃数
    }
}
```

#### 示例 2：手工调对象池容量
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class MassiveListPoolConfigDemo : MonoBehaviour
{
    [SerializeField] private DemoPoolHolder rowTemplate;
    [SerializeField] private Transform poolRoot;

    private ObjectPool<DemoPoolHolder> pool;

    private void Awake()
    {
        pool = new ObjectPool<DemoPoolHolder>(
            new DemoPoolFactory(rowTemplate, poolRoot),
            initialSize: 24,
            maxSize: 96);                               // 明确给出大列表池容量

        pool.Warm(48);                                  // 提前创建一部分
    }

    private void Start()
    {
        Debug.Log($"active={pool.ActiveCount}, inactive={pool.InactiveCount}, peak={pool.PeakActive}");
    }
}
```

> 💡 大列表调优的首要目标不是“把所有项都放进池里”，而是让“可见项 + 一屏缓冲”命中率足够高。

<a id="scenario-mixed"></a>
### 多模板混排

#### 示例 1：信息流混排
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class FeedCardHolder : ViewHolder
{
    public UnityEngine.UI.Text title;
}

public sealed class FeedCardRender : ItemRender<DemoMixedData, FeedCardHolder>
{
    protected override void OnBind(DemoMixedData data, int index)
    {
        Holder.title.text = $"[Card] {data.Title}";
    }
}

public sealed class MixedFeedDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: MixedLayoutManager + 2 templates

    private UGMixedList<DemoMixedData> list;

    private void Start()
    {
        list = UGListCreateHelper.CreateMixed<DemoMixedData>(recyclerView);
        list.RegisterItemRender<DemoMixedRender>("FeedText");
        list.RegisterItemRender<FeedCardRender>("FeedCard");

        list.Data = new List<DemoMixedData>
        {
            new DemoMixedData { TemplateName = "FeedCard", Title = "头图 Banner" },
            new DemoMixedData { TemplateName = "FeedText", Title = "正文 1", Subtitle = "文本块" },
            new DemoMixedData { TemplateName = "FeedText", Title = "正文 2", Subtitle = "文本块" },
            new DemoMixedData { TemplateName = "FeedCard", Title = "推荐卡片" },
        };
    }
}
```

#### 示例 2：未知模板名的保护策略
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class MixedTemplateGuardDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    public void BindSafely(List<DemoMixedData> rows)
    {
        foreach (DemoMixedData row in rows)
        {
            if (string.IsNullOrEmpty(row.TemplateName))
            {
                row.TemplateName = "FeedText";          // 回退到一个可用模板
            }
        }

        var list = UGListCreateHelper.CreateMixed<DemoMixedData>(recyclerView);
        list.RegisterItemRender<DemoMixedRender>("FeedText");
        list.Data = rows;
    }
}
```

> ⚠️ `MixedViewProvider.GetTemplate()` 找不到模板名时会抛 `KeyNotFoundException`；不要把兜底逻辑留给运行时异常。

<a id="scenario-paging"></a>
### 分页加载（加载态、空态、错误态）

#### 示例 1：统一状态流
```csharp
using System;
using System.Collections;
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public abstract class PagedEntryData : IMixedViewData
{
    public string TemplateName { get; set; }
}

public sealed class PagedContentData : PagedEntryData
{
    public string Title;
}

public sealed class PagedStateData : PagedEntryData
{
    public string Message;
    public Action Retry;
}

public sealed class PagedContentRender : ItemRender<PagedContentData, DemoItemHolder>
{
    protected override void OnBind(PagedContentData data, int index)
    {
        Holder.title.text = data.Title;
        Holder.subtitle.text = $"Item {index}";
    }
}

public sealed class PagedStateRender : ItemRender<PagedStateData, DemoStateHolder>
{
    private Action retry;

    protected override void OnHolderAttached()
    {
        base.OnHolderAttached();
        Holder.retryButton.onClick.AddListener(OnRetryClicked);   // 只注册一次
    }

    protected override void OnHolderDetached()
    {
        Holder.retryButton.onClick.RemoveListener(OnRetryClicked);
        base.OnHolderDetached();
    }

    protected override void OnBind(PagedStateData data, int index)
    {
        retry = data.Retry;
        Holder.message.text = data.Message;
        Holder.retryButton.gameObject.SetActive(data.Retry != null); // 错误态显示重试按钮
    }

    protected override void OnClear()
    {
        retry = null;                                    // 回收时清掉业务引用
    }

    private void OnRetryClicked()
    {
        retry?.Invoke();
    }
}

public sealed class PagedLoadingDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;  // Inspector: 需有 ContentItem / LoadingItem / EmptyItem / ErrorItem 模板

    private UGMixedList<PagedEntryData> list;
    private int page = 1;

    private void Start()
    {
        list = UGListCreateHelper.CreateMixed<PagedEntryData>(recyclerView);
        list.RegisterItemRender<PagedContentRender>("ContentItem");
        list.RegisterItemRender<PagedStateRender>("LoadingItem");
        list.RegisterItemRender<PagedStateRender>("EmptyItem");
        list.RegisterItemRender<PagedStateRender>("ErrorItem");
        StartCoroutine(LoadPage());
    }

    private IEnumerator LoadPage()
    {
        ShowLoading();
        yield return new WaitForSeconds(0.5f);           // 模拟网络

        if (page == 1)
        {
            ShowContent(new List<PagedEntryData>
            {
                new PagedContentData { TemplateName = "ContentItem", Title = "第一页-1" },
                new PagedContentData { TemplateName = "ContentItem", Title = "第一页-2" },
            });
            page++;
            yield break;
        }

        ShowEmpty();                                     // 第二次请求模拟空态
    }

    private void ShowLoading()
    {
        list.Data = new List<PagedEntryData>
        {
            new PagedStateData { TemplateName = "LoadingItem", Message = "正在加载..." },
        };
    }

    private void ShowContent(List<PagedEntryData> rows)
    {
        list.Data = rows;
    }

    private void ShowEmpty()
    {
        list.Data = new List<PagedEntryData>
        {
            new PagedStateData { TemplateName = "EmptyItem", Message = "暂无数据" },
        };
    }

    public void ShowError()
    {
        list.Data = new List<PagedEntryData>
        {
            new PagedStateData
            {
                TemplateName = "ErrorItem",
                Message = "加载失败，点击重试",
                Retry = () => StartCoroutine(LoadPage()), // 错误态回调
            },
        };
    }
}
```

#### 示例 2：滚动到底部加载下一页
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class PagedLoadMoreDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private bool isLoading;

    private void Awake()
    {
        recyclerView.OnScrollValueChanged += TryLoadMore; // 监听滚动变化
    }

    private void TryLoadMore()
    {
        if (isLoading || recyclerView.Scroller == null)
        {
            return;
        }

        float remain = recyclerView.Scroller.MaxPosition - recyclerView.GetScrollPosition();
        if (remain > 120f)
        {
            return;                                     // 距离底部还远，不加载
        }

        isLoading = true;
        Debug.Log("Reach bottom, load next page.");
    }
}
```

<a id="scenario-carousel"></a>
### 轮播与循环滚动（自动播放、手动切换）

#### 示例 1：循环 Banner
```csharp
using System.Collections;
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;
using UnityEngine.UI;

public sealed class BannerCarouselDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView; // Inspector: PageLayoutManager + Snap = true
    [SerializeField] private Button prevButton;
    [SerializeField] private Button nextButton;

    private UGLoopList<DemoSimpleData> list;
    private int virtualIndex;
    private Coroutine autoPlay;

    private void Start()
    {
        list = UGListCreateHelper.CreateLoop<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<DemoSimpleRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "Banner A" },
            new DemoSimpleData { Title = "Banner B" },
            new DemoSimpleData { Title = "Banner C" },
        };

        virtualIndex = list.Adapter.GetRealCount() * 100; // 从中间起始，保证可双向滚
        recyclerView.ScrollToWithAlignment(virtualIndex, ScrollAlignment.Center);

        prevButton.onClick.AddListener(() => Move(-1));   // 手动上一张
        nextButton.onClick.AddListener(() => Move(1));    // 手动下一张
        autoPlay = StartCoroutine(AutoPlay());
    }

    private void OnDisable()
    {
        if (autoPlay != null)
        {
            StopCoroutine(autoPlay);
        }
    }

    private IEnumerator AutoPlay()
    {
        while (true)
        {
            yield return new WaitForSeconds(3f);
            Move(1);                                      // 自动播放
        }
    }

    private void Move(int step)
    {
        virtualIndex += step;
        recyclerView.ScrollToWithAlignment(virtualIndex, ScrollAlignment.Center, 0f, true, 0.25f);
    }
}
```

#### 示例 2：非循环分页的边界保护
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class FiniteCarouselDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    [SerializeField] private int itemCount = 5;
    private int currentIndex;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index => currentIndex = Mathf.Max(index, 0);
    }

    public void Next()
    {
        int target = Mathf.Min(currentIndex + 1, itemCount - 1);
        recyclerView.ScrollToWithAlignment(target, ScrollAlignment.Center, 0f, true, 0.2f);
    }

    public void Prev()
    {
        int target = Mathf.Max(currentIndex - 1, 0);
        recyclerView.ScrollToWithAlignment(target, ScrollAlignment.Center, 0f, true, 0.2f);
    }
}
```

<a id="scenario-nav-scroll"></a>
### 手柄/键盘导航结合列表滚动

#### 示例 1：打开面板自动聚焦第一项
```csharp
using System.Collections.Generic;
using AlicizaX.UI;
using RecyclerViewBookSamples;
using UnityEngine;

public sealed class GamepadListDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;

    private UGList<DemoSimpleData> list;

    private void Start()
    {
        list = UGListCreateHelper.Create<DemoSimpleData>(recyclerView);
        list.RegisterItemRender<NavigableItemRender>();
        list.Data = new List<DemoSimpleData>
        {
            new DemoSimpleData { Title = "图像" },
            new DemoSimpleData { Title = "声音" },
            new DemoSimpleData { Title = "操作" },
        };
        recyclerView.TryFocusIndex(0, false, ScrollAlignment.Start); // 初次进入聚焦第一项
    }
}
```

#### 示例 2：导航时自动把目标项滚进可见区
```csharp
using AlicizaX.UI;
using UnityEngine;

public sealed class NavigationScrollSyncDemo : MonoBehaviour
{
    [SerializeField] private RecyclerView recyclerView;
    private int currentIndex;

    private void Awake()
    {
        recyclerView.OnIndexChanged += index => currentIndex = Mathf.Max(index, 0);
    }

    private void Update()
    {
        if (Input.GetKeyDown(KeyCode.DownArrow))
        {
            recyclerView.TryFocusIndex(currentIndex + 1, smooth: true, alignment: ScrollAlignment.End);
        }

        if (Input.GetKeyDown(KeyCode.UpArrow))
        {
            recyclerView.TryFocusIndex(currentIndex - 1, smooth: true, alignment: ScrollAlignment.Start);
        }
    }
}
```

> 📌 `TryFocusIndex(..., smooth: true)` 的意义不只是“滚动”，还包括“滚动结束后恢复焦点”。

<a id="faq"></a>
## FAQ

### 常见问题

#### Q1：为什么我已经赋值了数据，但列表里什么都没有？

- 最常见原因是没有通过 `UGList.Data`、`Adapter.SetList()` 或 `Notify*()` 等正式入口触发列表更新。
- 其次是 `Templates` 为空、`LayoutManager` 未配置或模板名与 `TemplateName` 不匹配。
- 如果是多模板列表，还要确认已经为每个模板注册了 `ItemRender`。

#### Q2：为什么 `NotifyItemChanged()` 后界面没变？

- 只会重绑“当前可见”的 Holder；不可见项会等滚动到可见区后再更新。
- 如果该项高度发生变化，需要用 `NotifyItemChanged(index, true)`。

#### Q3：为什么循环列表里业务索引和 `Holder.Index` 不一样？

- `OnIndexChanged` 回调参数与 `Adapter.ChoiceIndex` 代表的是业务层关注的“真实索引”。
- `Holder.Index` 是布局层的“虚拟索引”。
- `LoopAdapter` 绑定时会对虚拟索引取模。

#### Q4：为什么混排列表报模板找不到？

- `MixedAdapter.GetViewName()` 直接返回 `TemplateName`。
- `MixedViewProvider` 用模板对象的 `name` 做键。
- 任何大小写、空格或重命名不一致都会导致失败。

#### Q5：为什么滚动条不显示？

- `showScrollBar` 或 `Scroll` 可能未打开。
- `ShowScrollBarOnlyWhenScrollable = true` 时，内容未超过视口就不会显示。
- `Direction.Custom` 不支持当前实现的溢出检测。

#### Q6：为什么分页吸附不准确？

- `PageLayoutManager` 最适合固定尺寸页面。
- 项尺寸变化大时应换 `MixedLayoutManager`，并自己定义滚动定位策略。

#### Q7：为什么切换页面后焦点丢了？

- 视图复用会销毁/回收之前的 `Selectable`。
- 应该在 `OnEnable()` 或刷新完成后调用 `TryFocusIndex()`。

#### Q8：为什么对象池命中率低？

- 预热量不足。
- 列表每次都被 `Reset()`。
- 使用了全量刷新替代差量刷新。

<a id="anti-patterns"></a>
## Anti-patterns

### 常见反模式与替代方案

| 反模式 | 问题 | 正确做法 |
| --- | --- | --- |
| 每次数据变化都调用 `NotifyDataChanged()` | 频繁清空并重建可见项，浪费池命中率。 | 优先使用 `NotifyItemChanged()` / `NotifyItemRangeChanged()`。 |
| 多模板列表里把 `TemplateName` 写成业务文案 | 模板名一旦翻译或重命名就失效。 | 用固定常量，如 `const string FeedCard = "FeedCard";`。 |
| 在 `OnBind()` 里重复注册按钮事件 | Holder 被复用后会出现重复回调。 | 在 `OnHolderAttached()` 注册，在 `OnHolderDetached()` 解绑。 |
| 直接改 `Scroller.Position` 期待界面自动更新 | 位置变了但布局未刷新。 | 优先调用 `RecyclerView.ScrollTo*()`。 |
| 列表数据尚未通过正式入口完成更新就调用 `TryFocusIndex()` | 焦点目标尚未生成。 | 先写入 `Data` / `SetList()` / `Notify*()`，必要时延后到下一帧或 `OnEnable()`。 |
| 使用 `LoopAdapter` 却仍以真实索引做“下一页” | 会反复跳回前几项。 | 维护独立的虚拟索引。 |
| 每次打开页面都重新 new 包装层与数据容器 | 造成 GC 抖动和池统计失真。 | 页面级持有 `UGList` / `Adapter`，只替换数据。 |
| 把“加载中/空态/错误态”放在列表外部多套 UI | 逻辑分裂、切换难维护。 | 用 `MixedAdapter` 把状态也当作一种 Item。 |

<a id="performance"></a>
## 性能优化建议

### 建议清单

- 视图池预热：首屏数据尽量一次性设置到位，内部布局流程会自动触发 `PreparePool()` 准备“可见项 + 缓冲项”。
- 优先差量刷新：文本、数值、开关状态变化优先用 `NotifyItemChanged()` / `NotifyItemRangeChanged()`。
- 避免全量刷新：`NotifyDataChanged()` 只用于排序、模板切换、尺寸大量变化等无法局部更新的情况。
- 复用业务包装层：面板级缓存 `UGList` / `Adapter`，不要每次打开都重建。
- 控制模板数量：多模板会降低池命中率；能合并的样式尽量合并。
- 固定 Item 尺寸优先：能用 `LinearLayoutManager` / `GridLayoutManager` 时不要上来就用 `MixedLayoutManager`。
- 减少 `OnBind()` 重活：不要在 `OnBind()` 里做同步大图加载、复杂字符串拼接或深层级查找。
- 缓存引用：`Holder` 上的 `Text`、`Image`、`Button` 在模板初始化时就拖好，避免运行时 `GetComponent()`。
- 记录峰值活跃数：观察 `PoolStats`、`PeakActive`、`GetPeakActiveCount()`，按峰值 + buffer 设置池容量。
- 滚动事件节流：`OnScrollValueChanged` 是高频回调，尽量只做阈值判断，不做昂贵计算。
- 大量分页时保留数据容器：分页追加优先 `AddRange()`，避免整页复制新 `List<T>`。
- 减少 `Reset()`：`SetList()` 会触发 `RecyclerView.Reset()`；如果只是局部追加，直接对适配器做增量操作更稳。

> 💡 一个常见经验值：池容量先按“单屏可见数 + 1 屏缓冲”估，再通过 `PeakActive` 微调，而不是拍脑袋设置超大容量。

> ⚠️ 如果列表项高度经常变化，却还持续使用 `NotifyItemChanged(index, false)`，最终会出现错位、重叠或滚动条比例异常。

<a id="checklist"></a>
## 交付前检查清单

- `Templates` 已配置，且多模板名称与 `TemplateName` 完全一致。
- `LayoutManager` 与 `Scroller` 已在 Inspector 上正确绑定。
- 已为所有模板注册对应 `ItemRender`。
- 数据赋值后已通过 `Data` / `SetList()` / `Notify*()` 触发内部布局与刷新流程。
- 差量更新优先使用 `NotifyItemChanged()` / `NotifyItemRangeChanged()`。
- 焦点型页面已验证 `TryFocusIndex()`、`TryFocusEntry()` 与关闭/重开流程。
- 大列表页面已检查 `PoolStats` / `PeakActive` / `GetPeakActiveCount()`。
- 加载态、空态、错误态已验证，且不会因模板缺失报错。
- 循环列表已使用虚拟索引，不直接拿真实索引做连续滚动。
- `OnBind()` 中没有重复注册事件，也没有未释放的临时引用。