Vue 组件的编译期性能契约：用泛型 Props 与 defineModel 把运行时校验前移到类型层

引言

Vue 3 的 <script setup> 让组件写法更简洁，却也留下了类型退化的口子：defineProps 不写类型就得到 any，v-model 的绑定链在深层组件里悄悄断裂。这些「类型里的洞」，运行时都得靠额外的校验和收窄来补。本文不重复 Vue 的类型 API 清单，只拆三处能用 TypeScript 把性能与正确性同时前移到编译期的关键点。

一、泛型 Props：让子组件随父组件的数据「同步变型」

列表、表格这类通用组件，总有人为了省事把 props 标成 any，结果父子之间的类型契约彻底丢失。

<!-- 反例：props 标 any，父传什么都行，子组件内部失去类型约束 -->
<script setup lang="ts">
const props = defineProps<{ items: any; itemKey: string }>();
function render(item: unknown) {
  return item[props.itemKey]; // item 是 any，属性访问失控
}
</script>

<!-- 正例：泛型 Props，让 items 的元素类型随父组件推导 -->
<script setup lang="ts" generic="T extends { id: number }">
import { computed } from 'vue';

const props = defineProps<{
  items: T[];
  itemKey: keyof T;
}>();

// T 由 items 推导，itemKey 被约束为 T 的键，非法键直接报编译错
const firstId = computed(() => props.items[0]?.id);
</script>

generic="T extends { id: number }" 声明泛型参数，items: T[] 让 T 由父组件传入的数据自动推导。itemKey: keyof T 进一步把字段名约束到 T 的真实键上——传一个不存在的 itemKey，编译期就报错，根本到不了运行时。

二、defineModel：把双向绑定收敛成显式契约

v-model 是 Vue 的高频特性，但手写 emit('update:modelValue') 的旧语法，类型是可选的、约束是松散的，深层组件里极易写错事件名或漏掉载荷。

<!-- 反例：手写 emit，事件名与载荷全靠自觉，类型约束为零 -->
<script setup lang="ts">
const props = defineProps<{ modelValue: string }>();
const emit = defineEmits<{ (e: 'update:modelValue', v: string): void }>();

function onChange(v: string) {
  emit('update:modelValue', v); // 事件名拼错、载荷类型错，编译不报
}
</script>

<!-- 正例：defineModel 自动生成 modelValue 的绑定契约 -->
<script setup lang="ts">
const model = defineModel<string>();

// model.value 读、写自动同步父组件，无需手写 emit 与 props
function onChange(v: string) {
  model.value = v;
}
</script>

defineModel<string>() 一次性生成了 modelValue 的读取、写入与类型，父组件 v-model 绑定链在类型层就是一根完整的、不可写错的管道。省掉的不只是样板，更是「事件名失配」这类只能靠运行时暴露的隐性 bug。

三、组合式函数的返回类型：别让推导停在 Ref 之外

抽取 composable 是 Vue 的性能与复用利器，但如果返回类型不精确，调用方拿到的是 any 或笼统的 Ref<unknown>，后续每一步都要靠断言收窄。

// 反例：返回类型模糊，调用方拿到 Ref<unknown>，处处收窄
import { ref } from 'vue';

export function useCounter() {
  const count = ref(0);
  const double = ref(0);
  // 忘记标注返回类型，double 可能被推断成 Ref<number>，但逻辑关系丢失
  function inc() { count.value++; double.value = count.value * 2; }
  return { count, double, inc };
}

// 调用方：count 与 double 的关系、inc 的签名都不明确
const { count, double, inc } = useCounter();

// 正例：显式返回类型 + computed 收敛派生，让契约自文档化
import { ref, computed } from 'vue';

export function useCounter() {
  const count = ref(0);
  const double = computed(() => count.value * 2); // computed 自动追踪
  function inc() { count.value++; }
  return { count, double, inc: inc as () => void };
}

// 调用方：count 是 Ref<number>，double 是 ComputedRef<number>，inc 签名明确
const { count, double, inc } = useCounter();

用 computed 替代手动的 double.value = ... 同步，派生的正确性交给响应式系统保证，同时返回类型精确到 ComputedRef<number>。调用方不再需要任何断言，类型本身就是文档。

四、用 defineExpose 划定组件对外的类型边界

<script setup> 默认封闭，父组件通过 ref 拿到子组件实例时，需要显式暴露。不暴露或暴露成 any，都会让类型边界沦陷。

<!-- 子组件：defineExpose 显式声明对外契约 -->
<script setup lang="ts">
import { ref } from 'vue';

const count = ref(0);
function reset() { count.value = 0; }

defineExpose({ count, reset }); // 只有这两个成员对外可见
</script>

<!-- 父组件：通过 InstanceType 拿到精确的实例类型 -->
<script setup lang="ts">
import { ref } from 'vue';
import Child from './Child.vue';

const childRef = ref<InstanceType<typeof Child> | null>(null);

function handleReset() {
  childRef.value?.reset(); // 类型精确：reset 存在，count 可读不可写
}
</script>

InstanceType<typeof Child> 从子组件的 defineExpose 自动推导出实例类型，父组件只能访问被暴露的成员，且类型精确。未暴露的成员在类型层就是「不可见」，彻底杜绝了 ref.xxx.anyMethod() 这类运行时才炸的调用。

五、把「前移」落到三条契约

以上四个点收敛成三条可执行原则，让 TypeScript 真正成为组件性能与正确性的第一道闸：

// 正例：Vue 编译期契约三原则
// 1. 通用组件用泛型 Props + keyof，让父子数据同步变型，消灭 any
// 2. 双向绑定用 defineModel，事件名与载荷在类型层闭环
// 3. 组合式函数/组件实例用精确返回类型与 defineExpose，杜绝 unknown 收窄

// 反模式速查
//   defineProps<{ items: any }>：父子契约断裂，运行时靠断言补
//   手写 update:modelValue：事件名拼错只到运行时才炸
//   useXxx 返回 Ref<unknown>：调用方处处类型收窄，性能与可读性双输
//   defineExpose 漏暴露或 any：实例类型边界沦陷

这些原则的共同逻辑是：凡能在编译期用类型说清楚的事，就不要留到运行时用一次 if、一次断言、一次事件名比对来兜底。类型精确了，运行时该省的校验省了，该避的 bug 避了——性能与正确性在这条线上是同一件事。

结语

Vue 的性能优化常常被框在「响应式追踪」「渲染粒度」这些运行时话题里，但 TypeScript 给了一条更早的防线：在组件契约成型之前，就用泛型、defineModel、精确返回类型把它们锁死。当 Prop 的类型随父组件同步推导、v-model 的绑定链在类型层闭环、组合式函数与实例边界精确到不需要任何断言时，那些「运行时才暴露的坑」就已经被消灭在了编译期。这才是「类型即性能」在 Vue 里的真正含义。