游戏引擎 / 系统课时
UI Toolkit 列表虚拟化
UI Toolkit 列表虚拟化
当任务面板或排行榜包含上万条记录时,逐条创建 UI 元素会增加首屏构建、布局和滚动成本。本课使用 Unity 6 的 ListView 实现长列表虚拟化,并通过实际运行和计数验证元素复用效果。
学习目标
- 理解
ListView如何通过可见区域裁剪与元素复用减少 UI 元素数量。 - 使用
makeItem、bindItem和固定行高创建可运行的万条数据列表。 - 根据行高、数据更新方式和 Profiler 结果检查虚拟化效果。
虚拟化如何减少 UI 工作量
普通 ScrollView 如果一次添加 10000 个 Label,视觉树就需要管理这些元素,即使绝大部分位于屏幕外,也会增加初始化、内存和潜在的布局工作量。
ListView 则保留完整数据源,但只创建显示当前视口及缓冲区域所需的少量视觉元素。滚动时,离开视口的元素可以重新绑定到新的数据索引,而不必为每条数据永久保留独立元素。
例如列表包含 10000 条记录,视口高度为 480 像素,每行高度为 48 像素,那么同一时刻大约能显示 10 行。实际创建的元素数量还包含 Unity 管理的缓冲元素,不应直接认定为恰好 10 个。

虚拟化减少的是视觉元素及相关 UI 工作量,并不会自动减少 itemsSource 中的数据数量,也不会自动实现网络分页。对于包含图片的列表,图片资源的加载和释放仍需要单独管理。
创建可运行的万条数据列表
以下示例适用于 Unity 6(6000.0 及后续版本)的运行时 UI Toolkit。使用纯 C# 创建列表,无须制作列表行 UXML 模板。
首先配置场景:
- 在 Unity 编辑器中打开场景,选择
GameObject > UI Toolkit > UI Document,创建运行时 UI 对象。 - 检查该对象的
UIDocument组件,确保Panel Settings已引用有效的面板设置资产。如果没有,可通过Assets > Create > UI Toolkit > Panel Settings Asset创建后赋值。 - 本示例通过代码创建所有 UI,
Source Asset可以留空。 - 在
Assets下新建脚本VirtualizedListDemo.cs,将其挂到刚创建的 UI 对象上。
完整脚本如下:
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 首先输出:
items=10000滚动列表后点击「打印复用统计」,Console 还会输出:
created=<CREATED>, bound=<BOUND>其中 <CREATED> 是 makeItem 的累计调用次数,<BOUND> 是 bindItem 的累计调用次数。实际数值随面板缩放、滚动位置和内部缓冲策略变化,不应预设固定结果。
检查元素是否真正复用
使用上面的计数器可以直接区分视觉元素创建与数据重新绑定,而不用根据界面看起来是否流畅来判断虚拟化是否有效。
按以下顺序验证:
- 进入 Play 模式,不滚动列表,点击统计按钮,记录
created和bound。 - 将列表从顶部滚动到中间,再滚动到底部,重新点击按钮。
- 比较两个计数:正常情况下,
created应远小于数据总数 10000,而bound会随着滚动增加。 - 反复上下滚动,检查任务编号是否正确,有无空白行、旧文字残留或顺序错乱。
对固定高度列表,频繁滚动后 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 开销。
定位虚拟化后仍然卡顿的问题
虚拟化只能降低长列表的视觉元素数量。如果滚动依然出现长帧,可以依照下面的顺序检查。
- **首次打开长帧:**检查 10000 条数据是否在主线程执行了昂贵的解析、排序或图片加载。当前示例只生成简单字符串,真实业务应将重型数据准备工作移出关键显示帧。
- **滚动时布局持续偏高:**确认行高是否固定,检查
bindItem是否频繁修改高度、边距或大量子元素。固定行高列表应尽量保持稳定的几何尺寸。 - **滚动时出现 GC Alloc:**检查数据格式化、字符串拼接、临时集合和回调中的对象分配。当前示例直接读取已生成的字符串,避免每次绑定重新格式化任务名称。
- **反复打开后内存增长:**检查自定义行是否残留事件订阅、图片引用或外部资源句柄,确认解绑和销毁路径是否完整。
最后做一次对照测试:在相同设备、相同数据规模和相同视口高度下,分别记录首屏显示耗时与连续滚动时的帧时间分布。若视觉元素创建数已明显减少,但耗时仍集中在数据处理或纹理上传,应继续优化对应工作,而不是反复调整虚拟化参数。
对于成千上万条、行高相对稳定的任务或背包列表,优先采用 ListView + FixedHeight + 轻量 bindItem,并用元素创建计数和 Player Profiler 共同验证效果。