useElementBounding

追踪 HTML 元素边界框的 React Hook

useElementBounding 響應式追蹤 DOM 元素的邊界矩形，使用 ResizeObserver 和捲動/調整大小事件。它回傳元素的 width、height、top、right、bottom、left、x 和 y 值，在元素大小或位置變更時自動更新。

使用場景

  • 根據元素尺寸和位置定位工具提示或彈出框
  • 建構依賴元素邊界的響應式佈局邏輯
  • 追蹤元素在視窗中的位置以實現捲動動畫效果

注意事項

  • SSR 安全：在伺服器端渲染時所有值回傳 0。伺服器上不會進行 DOM 測量。
  • 效能：使用 ResizeObserver 實現高效的尺寸追蹤。可透過選項停用捲動和調整大小事件監聽以進一步優化。
  • 相關 hooks：另請參閱 useElementSize 僅追蹤尺寸，useMeasure 用於 content-box 測量，以及 useResizeObserver 用於低階的 ResizeObserver 存取。

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;