Vue / 系统课时

封装类型化组合函数

封装类型化组合函数

组合函数的价值不只是“把逻辑搬出去”,而是把可复用状态、输入约束、返回契约与副作用清理一起封装。完成本节后,你可以写出调用端有类型提示、内部可维护、组件卸载后不会遗留监听器的 Vue 3 组合函数。

学习目标

  • 用 TypeScript 为组合函数的参数和返回值建立明确契约。
  • 用 ref、computed 与生命周期钩子封装可复用状态逻辑。
  • 为事件监听、定时器等副作用设计可靠的清理机制。

先设计调用契约

组合函数应先从“调用者需要什么”倒推接口,而不是把组件内部变量原样搬出去。参数负责表达外部输入,返回值只暴露调用者真正需要的状态与操作;能由内部状态推导出的值,优先返回只读的 ComputedRef,避免调用端绕过约束直接修改。

下面实现一个 useWindowSize:允许传入可选的防抖时间,返回窗口宽高以及是否达到桌面断点。它有浏览器事件监听,因此还必须在组件卸载时解绑。

ts
import { computed, onBeforeUnmount, onMounted, ref, type ComputedRef, type Ref } from 'vue'

interface UseWindowSizeOptions {
  debounceMs?: number
}

interface UseWindowSizeResult {
  width: Ref<number>
  height: Ref<number>
  isDesktop: ComputedRef<boolean>
}

export function useWindowSize(
  options: UseWindowSizeOptions = {}
): UseWindowSizeResult {
  const width = ref(0)
  const height = ref(0)
  let timer: number | undefined

  const update = () => {
    width.value = window.innerWidth
    height.value = window.innerHeight
  }

  const onResize = () => {
    if (!options.debounceMs) {
      update()
      return
    }

    if (timer) window.clearTimeout(timer)
    timer = window.setTimeout(update, options.debounceMs)
  }

  const isDesktop = computed(() => width.value >= 1024)

  onMounted(() => {
    update()
    window.addEventListener('resize', onResize)
  })

  onBeforeUnmount(() => {
    window.removeEventListener('resize', onResize)
    if (timer) window.clearTimeout(timer)
  })

  return { width, height, isDesktop }
}

预期结果

text
组件调用 useWindowSize({ debounceMs: 100 }) 后,可获得带类型提示的 width、height 和只读 isDesktop;组件卸载时 resize 监听器与待执行定时器会被清理。

在组件中消费组合函数

调用端只关心组合函数公开的契约,不需要知道监听器、定时器或断点判断如何实现。这样以后即使内部从 resize 事件改成 ResizeObserver,只要返回接口不变,组件通常无需修改。

vue
<script setup lang="ts">
import { useWindowSize } from './useWindowSize'

const { width, height, isDesktop } = useWindowSize({ debounceMs: 100 })
</script>

<template>
  <p>{{ width }} × {{ height }}</p>
  <p>{{ isDesktop ? '桌面布局' : '移动布局' }}</p>
</template>

预期结果

text
页面显示当前视口宽高;当宽度达到 1024 像素时显示“桌面布局”,否则显示“移动布局”。调整窗口后状态会自动更新。

类型设计要保留约束

不要为了“灵活”把参数写成 any,也不要无差别返回所有内部 ref。如果调用者只能读取某个派生状态,就返回 ComputedRef;如果参数存在有限选项,用联合类型或字面量类型表达;如果组合函数需要接收响应式输入,可明确使用 Ref<T>、MaybeRef<T> 或项目约定的泛型类型。

同时要避免把组件实例细节带入组合函数。组合函数应尽量依赖显式参数和 Vue 响应式原语,而不是偷偷读取某个页面组件的局部变量,这样才真正具备跨组件复用能力。

副作用必须成对清理

只要组合函数创建了浏览器监听器、定时器、订阅或第三方实例,就应在同一文件里定义对应的释放逻辑。创建与清理分散在不同组件中,会让复用者必须了解内部实现,最终失去封装意义。

对于依赖生命周期的组合函数,还要明确它只能在组件 setup 或其他具备活动组件实例的上下文中调用。若逻辑需要在组件外运行,应改为显式暴露 start、stop,而不是依赖 onMounted 和 onBeforeUnmount。

一个可靠的类型化组合函数,最终应同时做到三件事:调用接口清晰、响应式语义可预测、副作用生命周期完整。满足这三点后,它才适合作为企业项目中的长期复用单元。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装类型化组合函数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通