useSticky

跟踪元素是否粘滞

useSticky 检测元素是否已滚动过阈值并应变为”粘性”。它通过观察容器（或窗口）相对于守卫元素的滚动位置工作，返回一个 [isSticky, setIsSticky] 元组。你可以通过 nav 偏移量（例如固定头部高度）进行配置，并可选择指定滚动轴（x 或 y）。

使用场景

• 实现在滚动过某一点后固定的粘性头部、导航栏或侧边栏
• 构建在滚动后出现的”回到顶部”按钮或浮动操作栏
• 创建基于相对于标记元素的滚动位置改变样式或行为的滚动感知 UI

注意事项

• 滚动容器：默认情况下，hook 监听窗口滚动。传入第三个 scrollElement ref 以观察特定容器内的滚动。
• 轴支持：在参数中设置 axis: 'x' 跟踪水平滚动而非默认的垂直（'y'）。
• 参见 useWindowScroll 了解跟踪窗口的原始滚动位置。

Usage

function Demo() {
  const element = useRef<HTMLDivElement>(null);
  const [isSticky] = useSticky(element, {
    // header fixed height
    nav: 64,
  });

  const stickyStyle: CSSProperties = isSticky
    ? {
        position: "fixed",
        top: 64,
        zIndex: 50,
        height: 20,
      }
    : {
        height: 20,
      };

  const guardStyle: CSSProperties = {
    width: 1,
    height: 1,
  };

  return (
    <div style={{height: 300,overflow: 'scroll'}}>
      <div ref={element} style={guardStyle} />
      <button style={stickyStyle}>
        {isSticky ? "粘滞中" : "未粘滞"}
      </button>
      <div style={{ height: "100vh" }} />
    </div>
  );
};

API

useSticky

Returns

[boolean, React.Dispatch<React.SetStateAction<boolean>>]: 包含以下元素的元组：

• 当前是否粘滞。
• 更新粘滞值的函数。

Arguments

UseStickyParams

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;