useElementBounding

追踪 HTML 元素边界框的 React Hook

useElementBounding 使用 getBoundingClientRect() 响应式地跟踪 DOM 元素的边界矩形。它返回一个包含 x、y、top、bottom、left、right、width、height 和手动重新测量的 update() 函数的对象。默认情况下，它在窗口滚动和调整大小时自动重新计算。

使用场景

  • 相对于目标元素定位工具提示、弹出框或浮动元素
  • 实现 UI 元素之间的碰撞检测或重叠检查
  • 跟踪元素位置用于滚动关联动画或视差效果

注意事项

  • 响应式：默认在窗口 resize 和 scroll 事件上自动更新。两种行为都可以通过 windowResize 和 windowScroll 选项禁用。
  • SSR 安全：在服务端渲染期间返回零值。设置 immediate: false 延迟首次测量直到你显式调用 update()。
  • 参见 useElementSize 和 useMeasure 了解通过 ResizeObserver 仅跟踪宽高，以及 useWindowSize 了解视口尺寸。

Usage

Live Editor

function Demo() {
  const ref = useRef<HTMLTextAreaElement>(null);
  const rect = useElementBounding(ref);
  return (
    <div>
      <p>调整框的大小以查看变化</p>
      <textarea ref={ref} readOnly value={JSON.stringify(rect, null, 2)} />
    </div>
  );
};
Result

API

useElementBounding

Returns

UseElementBoundingReturn

Arguments

参数名描述类型默认值
target目标元素BasicTarget<Element> (必填)-
options可选参数UseElementBoundingOptions | undefined-

UseElementBoundingOptions

参数名描述类型默认值
reset将数值重置为0booleantrue
windowResize是否监听 resize 事件booleantrue
windowScroll是否监听 scroll 事件booleantrue
immediate立即更新boolean-

UseElementBoundingReturn

参数名描述类型默认值
height元素的高度number (必填)-
bottom元素的底部位置number (必填)-
left元素的左侧位置number (必填)-
right元素的右侧位置number (必填)-
top元素的顶部位置number (必填)-
width元素的宽度number (必填)-
x元素的 X 位置number (必填)-
y元素的 Y 位置number (必填)-
update手动更新() => void (必填)-

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;