在 Vue 3 应用中，如何使用 `TypeScript` 的类型系统，为 `v-model` 和 `props` 编写类型安全的组件？

同学们，早上好！今天咱们来聊聊Vue 3里如何用TypeScript把咱们的组件类型安全武装到牙齿。说白了，就是让v-model和props都乖乖听咱TypeScript的话，减少那些神出鬼没的运行时错误。

开场白：类型安全的必要性

在没有类型系统的世界里，咱们的JavaScript代码就像在黑夜里开车，全凭感觉。今天感觉良好，可能一路顺风；明天感觉不好，撞到哪里都不知道。而TypeScript就像给咱们的车装上了夜视仪，不仅能照亮前方的路，还能提前预警障碍物。

对于Vue组件来说，props和v-model是组件与外界交流的桥梁。如果这两个桥梁出了问题，比如传错了类型，或者v-model的值根本不符合预期，那么整个组件就会变得不稳定。所以，用TypeScript武装它们，绝对是值得的。

一、Props的类型安全

Props是组件接收外部数据的接口。在Vue 3中，我们可以用两种方式来定义props的类型：

1. 使用defineProps（推荐）

defineProps是Vue 3提供的API，专门用来定义组件的props。它结合了TypeScript，可以让我们轻松地声明props的类型。

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

interface Props {
  message: string;
  count?: number; // 可选prop
  items: string[];
  callback: (value: string) => void;
}

const props = defineProps<Props>();

// 访问props
console.log(props.message);
console.log(props.count); // 如果没有传递，则为 undefined
console.log(props.items);
props.callback('hello');
</script>

<template>
  <div>
    <p>{{ props.message }}</p>
    <p v-if="props.count">Count: {{ props.count }}</p>
    <ul>
      <li v-for="item in props.items" :key="item">{{ item }}</li>
    </ul>
  </div>
</template>

在这个例子中，我们首先定义了一个Props接口，它描述了组件props的类型。然后，我们使用defineProps<Props>()告诉Vue，这个组件的props应该符合Props接口的定义。

• message: string：表示message这个prop必须是一个字符串。
• count?: number：表示count这个prop是一个可选的数字。
• items: string[]：表示items这个prop必须是一个字符串数组。
• callback: (value: string) => void：表示callback这个prop必须是一个函数，它接收一个字符串参数，并且没有返回值。

如果父组件传递的props类型不符合Props接口的定义，TypeScript编译器会报错，从而避免了运行时错误。

2. 使用props选项对象

这是Vue 2的经典用法，在Vue 3中仍然有效，但不如defineProps灵活。

// MyComponent.vue
<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  props: {
    message: {
      type: String,
      required: true
    },
    count: {
      type: Number,
      default: 0
    },
    items: {
      type: Array,
      default: () => []
    },
    callback: {
      type: Function as PropType<(value: string) => void>,
      required: true
    }
  },
  setup(props) {
    console.log(props.message);
    console.log(props.count);
    console.log(props.items);
    props.callback('hello');

    return {};
  }
});
</script>

<template>
  <div>
    <p>{{ message }}</p>
    <p v-if="count">Count: {{ count }}</p>
    <ul>
      <li v-for="item in items" :key="item">{{ item }}</li>
    </ul>
  </div>
</template>

在这个例子中，我们使用props选项对象来定义props。

• type：指定prop的类型。可以是String、Number、Boolean、Array、Object、Date、Function、Symbol。
• required：指定prop是否是必需的。
• default：指定prop的默认值。
• Function as PropType<(value: string) => void>：由于Function类型在TypeScript中比较模糊，所以我们需要使用PropType来明确指定函数的类型。

虽然这种方式也能提供类型检查，但不如defineProps简洁和易读。而且，在使用props选项对象时，我们需要手动将props传递给setup函数，略显繁琐。

Props类型声明方式对比

特性	defineProps	props选项对象
类型声明方式	使用泛型接口或类型别名	使用type属性，需要PropType辅助
简洁性	更简洁，易读	相对繁琐
自动类型推断	更好，可以根据接口或类型别名自动推断类型	较弱，需要手动指定type和PropType
setup函数集成	自动将props注入到setup函数中，无需手动传递	需要手动将props传递给setup函数
适用场景	推荐在Vue 3中使用，尤其是在使用<script setup>语法糖时	兼容Vue 2的写法，但在Vue 3中不推荐使用

高级技巧：使用PropType进行更精确的类型控制

有时候，type属性提供的类型不够精确。比如，我们想要限制prop只能是某些特定的字符串，或者只能是某些特定的对象。这时，我们可以使用PropType来定义更精确的类型。

import { defineComponent, PropType } from 'vue';

interface Person {
  name: string;
  age: number;
}

export default defineComponent({
  props: {
    status: {
      type: String as PropType<'active' | 'inactive' | 'pending'>,
      default: 'pending'
    },
    person: {
      type: Object as PropType<Person>,
      required: true
    }
  },
  setup(props) {
    console.log(props.status);
    console.log(props.person.name); // 可以安全地访问 person.name

    return {};
  }
});

在这个例子中：

• String as PropType<'active' | 'inactive' | 'pending'>：表示status这个prop只能是'active'、'inactive'或'pending'这三个字符串之一。
• Object as PropType<Person>：表示person这个prop必须是一个符合Person接口定义的对象。

二、v-model的类型安全

v-model是Vue中实现双向数据绑定的语法糖。在Vue 3中，我们可以使用defineEmits和modelValue prop来实现类型安全的v-model。

1. 使用defineEmits定义update:modelValue事件

// MyInput.vue
<script setup lang="ts">
import { defineProps, defineEmits } from 'vue';

interface Props {
  modelValue: string;
}

interface Emits {
  (e: 'update:modelValue', value: string): void;
}

const props = defineProps<Props>();
const emit = defineEmits<Emits>();

const handleChange = (event: Event) => {
  const target = event.target as HTMLInputElement;
  emit('update:modelValue', target.value);
};
</script>

<template>
  <input type="text" :value="modelValue" @input="handleChange">
</template>

在这个例子中：

• 我们定义了一个Props接口，它包含一个modelValue属性，类型为string。
• 我们定义了一个Emits接口，它描述了组件可以触发的事件。'update:modelValue'事件接收一个string类型的参数。
• 我们使用defineEmits<Emits>()告诉Vue，这个组件可以触发Emits接口中定义的事件。
• 在handleChange函数中，我们触发'update:modelValue'事件，并将输入框的值作为参数传递出去。

这样，父组件就可以通过v-model来绑定modelValue prop，并且可以确保传递的值是字符串类型。

// ParentComponent.vue
<template>
  <MyInput v-model="inputValue" />
  <p>Input Value: {{ inputValue }}</p>
</template>

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

const inputValue = ref('');
</script>

2. 简化写法：使用defineModel (实验性API)

Vue 3.3+ 引入了一个实验性的 API defineModel，旨在简化 v-model 的类型安全使用。它自动处理了 prop 和 emit 的定义。

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

const modelValue = defineModel<string>({
  required: true, // 可选，添加验证
  default: ''
})
</script>

<template>
  <input type="text" :value="modelValue" @input="$emit('update:modelValue', $event.target.value)">
</template>

在这个例子中，defineModel<string>() 自动创建了 modelValue prop 和 update:modelValue 事件，并且确保它们是 string 类型。 不需要再手动 defineProps 和 defineEmits，写法更加简洁。 required 和 default 选项提供了基本的验证支持。

3. v-model的参数：处理多个v-model绑定

如果组件需要支持多个v-model绑定，可以使用v-model的参数来实现。

// MyComponent.vue
<script setup lang="ts">
import { defineProps, defineEmits } from 'vue';

interface Props {
  title: string;
  content: string;
}

interface Emits {
  (e: 'update:title', value: string): void;
  (e: 'update:content', value: string): void;
}

const props = defineProps<Props>();
const emit = defineEmits<Emits>();

const handleTitleChange = (event: Event) => {
  const target = event.target as HTMLInputElement;
  emit('update:title', target.value);
};

const handleContentChange = (event: Event) => {
  const target = event.target as HTMLTextAreaElement;
  emit('update:content', target.value);
};
</script>

<template>
  <div>
    <input type="text" :value="title" @input="handleTitleChange">
    <textarea :value="content" @input="handleContentChange"></textarea>
  </div>
</template>

在这个例子中：

• 我们定义了title和content两个props。
• 我们定义了'update:title'和'update:content'两个事件。

父组件可以通过v-model的参数来绑定这两个props。

// ParentComponent.vue
<template>
  <MyComponent v-model:title="titleValue" v-model:content="contentValue" />
  <p>Title: {{ titleValue }}</p>
  <p>Content: {{ contentValue }}</p>
</template>

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

const titleValue = ref('');
const contentValue = ref('');
</script>

v-model类型声明方式对比

特性	使用defineEmits	使用defineModel (实验性)
简洁性	相对繁琐，需要手动定义prop和emit	更简洁，自动创建prop和emit
类型安全性	同样提供类型安全保障	同样提供类型安全保障
适用场景	通用，适用于所有v-model场景	适用于简单v-model绑定，在Vue 3.3+版本中使用，需要开启实验性特性
可定制性	可以自定义事件名称和参数类型	定制性较弱，主要通过required和default选项进行验证

三、复杂类型和泛型的应用

当你的props和v-model涉及到更复杂的类型时，比如联合类型、交叉类型、泛型等，TypeScript的威力就更能体现出来了。

1. 联合类型

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

interface Props {
  status: 'active' | 'inactive' | 'pending';
  value: string | number;
}

const props = defineProps<Props>();

console.log(props.status);
console.log(props.value);
</script>

<template>
  <div>
    <p>Status: {{ status }}</p>
    <p>Value: {{ value }}</p>
  </div>
</template>

在这个例子中：

• status: 'active' | 'inactive' | 'pending'：表示status这个prop只能是'active'、'inactive'或'pending'这三个字符串之一。
• value: string | number：表示value这个prop可以是字符串或数字。

2. 交叉类型

interface User {
  name: string;
  age: number;
}

interface Address {
  city: string;
  country: string;
}

type UserWithAddress = User & Address;

// MyComponent.vue
<script setup lang="ts">
import { defineProps, PropType } from 'vue';
import { UserWithAddress } from './types';

interface Props {
  user: UserWithAddress;
}

const props = defineProps<Props>();

console.log(props.user.name);
console.log(props.user.age);
console.log(props.user.city);
console.log(props.user.country);
</script>

<template>
  <div>
    <p>Name: {{ user.name }}</p>
    <p>Age: {{ user.age }}</p>
    <p>City: {{ user.city }}</p>
    <p>Country: {{ user.country }}</p>
  </div>
</template>

在这个例子中：

• UserWithAddress = User & Address：表示UserWithAddress类型是User和Address类型的交叉类型，它同时拥有User和Address的所有属性。

3. 泛型

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

interface Props<T> {
  items: T[];
  renderItem: (item: T) => string;
}

const props = defineProps<Props<any>>(); // 或者更具体的类型，例如Props<number>

</script>

<template>
  <ul>
    <li v-for="(item, index) in items" :key="index">
      {{ renderItem(item) }}
    </li>
  </ul>
</template>

在这个例子中：

• Props<T>：表示Props接口是一个泛型接口，它接收一个类型参数T。
• items: T[]：表示items这个prop是一个T类型的数组。
• renderItem: (item: T) => string：表示renderItem这个prop是一个函数，它接收一个T类型的参数，并且返回一个字符串。

父组件可以根据需要传递不同的类型参数给MyList组件。

四、最佳实践和注意事项

1. 尽可能使用defineProps和defineEmits

defineProps和defineEmits是Vue 3推荐的API，它们更简洁、易读，并且能更好地与TypeScript集成。

2. 为所有props和emits定义类型

即使是简单的组件，也应该为所有props和emits定义类型。这可以帮助你及早发现错误，并且提高代码的可维护性。

3. 使用接口或类型别名来定义props的类型

使用接口或类型别名可以使你的代码更易于理解和重用。

4. 注意可选props的处理

可选props的值可能是undefined，所以在访问可选props时，需要进行判空处理。

5. 利用TypeScript的类型推断

TypeScript可以根据上下文自动推断类型，所以在某些情况下，你可以省略类型声明。

6. 考虑使用第三方库来简化类型定义

有一些第三方库，比如vue-property-decorator，可以帮助你更方便地定义props和emits的类型。

总结

通过TypeScript，我们可以为Vue组件的props和v-model添加类型安全，从而减少运行时错误，提高代码的可维护性和可读性。虽然类型定义可能需要一些额外的工作，但是从长远来看，这是绝对值得的。

记住，类型安全并不是银弹，它不能解决所有问题。但是，它可以帮助我们编写更可靠、更健壮的代码。希望今天的讲座能帮助大家更好地理解如何在Vue 3中使用TypeScript来构建类型安全的组件。

好了，今天的课就到这里，下课！