Vue / 系统课时
封装类型化组合函数
封装类型化组合函数
组合函数的价值不只是“把逻辑搬出去”,而是把可复用状态、输入约束、返回契约与副作用清理一起封装。完成本节后,你可以写出调用端有类型提示、内部可维护、组件卸载后不会遗留监听器的 Vue 3 组合函数。
学习目标
- 用 TypeScript 为组合函数的参数和返回值建立明确契约。
- 用
ref、computed与生命周期钩子封装可复用状态逻辑。 - 为事件监听、定时器等副作用设计可靠的清理机制。
先设计调用契约
组合函数应先从“调用者需要什么”倒推接口,而不是把组件内部变量原样搬出去。参数负责表达外部输入,返回值只暴露调用者真正需要的状态与操作;能由内部状态推导出的值,优先返回只读的 ComputedRef,避免调用端绕过约束直接修改。
下面实现一个 useWindowSize:允许传入可选的防抖时间,返回窗口宽高以及是否达到桌面断点。它有浏览器事件监听,因此还必须在组件卸载时解绑。
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 }
}预期结果
组件调用 useWindowSize({ debounceMs: 100 }) 后,可获得带类型提示的 width、height 和只读 isDesktop;组件卸载时 resize 监听器与待执行定时器会被清理。在组件中消费组合函数
调用端只关心组合函数公开的契约,不需要知道监听器、定时器或断点判断如何实现。这样以后即使内部从 resize 事件改成 ResizeObserver,只要返回接口不变,组件通常无需修改。
<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>预期结果
页面显示当前视口宽高;当宽度达到 1024 像素时显示“桌面布局”,否则显示“移动布局”。调整窗口后状态会自动更新。类型设计要保留约束
不要为了“灵活”把参数写成 any,也不要无差别返回所有内部 ref。如果调用者只能读取某个派生状态,就返回 ComputedRef;如果参数存在有限选项,用联合类型或字面量类型表达;如果组合函数需要接收响应式输入,可明确使用 Ref<T>、MaybeRef<T> 或项目约定的泛型类型。
同时要避免把组件实例细节带入组合函数。组合函数应尽量依赖显式参数和 Vue 响应式原语,而不是偷偷读取某个页面组件的局部变量,这样才真正具备跨组件复用能力。
副作用必须成对清理
只要组合函数创建了浏览器监听器、定时器、订阅或第三方实例,就应在同一文件里定义对应的释放逻辑。创建与清理分散在不同组件中,会让复用者必须了解内部实现,最终失去封装意义。
对于依赖生命周期的组合函数,还要明确它只能在组件 setup 或其他具备活动组件实例的上下文中调用。若逻辑需要在组件外运行,应改为显式暴露 start、stop,而不是依赖 onMounted 和 onBeforeUnmount。
一个可靠的类型化组合函数,最终应同时做到三件事:调用接口清晰、响应式语义可预测、副作用生命周期完整。满足这三点后,它才适合作为企业项目中的长期复用单元。