游戏引擎 / 系统课时

UI Toolkit 列表虚拟化

UI Toolkit 列表虚拟化

当任务面板或排行榜包含上万条记录时,逐条创建 UI 元素会增加首屏构建、布局和滚动成本。本课使用 Unity 6 的 ListView 实现长列表虚拟化,并通过实际运行和计数验证元素复用效果。

学习目标

  • 理解 ListView 如何通过可见区域裁剪与元素复用减少 UI 元素数量。
  • 使用 makeItem、bindItem 和固定行高创建可运行的万条数据列表。
  • 根据行高、数据更新方式和 Profiler 结果检查虚拟化效果。

虚拟化如何减少 UI 工作量

普通 ScrollView 如果一次添加 10000 个 Label,视觉树就需要管理这些元素,即使绝大部分位于屏幕外,也会增加初始化、内存和潜在的布局工作量。

ListView 则保留完整数据源,但只创建显示当前视口及缓冲区域所需的少量视觉元素。滚动时,离开视口的元素可以重新绑定到新的数据索引,而不必为每条数据永久保留独立元素。

例如列表包含 10000 条记录,视口高度为 480 像素,每行高度为 48 像素,那么同一时刻大约能显示 10 行。实际创建的元素数量还包含 Unity 管理的缓冲元素,不应直接认定为恰好 10 个。

ListView 数据源、可见视口与复用元素池的关系

虚拟化减少的是视觉元素及相关 UI 工作量,并不会自动减少 itemsSource 中的数据数量,也不会自动实现网络分页。对于包含图片的列表,图片资源的加载和释放仍需要单独管理。

创建可运行的万条数据列表

以下示例适用于 Unity 6(6000.0 及后续版本)的运行时 UI Toolkit。使用纯 C# 创建列表,无须制作列表行 UXML 模板。

首先配置场景:

  1. 在 Unity 编辑器中打开场景,选择 GameObject > UI Toolkit > UI Document,创建运行时 UI 对象。
  2. 检查该对象的 UIDocument 组件,确保 Panel Settings 已引用有效的面板设置资产。如果没有,可通过 Assets > Create > UI Toolkit > Panel Settings Asset 创建后赋值。
  3. 本示例通过代码创建所有 UI,Source Asset 可以留空。
  4. 在 Assets 下新建脚本 VirtualizedListDemo.cs,将其挂到刚创建的 UI 对象上。

完整脚本如下:

csharp
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public sealed class VirtualizedListDemo : MonoBehaviour
{
    private readonly List<string> rows = new List<string>(10000);
    private int createdCount;
    private int bindCount;

    private void Start()
    {
        for (int i = 0; i < 10000; i++)
            rows.Add($"任务 {i + 1:D5}");

        var listView = new ListView
        {
            itemsSource = rows,
            virtualizationMethod = CollectionVirtualizationMethod.FixedHeight,
            fixedItemHeight = 48,
            selectionType = SelectionType.None
        };

        // 只在需要新视觉元素时创建,不为每条数据创建一行。
        listView.makeItem = () =>
        {
            createdCount++;
            return new Label();
        };

        // 滚动时复用旧元素,并把文本更新为新数据。
        listView.bindItem = (element, index) =>
        {
            ((Label)element).text = rows[index];
            bindCount++;
        };

        listView.unbindItem = (element, index) =>
        {
            ((Label)element).text = string.Empty;
        };

        listView.style.width = 420;
        listView.style.height = 480;

        var root = GetComponent<UIDocument>().rootVisualElement;
        var button = new Button(() =>
            Debug.Log($"created={createdCount}, bound={bindCount}"))
        {
            text = "打印复用统计"
        };

        root.Add(button);
        root.Add(listView);
        Debug.Log($"items={rows.Count}");
    }
}

代码中三个回调分别承担不同职责:makeItem 创建可复用的视觉元素;bindItem 接收视觉元素和数据索引,将当前数据写入元素;unbindItem 解除旧数据关联。示例的 Label 没有外部事件订阅,因此只需清除旧文本。

进入 Play 模式后,Game 视图应出现宽 420 像素、高 480 像素的可滚动任务列表,上方有一个统计按钮。Console 首先输出:

text
items=10000

滚动列表后点击「打印复用统计」,Console 还会输出:

text
created=<CREATED>, bound=<BOUND>

其中 <CREATED> 是 makeItem 的累计调用次数,<BOUND> 是 bindItem 的累计调用次数。实际数值随面板缩放、滚动位置和内部缓冲策略变化,不应预设固定结果。

检查元素是否真正复用

使用上面的计数器可以直接区分视觉元素创建与数据重新绑定,而不用根据界面看起来是否流畅来判断虚拟化是否有效。

按以下顺序验证:

  1. 进入 Play 模式,不滚动列表,点击统计按钮,记录 created 和 bound。
  2. 将列表从顶部滚动到中间,再滚动到底部,重新点击按钮。
  3. 比较两个计数:正常情况下,created 应远小于数据总数 10000,而 bound 会随着滚动增加。
  4. 反复上下滚动,检查任务编号是否正确,有无空白行、旧文字残留或顺序错乱。

对固定高度列表,频繁滚动后 created 通常不会像 bound 一样持续快速增长。这说明已有视觉元素被重新绑定到不同的数据条目。

还可以通过 Window > UI Toolkit > Debugger 检查运行时面板的视觉树,观察列表实际维护的行元素。它们的数量应明显少于数据源总数。

要衡量真实帧耗时,打开 Window > Analysis > Profiler,使用 CPU Usage 的 Timeline 视图,在目标 Player 上记录打开列表和连续滚动时的 UI 相关样本。比较优化前后的帧时间、布局开销和 GC Alloc,保持数据、窗口大小与滚动操作一致。

选择行高并控制刷新成本

ListView 支持两种垂直虚拟化模式,应根据列表内容的实际布局选择。

配置 适合场景 性能特点
FixedHeight 背包格、单行排行榜、统一高度的任务列表 已知行高,滚动位置计算直接,通常开销较低
DynamicHeight 多行聊天消息、可展开描述、可变高度文本 根据实际布局测量高度,灵活但可能增加布局成本

当前示例采用 FixedHeight 和 fixedItemHeight = 48。行模板应与该高度保持一致。如果实际每行需要 72 像素,却仍配置为 48,就可能产生裁切、重叠或滚动位置不准确等问题。

对于 DynamicHeight,fixedItemHeight 可以作为初始高度估计,建议取合理的最小行高。不要因为文本偶尔换行就无条件改用动态模式;如果产品允许统一行高与文本省略,固定行高通常更适合高频滚动的性能敏感列表。

数据变化时也要区分刷新与重建:

  • 修改现有数据后,可使用 listView.RefreshItem(index) 重新绑定指定可见行,或使用 listView.RefreshItems() 刷新当前可见行。
  • 当行创建方式、makeItem 等结构性配置变化时,才考虑 listView.Rebuild();它会重新创建可见元素,成本更高。
  • 在 bindItem 中避免每次创建复杂子元素、重复注册事件、同步读取磁盘或加载纹理。复杂行结构应优先在 makeItem 中创建,然后在绑定时只更新内容。
  • 如果行内使用图片、订阅或其他外部资源,应在 unbindItem 中解除旧关联,并在确实销毁元素时使用 destroyItem 完成最终清理,避免复用时显示上一条数据。

例如任务状态每秒变化一次,不需要每秒调用 Rebuild()。修改数据对象后,只刷新受影响的可见行即可;如果持续批量更新,则应合并刷新频率并观察 CPU 和 GC 开销。

定位虚拟化后仍然卡顿的问题

虚拟化只能降低长列表的视觉元素数量。如果滚动依然出现长帧,可以依照下面的顺序检查。

  1. **首次打开长帧:**检查 10000 条数据是否在主线程执行了昂贵的解析、排序或图片加载。当前示例只生成简单字符串,真实业务应将重型数据准备工作移出关键显示帧。
  2. **滚动时布局持续偏高:**确认行高是否固定,检查 bindItem 是否频繁修改高度、边距或大量子元素。固定行高列表应尽量保持稳定的几何尺寸。
  3. **滚动时出现 GC Alloc:**检查数据格式化、字符串拼接、临时集合和回调中的对象分配。当前示例直接读取已生成的字符串,避免每次绑定重新格式化任务名称。
  4. **反复打开后内存增长:**检查自定义行是否残留事件订阅、图片引用或外部资源句柄,确认解绑和销毁路径是否完整。

最后做一次对照测试:在相同设备、相同数据规模和相同视口高度下,分别记录首屏显示耗时与连续滚动时的帧时间分布。若视觉元素创建数已明显减少,但耗时仍集中在数据处理或纹理上传,应继续优化对应工作,而不是反复调整虚拟化参数。

对于成千上万条、行高相对稳定的任务或背包列表,优先采用 ListView + FixedHeight + 轻量 bindItem,并用元素创建计数和 Player Profiler 共同验证效果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

UI Toolkit 列表虚拟化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通