useMergedRefs

useMergedRefs 是一个合并多个 ref 到单个 ref 的 hook。当你需要在单个 dom 节点上使用多个 ref 时，请使用此 hook。

useMergedRefs 將多個 React ref 合併為一個。當你需要將多個 ref 附加到同一個 DOM 元素時（例如一個 ref 用於內部邏輯，另一個從 forwardRef 轉發），此 hook 非常有用。回傳的合併 ref 在設定時會同步更新所有輸入 ref。

使用場景

在使用 forwardRef 的元件中同時保持內部 ref 和外部轉發 ref
將多個 hook 回傳的 ref 附加到同一個元素
整合需要自己 ref 的多個函式庫到同一個元素

注意事項

Ref 類型：支援回呼 ref 和物件 ref（useRef 建立的 ref）。
空值處理：自動忽略 null 或 undefined 的 ref。
相關 hooks：另請參閱 useLatest 用於保持對最新值的 ref。

Usage

Live Editor

function Demo() {
  const hoverRef = useRef(null);
  const buttonRef = useRef<HTMLButtonElement>(null);
  const isHovered = useHover(hoverRef);
  const [isFocused, toggleFocus] = useToggle(false);

  const mergedRef = useMergedRefs(hoverRef, buttonRef);

  useEffect(() => {
    const handleKeyPress = (event) => {
      if (event.key === 'f' || event.key === 'F') {
        buttonRef.current?.focus();
      }
    };

    window.addEventListener('keypress', handleKeyPress);

    return () => {
      window.removeEventListener('keypress', handleKeyPress);
    };
  }, []);

  const handleFocus = () => toggleFocus(true);
  const handleBlur = () => toggleFocus(false);

  return (
    <div>
      <button
        ref={mergedRef}
        onFocus={handleFocus}
        onBlur={handleBlur}
        style={{
          padding: '10px 20px',
          backgroundColor: isHovered ? 'lightblue' : isFocused ? 'lightyellow' : 'white',
          border: '1px solid black',
          cursor: 'pointer',
          outline: isFocused ? '2px solid blue' : 'none',
        }}
      >
        {isHovered ? '已懸停！' : isFocused ? '已聚焦！' : '懸停或聚焦我'}
      </button>
      <p>按 'F' 鍵聚焦按鈕</p>
    </div>
  );
};

render(<Demo/>)

Result

API

useMergedRef

Returns

(node: T | null) => void: 合併多個 ref 的函數

Arguments

參數名	描述	類型	預設值
refs	-	PossibleRef<T>[]	-

PossibleRef

export type PossibleRef<T> = Ref<T> | undefined;