Skip to content
FEE
Frontend Engineering Essentials
Mid Level
Tone-Polished· 2026-07

[FEE-505] 高階元件與橫切邏輯 ​

INFO

Higher-Order Component(HOC)是一個接受元件並回傳新元件的函式,新元件帶有額外注入的行為。在 hooks 時代,custom hook 能涵蓋大多數橫切關注點。對於非渲染類的關注點(分析事件、權限檢查、資料抓取),團隊 SHOULD 優先採用 custom hook。當關注點需要包裹渲染輸出時(例如身分驗證重新導向、注入版面元素、portal 渲染),團隊 MUST 使用 HOC。任何包裹 DOM 元素的 HOC MUST 使用 React.forwardRef 以保留 ref 轉發。

介紹 ​

隨著 React 應用規模擴大,某些行為會在不相關的元件之間反覆出現:渲染頁面前的身分驗證檢查、使用者查看某個區塊時的分析事件觸發、主題注入、權限閘道、錯誤邊界、功能旗標切換。這些關注點橫向地切穿整棵元件樹,並不遵循任何父子關係。挑戰在於只需實作一次就能一致地套用每個關注點,不重複邏輯,也不把不相關的關注點糾纏進個別元件,同時讓元件樹對開發者每天倚賴的除錯工具保持清晰。

Higher-Order Component 是 React 16.8 之前用來解決這個問題的慣用方案。這個模式本身早於 React。它是函數式程式設計中高階函式概念的直接應用,適配到元件模型上。HOC 是一個接受元件作為引數並回傳新元件的函式。回傳的元件包裹原始元件,在包裹元件渲染前後加入行為,或完全阻止其渲染。Redux(connect)、React Router(withRouter)和 MobX(observer)等函式庫都用這個模式將 store 訂閱、路由 context 和響應式追蹤注入應用元件,而使用者不必撰寫任何串接程式碼。

React 16.8 引入 hooks 後,計算方式有了顯著改變。Custom hook 能在任意數量的 function component 之間提取並共享有狀態邏輯,而不改變元件樹。對於不涉及 DOM 結構的橫切關注點(讀取認證狀態、觸發分析事件、訂閱 store),custom hook 幾乎總是比 HOC 更簡單:需要的樣板程式碼更少、不在樹中產生額外的包裹元素,並且在擁有它的元件中以單一具名呼叫出現,而不是以 React DevTools 中的匿名包裹層呈現。然而,hook 並非萬能。hook 無法包裹其宿主元件的渲染輸出。它不能插入一個 <Navigate> 來取代元件、注入一個周圍的 <Portal>,也不能攔截 children。對於任何真正需要控制或修改渲染結果的關注點,HOC 仍是正確的工具。

理解何時使用哪種模式,並認識到兩者並不互斥,是本文所要培養的實務技能。真實的程式碼庫通常同時包含兩者:一個在路由層守護整條路由的 withAuth HOC,以及一個在個別元件內記錄使用者互動的 useAnalytics hook。目標是讓工具符合結構需求,而不是在虛假的論戰中選邊站。

另外值得理解一個常見的混淆點:HOC 和 hook 並不是在同一抽象層次上的替代方案。HOC 工廠函式本身在其回傳的元件內部呼叫 hook。上方的 withAuth 呼叫 useAuth 並有條件地回傳 <Navigate>。HOC 是控制渲染輸出的邊界;hook 是它用來存取橫切狀態的機制。這種組合(hook 驅動邏輯,HOC 塑造渲染邊界)是在 hooks 時代撰寫 HOC 的正確思維模型。一個完全不呼叫 hook 的 HOC,很可能是透過 props drilling、context 讀取或舊式生命週期方法來實作其橫切關注點,而這些方式都不如 hook 符合人體工學。

設計思考 ​

核心的架構決策,HOC 還是 hook,清楚地對應到一個問題:橫切關注點需要影響 DOM 中顯示的內容,還是只影響元件邏輯內部發生的事?如果答案是前者,HOC 是正確的抽象層次。如果答案是後者,hook 更簡單、更可組合、更透明。

考慮身分驗證守護。一個程式碼庫通常有兩種結構上不同的認證需求。第一種:阻止未認證使用者看到受保護的頁面,甚至不讓頁面骨架在重新導向觸發前閃現。這是渲染層面的關注點。元件根本不應該渲染;一個重新導向元素應出現在它的位置。HOC 是天然的選擇:它在渲染層進行攔截,並在包裹元件執行之前回傳 <Navigate>。第二種:在一個已經渲染的元件內部,在觸發動作之前檢查使用者是否擁有特定權限。這是邏輯層面的關注點。不需要任何包裹;一個回傳 isAuthorized 布林值的 hook 可以直接整合進元件的事件處理器,而不觸碰 DOM 結構。

分析是另一個能說明問題的案例。如果需要在特定元件掛載時觸發一個 view 事件,custom hook 裡的 useEffect 只需三行程式碼,不需要任何包裹。如果需要確保對整個子樹的每一次互動(包括動態渲染 children 上的點擊)都被追蹤,一個包裹子樹並附加委派事件監聽器的 HOC 可能更合適。關注點在 DOM 中的範圍決定了正確的抽象方式。

第三個維度是 class component 相容性。Hook 在 class component 中不可用。一個仍有 class component 的程式碼庫(無論是尚未遷移的舊有程式碼,還是你無法控制的第三方元件)都需要 HOC 來注入橫切行為。如果你的團隊完全使用 function component,這個維度就消失了。

決策表:

情境HOCCustom Hook
必須在 DOM 中注入包裹元素是否
橫切渲染邏輯(portals、邊界)是否
橫切非渲染邏輯(分析、權限檢查)皆可優先選 hook
僅 function component,hooks 可用優先選 hook是
必須攔截或轉換 children是否
需要 class component 相容性是否(hooks 不能在 class component 中使用)

這個表格突顯了「皆可」那一行確實存在真正的重疊。對於 function component 中的非渲染關注點,兩種工具都可以運作。決勝點是可組合性和 DevTools 可讀性:hook 以名稱出現在元件自身的程式碼中、可以輕鬆作為函式測試,且不在 React 元素樹中增加任何東西。HOC 則增加一個包裹層。在其他條件相同的情況下,hook 是成本更低的選項。

在評估一個提案中的 HOC 時,一個有用的思考練習是:想像改以 hook 實作這個關注點。如果 hook 的實作需要使用它的每個元件自行複製關注點的任何渲染邏輯(一個重新導向 JSX 元素、一個錯誤邊界的 fallback、一個 portal 掛載點),HOC 勝出,因為 HOC 將那段渲染邏輯集中在一個地方。如果 hook 的實作是自給自足的,且不需要元件新增任何渲染邏輯,hook 勝出。

最後,HOC 非常適合框架整合點,在那裡元件包裹是慣用的 API 形式。React Router 的 <Route> 元素使用 render props,但許多路由層級的關注點(權限、分析、捲動恢復)以 HOC 形式包裹路由元件,比逐路由設定更乾淨。類似地,測試函式庫通常提供 HOC 風格的包裹器,用於在單元測試中注入測試 provider(withStoreProvider、withThemeProvider)。在這些情境中,HOC 是框架或工具所預期的 API 形狀,而不是你在做的設計選擇。

React 19 與 ref 作為普通 prop 的變更。 React 19 移除了 function component 必須使用 React.forwardRef 的要求:function component 可以直接在 props 解構中宣告 ref,React 會正確處理它。這對純 React 19 程式碼庫的 HOC 撰寫體驗有所簡化。回傳的包裹函式可以直接在 props 中接受 ref,不再需要外包一層 React.forwardRef。然而,這項變更只是改變了機制;轉發 ref 的義務仍然存在。在 React 19 中忽略 ref 的 HOC,對任何持有包裹元件 ref 的父元件來說仍然是損壞的。實務上,大多數生產環境的 HOC 在 React 18/19 過渡期間仍需保持 React.forwardRef 相容性,而任何包裹 class component 的 HOC 則必須繼續使用 React.forwardRef,因為 class component 不接受 ref 作為普通 prop。ref 轉發契約是語意上的義務,而非 API 細節。滿足它的機制會隨版本改變,但義務本身不會改變。

生產函式庫中的真實 HOC 範例。 HOC 模式的持久生命力,體現在它在基礎 React 函式庫中的持續使用。React Redux 的 connect(mapStateToProps, mapDispatchToProps)(Component) 是最經典的 HOC:它訂閱 Redux store、選取元件所需的 state 切片,並以 props 形式注入。元件本身從不直接從 store 匯入。Apollo Client 的 withApollo(Component) 將 Apollo client 實例作為 prop 注入,讓 class component 能夠在不使用 render-prop 或 hook 的情況下命令式地執行查詢。React Router(v6 以前)的 withRouter(Component) 則注入 history、location 和 match props,使樹中的任何元件都能存取路由 context,而不需要直接消費 <Route>。這些實作都遵循相同的結構契約:一個工廠函式、一個透過 hook(或訂閱)從 context 讀取狀態的包裹器、注入衍生 props,以及明確的 displayName 和 forwardRef 支援。

最佳實踐 ​

無條件設定 displayName。 每個 HOC 工廠函式在回傳之前 MUST 在回傳的元件上設定 displayName。慣例是 `withHocName(${WrappedComponent.displayName ?? WrappedComponent.name ?? 'Component'})`。省略這個設定會在 React DevTools 中產生 Anonymous 或 ForwardRef 條目,當套用多個 HOC 時彼此無從區分。可讀的 DevTools 樹能直接縮短診斷元件層級 bug 的時間,尤其是在元件樹很深的情況下。

使用 React.forwardRef 轉發 ref。 任何渲染包裹元件的 HOC MUST 將回傳的元件包裹在 React.forwardRef 中。透過 ref props 將 ref 傳遞給包裹元件。這維持了透明性契約:從父元件的角度來看,持有 withAuth(Dashboard) 的 ref 應與持有 Dashboard 的 ref 完全相同。若未轉發,ref.current 對 function component 會是 null,對 class component 則會解析到 HOC 包裹層實例。兩者都不是父元件所預期的。

關於 React 19 的注意事項:在 React 19 中,function component 可以將 ref 作為普通 props 接受,無需 React.forwardRef。然而,需要同時支援 React 18 和 React 19 環境、或包裹 class component 的 HOC 包裹層,仍然受益於明確的 React.forwardRef 模式以確保相容性和清晰度。

避免 props 名稱衝突。 HOC 向包裹元件注入 props。如果注入的 props 名稱(例如 user、theme、data)與使用者試圖傳遞的 props 名稱衝突,其中一個會在沒有任何警告的情況下被另一個覆蓋。當 HOC 作者和元件使用者是不同的人時,這在大型程式碼庫中尤其隱蔽。最安全的緩解措施是為 HOC 注入的 props 使用非通用名稱(auth、injectedUser 等),或透過 TypeScript 明確記錄注入的 props 名稱並強制無重疊:使用 Omit<P, 'user'> 作為外部 props 類型,使消費者無法意外傳遞會衝突的 props。

不要修改包裹元件。 直接修改 WrappedComponent.prototype 或在 WrappedComponent 上附加屬性是很誘人的做法。這會在該元件的所有使用之間產生共享的可變狀態,包括不涉及 HOC 的使用。始終在 HOC 工廠中建立一個新元件並回傳它。永遠不要修改原件。

複製靜態方法。 當 HOC 包裹一個元件時,回傳的包裹器不會攜帶原始元件的靜態方法。如果 Dashboard 有一個靜態的 Dashboard.requiresAuth 旗標或 Dashboard.getLayout 函式,那些靜態成員在 withAuth(Dashboard) 上將不存在,除非明確複製。使用 hoist-non-react-statics 函式庫,或手動複製你需要的方法:AuthGuard.getLayout = WrappedComponent.getLayout。

使用 hoist-non-react-statics 提升靜態方法。 當 HOC 包裹一個元件時,工廠回傳的包裹器函式不會繼承原始元件上定義的任何靜態方法。這是一個靜默的問題:withAuth(Dashboard) 上不會有 Dashboard.getLayout、靜態設定的 Dashboard.defaultProps,或任何其他你定義的靜態成員。在 Next.js 中,失去 getLayout 會導致頁面在沒有預期版面包裹器的情況下渲染。在元件函式庫中,失去靜態的 componentType 鑑別器會破壞消費端程式碼中的 switch-on-type 邏輯。hoist-non-react-statics 套件自動化了這個複製過程:在回傳包裹器之前呼叫 hoistNonReactStatics(Wrapper, WrappedComponent),所有非 React 靜態成員(除了 displayName、defaultProps、propTypes、contextType 以及其他 React 保留鍵之外的所有靜態成員)都會被複製。如果你不想增加依賴,就針對應用程式實際使用的屬性明確複製靜態成員,刻意為之而非偶然遺漏。每個新 HOC 的程式碼審查清單項目應包含:「包裹元件定義了哪些靜態成員?包裹器上是否都有?」

將 HOC 工廠與其實作的關注點放在一起。 withAuth HOC 應放在 src/hoc/withAuth.tsx 或靠近 auth 模組的地方,而不是散落在各功能資料夾中。HOC 工廠是基礎設施。把它們像工具函式一樣對待:集中管理、版本化,並從單一位置匯出。

當堆疊無可避免時,使用 pipe 或 compose 工具組合 HOC 工廠。 如果必須對單一元件套用兩個 HOC,優先使用明確的 compose 呼叫,而非巢狀呼叫。巢狀呼叫由內而外閱讀(withAuth(withAnalytics(Dashboard))),若不仔細閱讀,執行順序容易產生歧義。compose(withAuth, withAnalytics)(Dashboard) 則以從左到右(或從右到左,取決於 compose 的實作)閱讀,讓優先順序變得明確。大多數工具函式庫(lodash、ramda)提供 compose 或 flowRight 輔助函式;或者,一個專案本地的雙引數 compose 只需六行 TypeScript,就能完全消除歧義。即使使用 compose,原則章節中的兩個 HOC 上限仍然適用。compose 改善了可讀性,但不會減少樹中包裹元素的數量。

獨立測試 HOC。 HOC 工廠是一個函式。可以透過傳入一個 mock 元件並斷言在不同 props 和 context 條件下回傳的元件渲染什麼來測試它。不要只依賴同時測試 HOC 和包裹元件的整合測試。獨立隔離 HOC 邏輯使認證重新導向行為、載入狀態渲染和 props 轉發可以獨立驗證。

必須(MUST)對其元件引數是純函式。 給定相同的 WrappedComponent,每次呼叫都必須回傳帶有相同增強行為的元件。禁止修改 WrappedComponent 的原型或 defaultProps。這樣做會在同一個基底元件被傳入多個 HOC 時,引發不可預期的行為。

禁止(MUST NOT)在單一元件上堆疊超過兩個 HOC。 每一層都在 React 樹中增加一個包裹元素,讓 DevTools 的雜訊成倍增加,並建立 props 穿透通道。當需要套用超過兩個橫切關注點時,應提取單一多關注點包裹器,或將這些關注點重構為元件直接呼叫的 hook。

應該(SHOULD)對橫切的非渲染關注點優先採用 custom hook。 分析、認證狀態讀取、權限檢查、資料預抓取和 store 訂閱不需要包裹元素,不在 React DevTools 中產生匿名條目,且組合時不帶 HOC 堆疊的 props 穿透代價。當橫切關注點需要包裹或替換渲染輸出時,必須(MUST)使用 HOC。

為 HOC 工廠使用一致的命名慣例。 with 前綴是普遍認可的慣例:withAuth、withTheme、withAnalytics、withFeatureFlag。未以 with 為前綴的 HOC 會讓讀者感到困惑,因為他們預期 with* 表示 HOC 工廠,use* 表示 hook。在程式碼庫中混用慣例(protectedComponent、analyticsDecorated、themed)會迫使讀者檢查每個未知函式的簽名,以確定它是 HOC、工具函式還是 hook。在 ESLint 規則或程式碼審查指南中強制執行 with 前綴,並在整個程式碼庫中保持一致。

圖解 ​

HOC 方式在 React 元素樹層級運作。包裹元件是樹中的一個節點,關於渲染什麼的決策在該節點內做出,在包裹元件實例化之前。Hook 方式在元件自身的渲染函式內部運作。元件已在樹中,hook 在渲染後觸發命令式的導航 effect。HOC 可以阻止元件渲染;hook 無法阻止其宿主元件渲染,只能阻止顯示有意義的 UI 或在渲染後觸發導航。

範例 ​

withAuth HOC:完整實作 ​

以下 HOC 為任何元件包裹身分驗證守護。如果使用者未通過認證,HOC 會渲染重新導向而非包裹元件。使用 React.forwardRef 使 HOC 的消費者持有的 ref 能正確解析到包裹元件。

tsx
// src/hoc/withAuth.tsx
import React from 'react';
import { Navigate } from 'react-router-dom';
import { useAuth } from '../hooks/useAuth';

export function withAuth<P extends object>(
  WrappedComponent: React.ComponentType<P>,
  redirectTo = '/login'
) {
  const AuthGuard = React.forwardRef<unknown, P>((props, ref) => {
    const { isAuthenticated, isLoading } = useAuth();

    if (isLoading) return <div aria-busy="true" aria-label="Checking auth..." />;
    if (!isAuthenticated) return <Navigate to={redirectTo} replace />;

    // TypeScript:因為 forwardRef 的泛型是 unknown,需要型別轉換
    const Component = WrappedComponent as React.ComponentType<P & { ref?: unknown }>;
    return <Component {...props} ref={ref} />;
  });

  // 在 React DevTools 中保留元件名稱
  AuthGuard.displayName = `withAuth(${
    WrappedComponent.displayName ?? WrappedComponent.name ?? 'Component'
  })`;

  return AuthGuard;
}

// 使用方式
const ProtectedDashboard = withAuth(Dashboard);
const ProtectedSettings = withAuth(Settings, '/auth/login');

逐一檢視關鍵決策:

  • React.forwardRef:HOC 回傳一個 forwardRef 包裹的元件。任何持有 ProtectedDashboard ref 的父元件,其 ref 都會透明地轉發到 Dashboard。沒有這個,ref 會是 null 或指向包裹層。
  • 由 HOC 渲染的載入狀態:isLoading 守護在 HOC 內部而非包裹元件。這意味著 Dashboard 從不需要處理「認證載入中」的情況。如果它渲染,它總是收到完全解析的認證狀態。
  • Navigate 回傳:HOC 可以回傳一個完全不同的元素樹(<Navigate>)來取代包裹元件。這在 Dashboard 內部的 hook 中在結構上是不可能做到的:元件已經在渲染了。
  • displayName:明確設定。在 React DevTools 中,元件樹將顯示 withAuth(Dashboard) 而非 ForwardRef 或 Anonymous。
  • TypeScript 型別轉換:ref 的 forwardRef 泛型型別是 unknown,因為實際的 ref 類型取決於 P。更嚴格的型別需要一個額外的 ref 類型泛型參數。型別轉換是孤立的,不影響執行時行為。

useAuthGuard hook:非渲染情境的等效實作 ​

當認證關注點是「如果未認證就以命令式重新導向使用者,但不阻止元件渲染載入狀態」,hook 更簡單且不產生包裹元素。

tsx
// src/hooks/useAuthGuard.ts — 非渲染情境的 hook 等效實作
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { useAuth } from './useAuth';

export function useAuthGuard(redirectTo = '/login') {
  const { isAuthenticated, isLoading } = useAuth();
  const navigate = useNavigate();

  useEffect(() => {
    if (!isLoading && !isAuthenticated) {
      navigate(redirectTo, { replace: true });
    }
  }, [isAuthenticated, isLoading, navigate, redirectTo]);

  return { isLoading };
}

// 使用方式——不需要包裹元素,不需要 forwardRef
function Dashboard() {
  const { isLoading } = useAuthGuard();
  if (isLoading) return <Spinner />;
  return <DashboardContent />;
}

結構上的差異立刻顯而易見:Dashboard 在 React DevTools 中以單一節點呈現。沒有添加任何包裹層。hook 在渲染後觸發導航 effect,而非阻止渲染。當元件無論如何都要渲染一個載入 spinner 時,這是合適的:多餘的渲染週期是無害的。當元件的渲染在認證檢查解析之前有可見的副作用,或當元件的渲染本身代價高昂且不應該對未認證使用者執行時,這就不合適了。

HOC 堆疊反模式與合併替代方案 ​

tsx
// 反模式:三個 HOC 層產生三個包裹元素和三個 displayName
// 條目在 DevTools 中,而且在第 N 層新增的任何 props 都必須穿越第 N-1 到 0 層
const ProtectedDashboard = withAuth(
  withAnalytics(
    withTheme(Dashboard)
  )
);

// 優先替代方案 A:單一多關注點 HOC
function withPageConcerns<P extends object>(WrappedComponent: React.ComponentType<P>) {
  const PageWrapper = React.forwardRef<unknown, P>((props, ref) => {
    const { isAuthenticated, isLoading } = useAuth();
    const navigate = useNavigate();
    const theme = useTheme();

    useAnalytics({ componentName: WrappedComponent.displayName ?? WrappedComponent.name });

    useEffect(() => {
      if (!isLoading && !isAuthenticated) navigate('/login', { replace: true });
    }, [isAuthenticated, isLoading, navigate]);

    if (isLoading) return <PageSkeleton />;

    const Component = WrappedComponent as React.ComponentType<P & { ref?: unknown }>;
    return (
      <ThemeContext.Provider value={theme}>
        <Component {...props} ref={ref} />
      </ThemeContext.Provider>
    );
  });

  PageWrapper.displayName = `withPageConcerns(${
    WrappedComponent.displayName ?? WrappedComponent.name ?? 'Component'
  })`;

  return PageWrapper;
}

// 優先替代方案 B:在元件內部將關注點組合為 hook
function Dashboard() {
  const { isLoading } = useAuthGuard();
  useAnalytics({ componentName: 'Dashboard' });
  const theme = useTheme();

  if (isLoading) return <PageSkeleton />;
  return <DashboardContent theme={theme} />;
}

替代方案 B 通常是最清晰的:元件的原始碼讀起來就像它所套用的關注點的一份清單,不帶包裹巢狀、DevTools 雜訊或 props 穿透。替代方案 A 適合當關注點確實必須包裹渲染輸出(本例中的主題 context 注入必須圍繞元件,這是渲染層面的需求),且在避免堆疊的同時進行合併仍然是值得的時候。

TypeScript 中的 HOC 型別模式 ​

HOC 型別是 React 程式碼庫中最常被問到的 TypeScript 主題之一,因為要保留完整型別推斷所需的泛型串接並不直觀。三種模式涵蓋了大多數真實世界的情境。

模式一:從外部型別中排除注入的 props。 最常見的 HOC 會注入一個或多個 props,而消費者不應該需要提供它們。對外部元件的 props 型別使用 Omit:

tsx
type WithAuthProps = { currentUser: User };

function withAuth<P extends WithAuthProps>(WrappedComponent: React.ComponentType<P>) {
  const AuthGuard = React.forwardRef<unknown, Omit<P, keyof WithAuthProps>>(
    (props, ref) => {
      const { currentUser } = useAuth();
      const Component = WrappedComponent as React.ComponentType<P & { ref?: unknown }>;
      return <Component {...(props as P)} currentUser={currentUser} ref={ref} />;
    }
  );
  AuthGuard.displayName = `withAuth(${WrappedComponent.displayName ?? WrappedComponent.name ?? 'Component'})`;
  return AuthGuard;
}

外部元件接受 Omit<P, keyof WithAuthProps>,這意味著消費者無法(也不需要)傳遞 currentUser。TypeScript 會在呼叫端強制執行這一點。

模式二:無注入 props 的透傳 HOC。 某些 HOC 在不注入 props 的情況下添加行為(例如在掛載時觸發分析事件)。外部型別與 P 相同:

tsx
function withAnalytics<P extends object>(WrappedComponent: React.ComponentType<P>) {
  const Tracked = React.forwardRef<unknown, P>((props, ref) => {
    useAnalytics({ componentName: WrappedComponent.displayName ?? WrappedComponent.name });
    const Component = WrappedComponent as React.ComponentType<P & { ref?: unknown }>;
    return <Component {...props} ref={ref} />;
  });
  Tracked.displayName = `withAnalytics(${WrappedComponent.displayName ?? WrappedComponent.name ?? 'Component'})`;
  return Tracked;
}

模式三:推斷 ref 型別。 當 ref 型別很重要時(例如消費者持有指向 DOM 元素的 ref),為 ref 元素型別新增第二個泛型參數:

tsx
function withAuth<TRef, P extends object>(WrappedComponent: React.ComponentType<P>) {
  return React.forwardRef<TRef, P>((props, ref) => {
    // ...
  });
}
const ProtectedInput = withAuth<HTMLInputElement, InputProps>(Input);

這更為冗長,但能讓消費者得到正確型別的 ref.current: HTMLInputElement | null。

常見錯誤 ​

Props 名稱衝突。 向包裹元件注入 user props 的 HOC,會在沒有警告的情況下靜默地覆蓋消費者試圖傳遞的任何 user props。在 HOC 作者和元件消費者是不同的人的大型程式碼庫中,這尤其隱蔽。最安全的緩解措施是對 HOC 注入的 props 使用非通用名稱(auth、injectedUser 等),或使用 TypeScript 明確記錄注入的 props 名稱並強制無重疊:將 Omit<P, 'user'> 作為外部 props 類型,使消費者無法意外傳遞會衝突的 props。

在渲染函式或元件內部建立 HOC。 在元件的渲染函式內部呼叫 HOC 工廠,會在每個渲染週期建立一個新的元件類型。React 將每個新類型視為完全不同的元件,在每次父元件渲染時卸載並重新掛載包裹元件。這完全破壞了記憶化,並摧毀了包裹元件內的本地 state。HOC 工廠 MUST 在模組作用域中呼叫,在任何元件或 hook 之外。

tsx
// 錯誤——每次渲染都建立新的元件類型
function Page() {
  const ProtectedDashboard = withAuth(Dashboard); // 每次渲染都是新類型!
  return <ProtectedDashboard />;
}

// 正確——在模組作用域呼叫一次
const ProtectedDashboard = withAuth(Dashboard);
function Page() {
  return <ProtectedDashboard />;
}

忘記複製靜態方法。 當 Dashboard 有一個靜態屬性(Dashboard.getLayout、Dashboard.fetchData、Dashboard.config),這些屬性在 withAuth(Dashboard) 上是不存在的。一個使用 getLayout 的 Next.js 頁面元件,在被 HOC 包裹時會悄悄地失去其版面。檢查包裹元件匯出了哪些靜態屬性,並明確複製它們,或使用 hoist-non-react-statics 自動複製所有非 React 靜態屬性。

從包裹 function component 的 HOC 中回傳 class component。 一些較舊的 HOC 實作在內部使用基於 class 的包裹器,即使包裹的元件是 function component 也是如此。這種混合方式阻止了包裹元件在 HOC 主體內使用 hooks(因為 hooks 不能在 class 的 render 方法中執行)。現代 HOC MUST 使用 function component(通常透過 React.forwardRef)作為其內部包裹器,以保持與 HOC 邏輯內部所呼叫 hook 的相容性,例如上方範例中的 useAuth、useNavigate 和 useEffect。

忽略深層包裹對 React 協調的效能影響。 每個 HOC 包裹層在協調樹中都是一個真實的 React 元素。在典型規模下,每個路由層級元件有兩三個包裹層並不構成可測量的問題。但在一個渲染數百行的大型資料密集表格中,每行都被 HOC 包裹以進行逐行權限檢查,會在每次更新時產生數百個額外的協調節點。在效能敏感的渲染路徑中,優先選擇 hook 形式:它不在元素樹中增加任何節點,且沒有協調開銷。

相關 FEE ​

參考資料 ​