useWindowScroll

useWindowScroll 是一个 React Hook，它用于获取浏览器窗口的滚动位置

useWindowScroll 以响应式状态对象返回浏览器窗口当前的水平（x）和垂直（y）滚动位置。它监听窗口上的 scroll 事件，并在用户滚动时更新值。这提供了一种简单的方式将 window.scrollX 和 window.scrollY 作为 React 状态访问。

使用场景

  • 构建滚动进度指示器或阅读位置追踪器
  • 实现视差滚动效果或滚动关联动画
  • 基于当前滚动位置显示或隐藏 UI 元素（例如”回到顶部”按钮）

注意事项

  • SSR 安全：在服务端渲染期间返回 { x: 0, y: 0 }，因为 window 不可用。
  • 性能：该 hook 监听窗口的 scroll 事件。对于高频滚动跟踪，考虑在消费组件中结合 requestAnimationFrame 或节流。
  • 参见 useSticky 了解检测元素何时应变为粘性，以及 useWindowSize 了解跟踪视口尺寸。

Usage

Live Editor
function Demo() {
  return (
    <div>
      <div>
        <iframe
          src="https://codesandbox.io/embed/dreamy-lehmann-mzg96r?fontsize=14&hidenavigation=1&theme=dark"
          style={{
            width: "100%",
            height: 500,
            border: 0,
            borderRadius: 4,
            overflow: "hidden",
          }}
          title="dreamy-lehmann-mzg96r"
          allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
          sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
        >
        </iframe>
      </div>
    </div>
  );
};
Result

API

useWindowScroll

Returns

UseWindowScrollState

Arguments

useWindowScrollState

参数名描述类型默认值
x水平滚动的像素值number (必填)-
y垂直滚动的像素值number (必填)-