TanStack Virtual 中 ResizeObserver 循环未处理通知问题的解决方案

问题背景

在使用 TanStack Virtual（原 react-virtual）虚拟滚动库时，开发者可能会遇到控制台报错："Uncaught ResizeObserver loop completed with undelivered notifications"。这个错误虽然不会影响生产环境的运行，但在开发过程中会带来困扰。

问题本质

这个错误源于 ResizeObserver API 的工作机制。当元素尺寸发生变化时，ResizeObserver 会尝试通知所有观察者。如果在处理这些通知时又触发了新的布局变化，就可能出现通知无法及时传递的情况，导致浏览器抛出这个警告。

解决方案

TanStack Virtual 提供了专门的配置项来解决这个问题：

const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 45,
  useAnimationFrameWithResizeObserver: true // 启用此选项
});

技术原理

当启用 useAnimationFrameWithResizeObserver 选项后，虚拟滚动库会使用 requestAnimationFrame 来调度 ResizeObserver 的回调。这种方法可以：

1. 将尺寸变化的处理推迟到浏览器下一次重绘之前
2. 避免在布局计算过程中触发新的布局变化
3. 减少不必要的重排和重绘
4. 提高滚动的流畅度

最佳实践

1. 在开发环境中启用此选项可以消除控制台警告
2. 在生产环境中虽然可以关闭，但建议保持开启以获得更平滑的滚动体验
3. 对于复杂列表，配合 overscan 属性一起使用效果更佳

注意事项

1. 此解决方案需要 TanStack Virtual v3.0.0 及以上版本
2. 在某些极端情况下可能仍会出现警告，但不影响功能
3. 如果性能成为问题，可以考虑调整动画帧节流策略

通过合理配置 TanStack Virtual 的这些选项，开发者可以获得既无警告又高性能的虚拟滚动体验。