Vue.js 高阶组件封装与自定义 Hook 实战技巧

在 Vue.js 应用开发中，跨组件复用状态与行为通常有两种途径：基于组件包装的高阶组件（HOC）与基于 Composition API 的自定义 Hook（组合式函数）。本文直接梳理这两种模式的核心封装范式、关键边界问题（属性透传、插槽保留、生命周期注销与类型推导）以及工程落地中的选型准则，为日常业务开发与公共库构建提供切实可行的操作参考。

图 0：Vue.js 高阶组件 (HOC) 与自定义 Hook (Composable) 架构概览

一、Vue 高阶组件（HOC）的核心原理与通用封装范式

高阶组件是一个接收组件作为参数、并返回一个新组件的纯函数。在 React 体系中，HOC 曾是逻辑复用的主要手段；而在 Vue 中，由于其独有的单文件组件（SFC）模板编译机制和依赖注入设计，HOC 的实现必须借助底层渲染函数 h() 或 JSX。

在 Vue 3 体系中，封装高阶组件需要重点处理四个核心边界：属性透传、插槽转接、方法与 Ref 暴露以及组件元信息（displayName）保全。如果忽略这些细节，包装后的组件极易丢失外部传入的属性或触发父子组件插槽失效。

图 1：Vue 高阶组件 (HOC) 包装与属性/插槽/事件流转架构

1.1 标准高阶组件封装模板（以权限拦截为例）

以下代码演示一个典型的业务权限高阶组件 withPermission。该组件拦截未授权用户的访问，若校验通过则将所有 props、attrs 和 slots 完整传递给目标组件，并对外透传组件内部暴露的实例方法。

// withPermission.ts
import { defineComponent, h, ref, type Component, type VNode } from 'vue';

export interface WithPermissionOptions {
  role: string;
  fallbackText?: string;
}

export function withPermission<T extends Component>(
  WrappedComponent: T,
  options: WithPermissionOptions
) {
  return defineComponent({
    name: `WithPermission(${(WrappedComponent as any).name || 'Anonymous'}`,
    // 关键点 1：关闭自动继承，由渲染函数显式精细控制
    inheritAttrs: false,
    setup(props, { attrs, slots, expose }) {
      const innerRef = ref<any>(null);

      // 模拟权限状态获取，实际工程中可接入全局 pinia store
      const hasPermission = checkUserRole(options.role);

      // 关键点 2：转发内层组件暴露的方法与属性，保证父级 ref 正常调用
      expose(
        new Proxy({}, {
          get(_, prop: string) {
            return innerRef.value?.[prop];
          }
        })
      );

      return (): VNode => {
        if (!hasPermission) {
          return h('div', { class: 'permission-denied-fallback' }, [
            options.fallbackText || '当前账号无权访问该组件内容'
          ]);
        }

        // 关键点 3：合并透传 props 与 attrs，挂载 innerRef，完整交付 slots
        return h(
          WrappedComponent,
          {
            ...attrs,
            ref: innerRef,
          },
          slots
        );
      };
    }
  });
}

function checkUserRole(role: string): boolean {
  const currentRole = localStorage.getItem('user_role') || 'guest';
  return currentRole === role || currentRole === 'admin';
}

二、自定义 Hook（Composable）的设计规范与进阶技巧

自定义 Hook 是 Vue 3 Composition API 下最推崇的逻辑复用形式。它通过将相关的响应式状态（ref、reactive）、计算属性以及生命周期钩子集中封装在一个普通 JavaScript 函数内，以清晰的输入输出契约提供服务。

相较于高阶组件，自定义 Hook 的调用完全发生在组件的 setup() 内部，不产生额外的组件层级，能够清晰追踪数据来源，并且对 TypeScript 具有天然的无损推导支持。

图 2：自定义 Hook (Composable) 响应式驱动与生命周期解耦模型

2.1 自定义 Hook 编写的三项硬性工程准则

• 入参弹性化（Flexible Arguments）：使用 Vue 3.3+ 引入的 toValue（或 unref）处理传入参数。允许调用方传入普通原始值、Ref 响应式变量或返回值的 getter 函数，从而适应静态与动态多变场景。
• 解构保活（Destructure-friendly Output）：返回值必须是包含多个 Ref 的普通对象，而不是直接返回一个 reactive 对象。直接对 reactive 解构会导致响应性丢失；返回普通对象包装的 ref 则支持调用方任意解构并安全重命名。
• 生命周期与副作用自治（Self-disposing）：如果 Hook 内部注册了全局 DOM 事件、定时器或未完成的异步网络请求，必须利用 onScopeDispose 或 onUnmounted 进行清理，保证其挂载的 EffectScope 销毁时无遗留泄漏。

2.2 实战范式：异步数据请求与竞态取消 Hook

以下代码实现通用的 useRequest 组合式函数，支持动态 URL 监听、请求防重取消与自动清理。

// useRequest.ts
import {
  shallowRef,
  ref,
  watchEffect,
  toValue,
  onScopeDispose,
  type MaybeRefOrGetter,
  type Ref
} from 'vue';

export interface UseRequestOptions<T> {
  immediate?: boolean;
  initialData?: T;
}

export interface UseRequestReturn<T> {
  data: Ref<T | null>;
  loading: Ref<boolean>;
  error: Ref<Error | null>;
  execute: () => Promise<void>;
}

export function useRequest<T = any>(
  urlSource: MaybeRefOrGetter<string>,
  options: UseRequestOptions<T> = {}
): UseRequestReturn<T> {
  const { immediate = true, initialData = null } = options;

  // 使用 shallowRef 避免大对象深度递归代理带来的初始化性能负担
  const data = shallowRef<T | null>(initialData);
  const loading = ref<boolean>(false);
  const error = shallowRef<Error | null>(null);

  let currentController: AbortController | null = null;

  const execute = async () => {
    // 竞态防护：如果上一轮请求尚未结束，立即中断
    if (currentController) {
      currentController.abort();
    }

    currentController = new AbortController();
    loading.value = true;
    error.value = null;

    const url = toValue(urlSource);

    try {
      const response = await fetch(url, {
        signal: currentController.signal,
      });
      if (!response.ok) {
        throw new Error(`HTTP 异常: ${response.status}`);
      }
      data.value = await response.json();
    } catch (err: any) {
      if (err.name !== 'AbortError') {
        error.value = err instanceof Error ? err : new Error(String(err));
      }
    } finally {
      loading.value = false;
    }
  };

  if (immediate) {
    // 响应源改变时自动重发请求
    watchEffect(() => {
      // 触发 toValue(urlSource) 依赖收集
      if (toValue(urlSource)) {
        execute();
      }
    });
  }

  // 组件卸载或作用域销毁时，自动中断挂起请求
  onScopeDispose(() => {
    if (currentController) {
      currentController.abort();
      currentController = null;
    }
  });

  return {
    data,
    loading,
    error,
    execute,
  };
}

三、实战操作步骤：从零抽离与工程落地流程

当业务代码中出现多处相似逻辑时，切勿盲目创建包装组件。按照规范的工程落地流程，可将重构风险降至最低。

图 3：跨组件逻辑封装与落地的四步工程化操作流程

1. 步骤一：识别复用诉求的核心边界。仔细分析需要抽离的代码是否包含 DOM 渲染结构：
   • 若只涉及纯数据计算、状态跟踪、网络请求、浏览器原生 API（如 ResizeObserver、IntersectionObserver），必须选择自定义 Hook；
   • 若需要从外部完全阻断或重写目标组件的渲染输出（如统一包裹全局骨架屏、注入全局固定右键菜单或对组件做无侵入埋点劫持），则进入高阶组件方案。
2. 步骤二：明确输入参数与输出契约。 编写严格的 TypeScript 类型接口。对于 Hook，确定哪些参数需要支持 MaybeRefOrGetter；对于 HOC，明确包装器向内层注入的新增属性名称，避免与基础组件本身的 prop 命名产生覆盖碰撞。
3. 步骤三：实现防御机制与清理回收。 针对 Hook，检查所有具有生命周期的对象（事件监听、setTimeout、WebSocket 连接、网络请求），统一在 onScopeDispose 中完成反向注销；针对 HOC，必须关闭 inheritAttrs 并实现组件实例方法的代理暴露。
4. 步骤四：在业务组件中集成验证。 编写单元测试与场景集成用例，验证以下关键状态：组件动态销毁时无后台挂起任务、解构后响应性能否正常触发视图更新、在 Vue DevTools 中的组件树层级是否符合预期。

四、选型决策与核心避坑指南

尽管高阶组件与自定义 Hook 均能实现代码逻辑复用，但二者在设计哲学、维护成本及调试体验上存在明显差异。下表对比了两者在关键工程维度的表现：

图 4：HOC 与自定义 Hook 技术选型矩阵与核心指标总结

4.1 核心踩坑点与排查对策

• 陷阱 1：在 Hook 外部或异步回调内部调用生命周期钩子。
  onMounted、onScopeDispose 等生命周期函数必须在 setup() 的同步执行流程中执行。如果在 setTimeout 或 await 之后才调用这些钩子，Vue 将无法捕获当前组件实例上下文，导致控制台抛出 [Vue warn]: onMounted is called when there is no active component instance to be associated with. 的错误。
• 陷阱 2：HOC 导致的原生事件重复触发。
  如果未设置 inheritAttrs: false，Vue 会默认将所有未声明的 attrs 绑定到根节点上；此时若渲染函数 h(WrappedComponent, attrs) 再次显式绑定 attrs，将导致子组件根元素接收两份事件监听，用户点击一次按钮会触发两次事件回调。
• 陷阱 3：在 Hook 中直接返回 reactive 导致解构失活。
  若写成 return reactive({ count, loading })，调用方执行 const { count } = useHook() 时将获取普通基本类型值，从此与 Hook 内部状态彻底断开响应联系。务必始终返回纯对象包裹的 ref 实例集合（或使用 toRefs 转换后再返回）。

综上所述，在现代 Vue 3 架构演进中，自定义 Hook 是日常业务逻辑、状态流转和异步控制的首选复用路径；而高阶组件则应当定位于视图级别的外层防御包装器，二者分工明确，结合使用能显著提升前端工程代码的清晰度与可测试性。