---
title: "useMergedRefs 用法与示例"
description: "`useMergedRefs` 是一个合并多个 ref 到单个 ref 的 hook。当你需要在单个 dom 节点上使用多个 ref 时，请使用此 hook。"
canonical: https://reactuse.com/zh-Hans/state/usemergedrefs/
---

# useMergedRefs

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

`useMergedRefs` 接受任意数量的 ref（回调 ref、`RefObject` 或 `undefined`），返回一个将 DOM 节点转发给所有 ref 的单一回调 ref。这消除了在同一元素上手动同步多个 ref 的需要。返回的 ref 是稳定的，统一处理 ref 对象和回调 ref。

### 使用场景

- 将来自 `React.forwardRef` 的转发 ref 与另一个 hook（例如 `useHover`、`useFocus`）使用的内部 ref 合并
- 在同一 DOM 元素上附加多个独立行为（测量、交叉观察、拖拽处理）
- 构建复合组件或组件库，库和使用者都需要 ref 访问

### 注意事项

- **处理所有 ref 类型**：无缝支持 `RefObject`、回调 ref 和 `undefined` 值。
- **SSR 安全**：返回的回调 ref 不会自行访问任何浏览器 API。
- 参见 `useHover` 和其他接受 ref 的元素 hook，可以通过 `useMergedRefs` 合并。

## Usage

```tsx live noInline
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/>)
```

%%API%%