TanStack Virtual 在 iOS 16 以下版本的滚动边界处理问题

在 React 虚拟滚动库 TanStack Virtual 的使用过程中，开发者可能会遇到一个与 iOS 浏览器滚动行为相关的特殊问题。这个问题主要出现在 iOS 16 以下版本的设备上，表现为当用户滚动到容器边缘时会出现异常的反弹动画效果。

问题现象

当在 iOS 16 以下版本的浏览器中使用 TanStack Virtual 进行水平或垂直虚拟滚动时，如果用户尝试滚动超过容器的边界（即尝试滚动到内容开始之前或结束之后），会出现不自然的反弹动画。具体表现为滚动位置会突然跳回边界值，导致用户体验不佳。

问题根源

这个问题源于 iOS 16 以下版本浏览器对滚动行为的特殊处理机制。在这些版本的 Safari 中，当滚动超过边界时，浏览器会强制触发一个反弹效果，这会导致虚拟滚动库的偏移量计算出现异常，进而引发重新渲染和布局重排。

解决方案

TanStack Virtual 提供了 observeElementOffset 配置项，允许开发者自定义滚动偏移量的观察行为。我们可以利用这个配置项来限制滚动偏移量始终保持在有效范围内，从而避免 iOS 的边界反弹问题。

以下是推荐的解决方案实现：

const virtualizer = useVirtualizer({
  horizontal: true,
  count,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 100,
  overscan: 6,
  observeElementOffset: (instance, cb) =>
    observeElementOffset(instance, (offset, isScrolling) =>
      cb(
        Math.max(
          0,
          Math.min(
            offset,
            instance.options.horizontal
              ? instance.scrollElement.scrollWidth - 
                  instance.scrollElement.clientWidth
              : instance.scrollElement.scrollHeight - 
                  instance.scrollElement.clientHeight
          )
        ),
        isScrolling
      )
});

实现原理

这个解决方案的核心在于对滚动偏移量进行钳制处理：

1. 获取当前滚动方向（水平或垂直）的最大允许偏移量

   • 水平方向：scrollWidth - clientWidth
   • 垂直方向：scrollHeight - clientHeight

2. 使用 Math.max(0, Math.min(offset, maxOffset)) 确保偏移量始终在 0 到最大允许值之间

3. 将处理后的偏移量传递给原始回调函数

这种方法有效地阻止了 iOS 浏览器在边界处的异常反弹行为，同时保持了虚拟滚动的正常功能。

注意事项

1. 此解决方案主要针对 iOS 16 以下版本，现代浏览器通常不需要这种处理

2. 在使用自定义 observeElementOffset 时，需要确保正确处理 isScrolling 参数，避免在初始化时错误地标记为滚动状态

3. 对于复杂的虚拟滚动场景，可能需要根据实际需求调整钳制逻辑

通过这种处理方式，开发者可以在保持 TanStack Virtual 高性能特性的同时，解决 iOS 旧版本浏览器中的滚动边界问题，提供更流畅的用户体验。