useScrollIntoView

類似於 element.scrollIntoView() 的 React Hook

useScrollIntoView 提供程式化的平滑捲動功能，將目標元素捲動到可視範圍內。它回傳一個物件，包含 scrollIntoView 函式和 cancel 函式。支援可設定的動畫時長、緩動函式和偏移量，並可在清單上下文中防止內容跳動。

使用場景

• 在表單驗證失敗時將使用者捲動到第一個錯誤欄位
• 實作「跳轉到頂部」或「跳轉到章節」按鈕
• 在清單中添加新項目後自動捲動以顯示新增內容

注意事項

• SSR 安全：在伺服器端渲染時回傳空操作函式。伺服器上不會進行 DOM 捲動。
• 可取消：設定 cancelable: true（預設）允許使用者透過手動捲動中斷捲動動畫。設定 isList: true 可防止清單中的內容跳動。
• 相關 hooks：另請參閱 useScroll 追蹤捲動位置和狀態，以及 useScrollLock 完全防止捲動。

Usage

function Demo() {
  const targetRef = useRef<HTMLParagraphElement>(null);
  const { scrollIntoView } = useScrollIntoView(targetRef, {
    offset: 60,
  });

  return (
    <div>
      <button onClick={() => scrollIntoView({ alignment: "center" })}>
        滾動到目標
      </button>
      <div style={{ height: "50vh" }} />
      <p ref={targetRef}>你好，這裡是目標</p>
    </div>
  );
}

API

useScrollIntoView

Returns

{ scrollIntoView: (animation?: UseScrollIntoViewAnimation | undefined) => void; cancel: () => void; }: 包含以下元素的對象：

• scrollIntoView：滚動進入視口函數。
• cancel： 取消滚動函數。

Arguments

UseScrollIntoViewAnimation

UseScrollIntoViewParams

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;