useEventListener

輕鬆使用 EventListener。

useEventListener 簡化了 DOM 事件監聽器的新增和移除。它接受事件名稱、處理函式和可選的目標元素（預設為 window），在元件掛載時自動附加監聽器，卸載時自動移除。支援所有標準 AddEventListenerOptions。

使用場景

  • 監聽視窗事件如 resize、scroll 或 keydown 而無需手動清理
  • 為特定 DOM 元素新增事件監聽器並確保正確清理
  • 以宣告式方式管理事件監聽器的生命週期

注意事項

  • SSR 安全：在伺服器端渲染時為空操作。伺服器上不會附加事件監聽器。
  • 自動清理：監聽器在元件卸載或依賴變更時自動移除，防止記憶體洩漏。
  • 相關 hooks：另請參閱 useEvent 用於建立穩定的事件處理器參考，以及 useEventEmitter 用於自訂事件系統。

Usage

Live Editor

function Demo() {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const [state, setState] = useState("未雙擊");

  const onDBClick = () => {
    setState("已雙擊");
  };

  const onClick = (event: Event) => {
    console.log("按鈕被點擊！", event);
  };

  const onVisibilityChange = (event: Event) => {
    console.log("文檔可見性已更改！", {
      isVisible: !document.hidden,
      event,
    });
  };

  // example with window based event
  useEventListener("dblclick", onDBClick);

  // example with document based event
  useEventListener("visibilitychange", onVisibilityChange, () => document);

  // example with element based event
  useEventListener("click", onClick, buttonRef);

  return (
    <div>
      <p>{state}</p>
      <button ref={buttonRef}>點擊我</button>
    </div>
  );
};
Result

API

useEventListener

Returns

void

Arguments

參數名描述類型預設值
eventName事件名称string (必填)-
handler事件处理器(event: any) => void (必填)-
elementdom元素EventTarget | Element | Document | HTMLElement | Window | null | undefinedwindow
options监听选项boolean | AddEventListenerOptions | undefined-