React + TypeScript：forwardRef 型別定義完整指南

---

簡介

在 React 中，ref 提供了一條直接存取 DOM 元素或子元件實例的管道，常用於聚焦、測量尺寸或與第三方 UI 函式庫整合。當我們在 TypeScript 專案裡使用 ref 時，若不正確地為 forwardRef 產生型別，會導致編譯錯誤、IDE 智慧提示失效，甚至執行時出現不可預期的行為。

本篇文章聚焦於 React 的 forwardRef，說明如何在 TypeScript 中為它寫出正確且可維護的型別定義。從基礎概念到進階寫法，配合 4 個實務範例、常見陷阱與最佳實踐，幫助你在日常開發中安全、快速地使用 forwardRef。

---

核心概念

1. 為什麼需要 forwardRef？

forwardRef 允許父層元件把 ref 直接傳遞給子層的 DOM 或 自訂元件，而不必透過額外的 props 轉發。這在以下情境特別有用：

• 聚焦表單欄位：父元件想要在表單載入後自動聚焦某個 <input>。
• 與第三方 UI 函式庫整合：許多 UI 套件（如 Material‑UI、Ant Design）要求外部取得內部的 DOM 節點。
• 高階元件 (HOC) 的透明化：HOC 包裝後仍希望保留原始元件的 ref 能力。

2. forwardRef 的基本型別

在 JavaScript 中，我們這樣寫：

import React, { forwardRef } from 'react';

const MyButton = forwardRef((props, ref) => (
  <button ref={ref} {...props}>Click me</button>
));

在 TypeScript 中，forwardRef 會返回一個泛型函式。最簡單的型別寫法如下：

import React, { forwardRef, ButtonHTMLAttributes } from 'react';

const MyButton = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement>>(
  (props, ref) => (
    <button ref={ref} {...props}>Click me</button>
  )
);

• 第一個泛型參數 (HTMLButtonElement) 表示 ref 最終指向的 DOM 類型。
• 第二個泛型參數 (ButtonHTMLAttributes<HTMLButtonElement>) 為 props 的型別。

重點：若省略這兩個泛型，ref 會被推斷為 any，失去型別安全。

3. React.Ref 與 React.RefObject 的差別

型別	說明
React.Ref<T>	可以是 RefObject<T>、回呼函式 `(instance: T
React.RefObject<T>	由 React.createRef<T>() 產生，擁有 .current 屬性。常在類別元件或函式元件裡使用。

在 forwardRef 中，我們通常不需要自行宣告 React.Ref<T>，只要在泛型裡提供 T（即最終的 DOM 或元件實例型別）即可。

4. 自訂元件的 forwardRef 型別

如果 ref 需要指向 子元件的實例（例如使用 useImperativeHandle 暴露方法），型別會稍微複雜一些。下面示範一個「可聚焦」的自訂 Input 元件：

import React, { forwardRef, useImperativeHandle, useRef } from 'react';

export interface FocusableInputHandle {
  focus: () => void;
}

const FocusableInput = forwardRef<FocusableInputHandle, React.InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    const innerRef = useRef<HTMLInputElement>(null);

    // 把 focus 方法暴露給外層 ref
    useImperativeHandle(ref, () => ({
      focus: () => innerRef.current?.focus(),
    }));

    return <input ref={innerRef} {...props} />;
  }
);

• forwardRef<FocusableInputHandle, ...>：FocusableInputHandle 定義了外層可以呼叫的介面。
• useImperativeHandle：將內部的 focus 方法映射到外部。

5. React.ForwardRefExoticComponent 與 React.RefAttributes

當我們把 forwardRef 包裝成 具備靜態屬性（如 displayName）的元件時，會得到 React.ForwardRefExoticComponent<P>：

type MyCompProps = { label: string };
const MyComp = forwardRef<HTMLDivElement, MyCompProps>((props, ref) => (
  <div ref={ref}>{props.label}</div>
));

MyComp.displayName = 'MyComp';
// MyComp 的型別是 React.ForwardRefExoticComponent<MyCompProps & React.RefAttributes<HTMLDivElement>>

• React.RefAttributes<T> 會自動加入 ref?: React.Ref<T> 的屬性，使得使用 MyComp 時能直接傳入 ref。

---

程式碼範例

以下提供 四個實務範例，從最簡單的 DOM 轉發到自訂 hook 暴露方法，皆附上完整的型別說明與註解。

範例 1：最簡單的 forwardRef（Button）

import React, { forwardRef, ButtonHTMLAttributes } from 'react';

// 1️⃣ 指定 ref 指向的 DOM 類型與 props 型別
const SimpleButton = forwardRef<
  HTMLButtonElement,                         // ref 最終指向 <button>
  ButtonHTMLAttributes<HTMLButtonElement>   // props 繼承原生 button 屬性
>((props, ref) => {
  // 2️⃣ 將 ref 直接掛在 <button> 上
  return <button ref={ref} {...props} />;
});

export default SimpleButton;

使用方式

const btnRef = React.useRef<HTMLButtonElement>(null);
<SimpleButton ref={btnRef} onClick={() => btnRef.current?.focus()}>點我</SimpleButton>

---

範例 2：自訂 Input 並暴露 focus 方法

import React, {
  forwardRef,
  useImperativeHandle,
  useRef,
  InputHTMLAttributes,
} from 'react';

// 1️⃣ 定義外部可以呼叫的介面
export interface InputHandle {
  focus: () => void;
}

// 2️⃣ forwardRef 的泛型：<介面, props>
const CustomInput = forwardRef<InputHandle, InputHTMLAttributes<HTMLInputElement>>(
  (props, ref) => {
    const innerRef = useRef<HTMLInputElement>(null);

    // 3️⃣ 把 focus 方法映射到外層 ref
    useImperativeHandle(ref, () => ({
      focus: () => innerRef.current?.focus(),
    }));

    return <input ref={innerRef} {...props} />;
  }
);

export default CustomInput;

使用方式

const inputRef = React.useRef<InputHandle>(null);
<CustomInput ref={inputRef} placeholder="請輸入文字" />
<button onClick={() => inputRef.current?.focus()}>聚焦輸入框</button>

---

範例 3：在 HOC 中保留 forwardRef 的型別

import React, {
  forwardRef,
  ComponentType,
  PropsWithChildren,
  Ref,
} from 'react';

// 1️⃣ HOC 會接收一個具備 ref 的元件，並回傳同樣支援 ref 的元件
function withLoading<P, T>(WrappedComponent: ComponentType<P & React.RefAttributes<T>>) {
  const ComponentWithLoading = forwardRef<T, PropsWithChildren<P>>(
    (props, ref) => {
      const [loading, setLoading] = React.useState(false);

      // 假設有一些非同步操作
      const handleClick = async () => {
        setLoading(true);
        // ... async work
        setLoading(false);
      };

      return (
        <div>
          {loading && <span>載入中...</span>}
          {/* 2️⃣ 把 ref 直接傳給 WrappedComponent */}
          <WrappedComponent {...props} ref={ref as Ref<T>} />
          <button onClick={handleClick}>觸發載入</button>
        </div>
      );
    }
  );

  // 讓開發者在除錯時能看到正確的名稱
  ComponentWithLoading.displayName = `withLoading(${WrappedComponent.displayName || WrappedComponent.name})`;
  return ComponentWithLoading;
}

// ----- 使用範例 -----
type CardProps = { title: string };
const Card = forwardRef<HTMLDivElement, CardProps>((props, ref) => (
  <div ref={ref}>
    <h3>{props.title}</h3>
  </div>
));

export default withLoading(Card);

說明

• ComponentType<P & React.RefAttributes<T>> 確保 WrappedComponent 接受 ref。
• forwardRef<T, PropsWithChildren<P>> 中的 T 為最終的 ref 型別，PropsWithChildren<P> 讓 HOC 仍能接受子元素。

---

範例 4：結合 React.memo 與 forwardRef（最佳化）

import React, {
  forwardRef,
  memo,
  ButtonHTMLAttributes,
} from 'react';

// 1️⃣ 定義 Props，使用泛型延伸原生 button 屬性
type IconButtonProps = {
  icon: React.ReactNode;
} & ButtonHTMLAttributes<HTMLButtonElement>;

// 2️⃣ forwardRef + memo：先 forwardRef 再包 memo
const IconButton = memo(
  forwardRef<HTMLButtonElement, IconButtonProps>((props, ref) => {
    const { icon, children, ...rest } = props;
    return (
      <button ref={ref} {...rest}>
        {icon}
        {children}
      </button>
    );
  })
);

IconButton.displayName = 'IconButton';

export default IconButton;

使用方式

const btnRef = React.useRef<HTMLButtonElement>(null);
<IconButton
  ref={btnRef}
  icon={<i className="fa fa-search" />}
  onClick={() => console.log('clicked')}
/>

---

常見陷阱與最佳實踐

陷阱	說明	解決方式
忘記指定 ref 的泛型	forwardRef 預設回傳 any，失去型別安全。	永遠在 forwardRef<T, P> 中提供 T（ref 指向的型別）。
useImperativeHandle 回傳的物件與介面不匹配	編譯器不會自動檢查回傳物件與 forwardRef 泛型是否一致。	為回傳物件寫明 介面（如 InputHandle），並在 forwardRef 中使用相同介面。
在 HOC 中遺失 ref	HOC 常以 props 方式包裝子元件，若未使用 forwardRef，外層無法取得 ref。	在 HOC 中使用 forwardRef，並把 ref 正確傳遞給子元件 (ref as Ref<T>)。
memo 內部包 forwardRef 時忘記設定 displayName	開發工具的元件樹會顯示匿名函式，難以除錯。	為 forwardRef 或 memo 包裝的元件手動設定 displayName。
ref 與 key 同時傳入，導致 ref 變 null	React 會先處理 key 再處理 ref，若 key 改變會重新建立元件，舊的 ref 失效。	確保在列表渲染時 key 穩定，且不在同一個渲染循環內改變 key。

最佳實踐

1. 明確寫出所有泛型：forwardRef<DOMOrComponent, Props>，讓 IDE 完整提示。
2. 使用 React.RefAttributes<T>：在自訂元件的型別宣告時，直接擴充 RefAttributes，避免手動加入 ref?: React.Ref<T>。
3. 將 useImperativeHandle 的回傳物件抽成介面，保持一致性與可重用性。
4. 在測試中加入 ref 行為：使用 @testing-library/react 的 ref 測試，確保未因重構失去功能。
5. 在 forwardRef 內部避免使用 any：即使暫時無法確定型別，也可使用 unknown 再逐步收斂。

---

實際應用場景

1. 表單元件庫（如 Ant Design、Material‑UI）

這類 UI 套件的每個輸入元件都會提供 ref，讓使用者在表單提交前自行觸發驗證或聚焦。透過正確的 forwardRef 型別，開發者在自己的表單封裝層仍能保有原始元件的 ref 能力。

2. 動畫與測量（React‑Spring、Framer‑Motion）

許多動畫函式庫需要直接存取 DOM 節點以計算尺寸或座標。使用 forwardRef 包裝的自訂元件，使得外層動畫容器能直接取得子元件的實際 DOM。

3. 可重用的「彈出式」元件

例如自訂的 Modal、Tooltip，內部會在開啟時自動聚焦第一個可互動元素。外層只需要傳遞 ref 給 Modal，不必關心裡面的結構。

4. 高階元件 (HOC) 與裝飾器

在大型專案裡，常見「權限檢查」或「國際化」的 HOC。若原始元件支援 ref，HOC 必須保留這個特性，否則會破壞原本的聚焦或測量功能。

---

總結

• forwardRef 是 React 提供的 ref 轉發 機制，配合 TypeScript 必須明確指定 ref 的目標型別 (HTMLDivElement、自訂介面等) 與 props 型別。
• 使用 forwardRef<T, P>、React.RefAttributes<T>、useImperativeHandle，可以在 函式元件 中安全、清晰地暴露方法或 DOM。
• 在 HOC、memo、以及自訂 UI 套件 中保留 ref 能力，需要把 forwardRef 包裝在最外層，並適當地轉型 ref as Ref<T>。
• 常見陷阱包括忘記泛型、介面不匹配、HOC 丟失 ref 等；遵循「永遠寫出完整泛型」與「介面化回傳物件」的最佳實踐，可大幅降低錯誤風險。
• 實務上，forwardRef 為 表單、動畫、彈窗、以及高階元件 提供了必要的底層存取能力，是打造可重用、可測試、易維護的 React+TypeScript 程式碼的關鍵。

掌握了上述概念與範例後，你就能在日常開發中自信地使用 forwardRef，為 React 應用注入更強的型別安全與彈性。祝你寫程式快樂，專案順利 🚀。