TanStack Virtual 中 max-height 容器首次渲染问题解析

问题现象

在使用 TanStack Virtual（原 react-virtual）时，当虚拟列表容器采用 max-height 而非固定高度时，首次渲染会出现可见项数量计算不准确的问题。具体表现为：

1. 首次渲染时，虚拟列表虽然正确计算了容器高度
2. 但显示的可见项数量不足，无法填满可用空间
3. 触发重新渲染后，才会显示正确数量的项目

问题根源

这种问题的出现与虚拟列表库的工作机制有关。TanStack Virtual 在首次渲染时需要确定：

1. 容器的高度（viewport 尺寸）
2. 每个项目的高度（用于计算可见范围）

当使用 max-height 时，容器高度是动态计算的。库在首次渲染时可能无法准确获取最终高度值，导致：

• 高度测量发生在渲染之后
• 初始可见项计算基于不完整的高度信息
• 后续渲染时才能获取准确高度并正确计算

解决方案

方案一：使用 initialRect 参数

通过为 useVirtualizer 提供 initialRect 选项，可以手动设置初始高度估计值：

const rowVirtualizer = useVirtualizer({
  count: rows.length,
  estimateSize: () => 35, // 每行高度估计值
  getScrollElement: () => parentRef.current,
  initialRect: { height: rows.length * 35 } // 初始高度估计
})

这种方法让虚拟列表在首次渲染时就有一个合理的高度估计值，避免出现可见项不足的情况。

方案二：强制重新渲染

在容器尺寸稳定后强制触发重新渲染：

const [ready, setReady] = useState(false);

useEffect(() => {
  const timer = setTimeout(() => setReady(true), 100);
  return () => clearTimeout(timer);
}, []);

// 在依赖项中加入 ready
const rowVirtualizer = useVirtualizer({
  count: rows.length,
  estimateSize: () => 35,
  getScrollElement: () => parentRef.current,
})

方案三：使用 ResizeObserver

对于更复杂的动态尺寸场景，可以使用 ResizeObserver 监听容器尺寸变化：

useEffect(() => {
  if (!parentRef.current) return;
  
  const observer = new ResizeObserver(() => {
    rowVirtualizer.measure();
  });
  
  observer.observe(parentRef.current);
  return () => observer.disconnect();
}, []);

最佳实践建议

1. 对于已知行高的列表，优先使用 initialRect 提供初始估计值
2. 对于动态高度的项目，确保 estimateSize 尽可能准确
3. 复杂场景下考虑结合 ResizeObserver 实现响应式调整
4. 避免完全依赖 max-height，尽可能提供确定的高度值

总结

TanStack Virtual 在处理动态高度容器时，首次渲染可能出现可见项计算不准确的问题。通过理解虚拟列表的工作原理，并采用适当的初始化策略，可以确保列表在各种高度场景下都能正确渲染。开发者应根据具体场景选择最适合的解决方案，以提供最佳的用户体验。