Blazor中Virtualize多行布局滚动时如何保持项水平位置一致？

问题现象 #

使用<Virtualize>组件渲染千级项规模的列表，通过display: inline-block样式实现单行多列的网格布局时，基础功能可正常运行，但滚动交互存在严重体验问题：

• 滚动过程中，组件会从DOM头部移除不定数量的项，同时在尾部追加新项，直接导致已渲染项位置偏移，触发页面重排：原本位于某行第3位的项，可能跳转至新行的第1、2、4位
• 滚动触发项更新后，用户无法追踪视口内应展示的项，完全丢失滚动位置感知
• 已尝试的无效修复手段：给Virtualize子内容添加@key指令、显式设置ItemSize参数，均未改善错位问题

问题可稳定复现：

缓慢向下滚动列表，以项的6位十六进制ID作为不同项的区分标识：

1. 向下滚动一段距离、第一次重排触发前，列表最后一项后方会出现明显空隙
   
2. 小幅继续向下滚动即触发重排，所有已加载项的位置发生跳变
   

行为对比 #

• 预期行为：滚动时，原本靠近视口底部的项应保持原有水平位置，随滚动自然移动到视口上部区域，新项在现有项后方按顺序加载展示
• 实际行为：滚动后仅能看到部分之前加载的项，且这些项的水平位置发生偏移，部分项直接跳到视口上方，用户丢失滚动位置的上下文感知
• 附加异常表现：第一次重排触发前，列表最后一行始终处于不完整状态，直到该行完全滚动进入视口才会触发重渲染/重排，仿佛组件无法识别当前视口可容纳的总项数，该表现与核心错位问题直接相关

核心矛盾 #

理想状态下，垂直虚拟列表的DOM项增删操作，应当以单行可容纳的最大项数为增减的倍数单位，但目前原生<Virtualize>组件没有提供传入该数值的配置入口，且该数值理论上需要结合容器宽度、单项宽度动态计算。

根本原因 #

原生<Virtualize>组件的虚拟滚动逻辑完全基于单条项的固定垂直高度做偏移计算，默认每一个项单独占据一整行，完全没有感知多列网格布局的存在。因此组件增减项时以单条项为单位计算占位高度，直接导致高度计算偏差、项数增减粒度错误，最终引发水平位置错位、滚动位置跳变的问题。

解决方案 #

方案1：行级虚拟滚动封装（最稳定，无第三方依赖） #

不要直接将单个数据项作为Virtualize的渲染单元，而是先把原始数据源按单行可容纳的项数分组，将每一行作为Virtualize的单个渲染项，完全贴合组件原生的高度计算逻辑：

1. 固定单项宽度、单行高度，监听列表容器的尺寸变化，计算当前容器宽度下单行最多可容纳的项数itemsPerRow，计算逻辑为容器可用宽度 / 单项固定宽度，结果向下取整
2. 将原始的平铺数据列表，按itemsPerRow的长度分组成二维数组，每个子数组对应一整行的所有项
3. 将Virtualize的ItemSize参数设置为单行的固定高度（注意不是单项高度）
4. Virtualize的子内容负责渲染整行容器，在容器内遍历当前行的子数组，渲染单行内的所有项，行内使用flex布局或者display: inline-block排列项即可

核心实现代码参考：

@* 给外层容器设置@ref用于获取宽度，监听resize事件 *@
<div @ref="_listContainer" class="virtual-list-container">
    <Virtualize Items="_rowGroups" ItemSize="@ROW_HEIGHT">
        <ItemContent>
            <div class="list-row" style="height: @ROW_HEIGHTpx;">
                @foreach (var product in context)
                {
                    <div class="list-item" style="width: @ITEM_WIDTHpx;">
                        @product.Id
                        @* 其他项内容 *@
                    </div>
                }
            </div>
        </ItemContent>
    </Virtualize>
</div>

<style>
    .virtual-list-container { width: 100%; }
    .list-row { width: 100%; display: flex; flex-wrap: nowrap; }
    .list-item { flex-shrink: 0; display: inline-block; box-sizing: border-box; }
</style>

@code {
    private ElementReference _listContainer;
    private List<Product> _allItems = new(1000);
    private List<Product[]> _rowGroups = new();
    private const int ITEM_WIDTH = 200;
    private const int ROW_HEIGHT = 240;
    private int _itemsPerRow;

    protected override void OnInitialized()
    {
        // 初始化填充千条测试数据
        for (int i = 0; i < 1000; i++)
        {
            _allItems.Add(new Product { Id = Guid.NewGuid().ToString("N")[..6] });
        }
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            // 首次渲染后计算初始列数，绑定容器尺寸变化监听
            await UpdateItemsPerRowAsync();
            // 监听容器resize，宽度变化时重新计算列数、重建行分组
        }
    }

    private async Task UpdateItemsPerRowAsync()
    {
        // 获取容器实际宽度，计算单行可容纳项数
        var containerWidth = await _listContainer.GetBoundingClientRectAsync();
        var newItemsPerRow = Math.Max(1, (int)(containerWidth.Width / ITEM_WIDTH));
        if (newItemsPerRow != _itemsPerRow)
        {
            _itemsPerRow = newItemsPerRow;
            RebuildRowGroups();
            StateHasChanged();
        }
    }

    private void RebuildRowGroups()
    {
        _rowGroups = _allItems
            .Select((item, index) => (item, index))
            .GroupBy(x => x.index / _itemsPerRow)
            .Select(g => g.Select(x => x.item).ToArray())
            .ToList();
    }

    public class Product { public string Id { get; set; } }
}

该方案下Virtualize的增减粒度永远是整行，不会出现半行加载、项水平错位的问题，滚动位置计算完全准确，窗口尺寸变化时只需要重新计算列数、重建分组即可适配。

方案2：使用原生支持网格虚拟滚动的组件 #

如果不想自行处理尺寸监听、数据分组逻辑，可以直接替换为原生支持多列/网格虚拟滚动的Blazor组件，这类组件内部已经实现了列数自动计算、按行批量增减项的逻辑，不需要额外封装。选型时注意确认组件的虚拟滚动计算逻辑是基于行高而非单项高度，避免复现同类错位问题。

避坑说明 #

以下手段无法从根本解决问题，不推荐浪费时间尝试：

• 仅给子项加@key、仅调整ItemSize数值：两个配置都没有改变Virtualize按单条项计算高度、单条为单位增减项的核心逻辑
• 给单项加绝对定位、手动计算每个项的偏移量：维护成本极高，窗口缩放、尺寸变化场景下极易出现新的错位问题

内容的提问来源于stack exchange，提问作者Patrick Szalapski