发布于 由admin

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

欢迎来到今天的 Vue 3 + TypeScript 类型安全组件构建讲座！ 今天咱们的目标是：让你的 Vue 组件不仅能跑，还能优雅地被 TypeScript 保护起来，告别那些运行时才暴露的类型错误。想象一下，你的代码就像一个坚固的堡垒，TypeScript 就是守卫它的骑士，时刻警惕着任何潜在的入侵者（类型错误）。

1. props 的类型安全：让组件接收正确的“礼物”

首先，我们从 props 开始。props 就像组件接收的礼物，我们必须确保这些礼物是组件期望的，否则组件可能会“罢工”。

1.1 简单类型的 props

最简单的场景，props 是基本类型，比如 string、number、boolean。

// MyComponent.vue

<template>
  <div>
    <h1>{{ title }}</h1>
    <p>Count: {{ count }}</p>
    <p>Is Active: {{ isActive }}</p>
  </div>
</template>

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

const props = defineProps({
  title: {
    type: String,
    required: true,
  },
  count: {
    type: Number,
    default: 0,
  },
  isActive: {
    type: Boolean,
    default: false,
  },
});

console.log(props.title); // string
console.log(props.count); // number
console.log(props.isActive); // boolean
</script>

这里，我们使用了 defineProps 宏，并为每个 prop 指定了 type。 required: true 表示该 prop 必须传递，否则 TypeScript 会报错。 default 提供了默认值，如果没有传递该 prop，组件会使用默认值。

类型推断的优点：

TypeScript 能够根据 type 自动推断出 props 的类型。 在 <script setup> 中，props.title 的类型会被推断为 string，props.count 为 number，props.isActive 为 boolean。 这意味着你可以在代码中安全地使用这些 props，而不用担心类型错误。

1.2 使用接口定义 props

当 props 数量较多或者结构复杂时，使用接口 (interface) 可以提高代码的可读性和可维护性。

// MyComponent.vue

<template>
  <div>
    <h1>{{ user.name }}</h1>
    <p>Email: {{ user.email }}</p>
    <p>Age: {{ user.age }}</p>
  </div>
</template>

<script setup lang="ts">
import { defineProps, PropType } from 'vue';

interface User {
  name: string;
  email: string;
  age: number;
  isAdmin?: boolean; // 可选属性
}

const props = defineProps({
  user: {
    type: Object as PropType<User>, // 使用 Object as PropType<User>
    required: true,
  },
});

console.log(props.user.name); // string
console.log(props.user.email); // string
console.log(props.user.age); // number
//console.log(props.user.address); // 报错：对象类型“{ name: string; email: string; age: number; }”上不存在属性“address”。
</script>

重点:

  • Object as PropType<User>: 这是关键！ type: Object 告诉 Vue 这个 prop 是一个对象，而 as PropType<User> 告诉 TypeScript 这个对象的具体类型是 User 接口定义的类型。
  • 可选属性 isAdmin?: isAdmin? 表示 isAdmin 是一个可选属性，可以不传递。
  • 类型检查: TypeScript 会检查传递给 user prop 的对象是否符合 User 接口的定义。 如果传递的对象缺少 name、email 或 age 属性，或者这些属性的类型不正确，TypeScript 会报错。

1.3 使用泛型定义 props (更简洁)

Vue 3 提供了使用泛型定义 props 的方式，更加简洁。

// MyComponent.vue

<template>
  <div>
    <h1>{{ user.name }}</h1>
    <p>Email: {{ user.email }}</p>
    <p>Age: {{ user.age }}</p>
  </div>
</template>

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

interface User {
  name: string;
  email: string;
  age: number;
  isAdmin?: boolean;
}

const props = defineProps<{ user: User }>();

console.log(props.user.name); // string
console.log(props.user.email); // string
console.log(props.user.age); // number
//console.log(props.user.address); // 报错：对象类型“{ user: User; }”上不存在属性“address”。
</script>

优点:

  • 更简洁: 不需要显式地指定 type 和 required。
  • 类型推断: TypeScript 可以根据泛型参数自动推断出 props 的类型。

1.4 使用 PropType 定义复杂类型

当 prop 的类型比较复杂，例如数组、联合类型或者自定义类型时，可以使用 PropType。

// MyComponent.vue

<template>
  <div>
    <ul>
      <li v-for="item in items" :key="item">{{ item }}</li>
    </ul>
    <p>Status: {{ status }}</p>
  </div>
</template>

<script setup lang="ts">
import { defineProps, PropType } from 'vue';

type Status = 'pending' | 'processing' | 'completed' | 'rejected';

const props = defineProps({
  items: {
    type: Array as PropType<string[]>,
    default: () => [],
  },
  status: {
    type: String as PropType<Status>,
    default: 'pending',
    validator(value: string): boolean {
      return ['pending', 'processing', 'completed', 'rejected'].includes(value);
    },
  },
});

console.log(props.items); // string[]
console.log(props.status); // Status
</script>

重点:

  • Array as PropType<string[]>: 告诉 TypeScript items 是一个字符串数组。
  • String as PropType<Status>: 告诉 TypeScript status 是一个 Status 类型，并且可以使用 validator 进行运行时校验。
  • validator: validator 函数用于在运行时校验 prop 的值是否合法。 它可以帮助你捕获一些在 TypeScript 类型检查中无法发现的错误。

1.5 总结 props 类型定义

方法 描述 优点 缺点
简单类型 (String, Number, Boolean) 使用 type: String、type: Number、type: Boolean 定义基本类型的 props。 简单易懂，适用于简单的 props。 缺乏灵活性，无法定义复杂的类型。
接口 (interface) + PropType 使用 interface 定义 prop 的类型，然后使用 type: Object as PropType<YourInterface>。 可以定义复杂的对象类型，提高代码的可读性和可维护性。 略显繁琐，需要显式地指定 type 和 PropType。
泛型 使用 defineProps<{ yourProp: YourType }>() 定义 props。 更加简洁，TypeScript 可以自动推断类型。 适用于简单的对象类型，对于复杂的类型可能需要使用 PropType。
PropType (Array, 联合类型, 自定义类型) 使用 type: Array as PropType<YourType[]>、type: String as PropType<YourUnionType> 定义数组、联合类型和自定义类型的 props。 可以定义各种复杂的类型，灵活性强。 需要显式地指定 PropType，代码略显冗长。

2. v-model 的类型安全： 双向绑定的福音

v-model 是 Vue 中实现双向绑定的重要指令。 为了确保 v-model 的类型安全，我们需要定义 modelValue prop 和 update:modelValue 事件。

2.1 简单类型的 v-model

// MyInput.vue

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

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

const props = defineProps({
  modelValue: {
    type: String,
    default: '',
  },
});

const emit = defineEmits(['update:modelValue']);
</script>

重点:

  • modelValue prop: v-model 默认使用 modelValue 作为绑定的 prop。 我们将其类型定义为 String。
  • update:modelValue 事件: v-model 默认监听 update:modelValue 事件来更新绑定的值。 我们在 @input 事件中触发 update:modelValue 事件，并将输入框的值传递给父组件。
  • 类型转换 ($event.target as HTMLInputElement).value: $event.target 的类型是 EventTarget，我们需要将其转换为 HTMLInputElement 才能访问 value 属性。

父组件使用:

<template>
  <div>
    <MyInput v-model="message" />
    <p>Message: {{ message }}</p>
  </div>
</template>

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

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

2.2 自定义 v-model 名称

如果你想使用不同的 prop 和事件名称，可以使用 model 选项。

// MyInput.vue

<template>
  <input type="text" :value="title" @input="emit('change-title', ($event.target as HTMLInputElement).value)" />
</template>

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

const props = defineProps({
  title: {
    type: String,
    default: '',
  },
});

const emit = defineEmits(['change-title']);

defineOptions({
    model: {
        prop: 'title',
        event: 'change-title'
    }
})
</script>

重点:

  • defineOptions: 使用 defineOptions 宏来配置组件的选项。
  • model 选项: model 选项指定了 prop 和事件的名称。 prop: 'title' 表示使用 title prop，event: 'change-title' 表示监听 change-title 事件。

父组件使用:

<template>
  <div>
    <MyInput v-model:title="message" />
    <p>Message: {{ message }}</p>
  </div>
</template>

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

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

2.3 复杂类型的 v-model

v-model 还可以绑定复杂类型，例如对象。

// MyObjectInput.vue

<template>
  <div>
    <label>Name: <input type="text" :value="modelValue.name" @input="updateName($event.target.value)" /></label><br />
    <label>Age: <input type="number" :value="modelValue.age" @input="updateAge($event.target.value)" /></label>
  </div>
</template>

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

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

const props = defineProps<{ modelValue: Person }>();
const emit = defineEmits<{ (e: 'update:modelValue', value: Person): void }>();

const updateName = (name: string) => {
  emit('update:modelValue', { ...props.modelValue, name });
};

const updateAge = (age: string) => {
  emit('update:modelValue', { ...props.modelValue, age: Number(age) });
};
</script>

重点:

  • Person 接口: 定义了 v-model 绑定的对象的类型。
  • defineProps<{ modelValue: Person }>(): 指定 modelValue 的类型为 Person。
  • defineEmits<{ (e: 'update:modelValue', value: Person): void }>(): 指定 update:modelValue 事件的参数类型为 Person。 这确保了我们在触发 update:modelValue 事件时传递的是一个符合 Person 接口的对象。
  • 展开运算符 ...props.modelValue: 在更新对象时，使用展开运算符可以避免覆盖其他属性。

父组件使用:

<template>
  <div>
    <MyObjectInput v-model="person" />
    <p>Name: {{ person.name }}</p>
    <p>Age: {{ person.age }}</p>
  </div>
</template>

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

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

const person = ref<Person>({ name: 'John', age: 30 });
</script>

2.4 总结 v-model 类型定义

特性 描述 优点 缺点
默认 v-model 使用 modelValue prop 和 update:modelValue 事件实现双向绑定。 简单易用，适用于大多数场景。 默认名称固定，不够灵活。
自定义 v-model 使用 model 选项配置 prop 和事件的名称。 更加灵活，可以自定义 prop 和事件的名称。 需要使用 defineOptions，略显繁琐。
复杂类型 v-model 使用接口或类型别名定义 v-model 绑定的对象的类型，并使用 defineProps 和 defineEmits 指定类型。 可以绑定各种复杂的对象类型，确保类型安全。 需要定义接口或类型别名，代码略显冗长。

3. emit 的类型安全：组件之间的“悄悄话”

emit 用于组件之间传递事件。 为了确保 emit 的类型安全，我们需要使用 defineEmits 宏来定义组件可以触发的事件和它们的参数类型。

3.1 简单事件

// MyButton.vue

<template>
  <button @click="emit('click', 'Button Clicked!')">Click Me</button>
</template>

<script setup lang="ts">
import { defineEmits } from 'vue';

const emit = defineEmits(['click']);
</script>

这里，我们定义了一个 click 事件，但是没有指定参数类型。 这意味着我们可以传递任何类型的值作为参数，但是 TypeScript 不会进行类型检查。

3.2 使用对象字面量定义 emit

为了提高类型安全性，我们可以使用对象字面量来定义 emit，明确指定事件名称和参数类型。

// MyButton.vue

<template>
  <button @click="emit('click', 'Button Clicked!')">Click Me</button>
</template>

<script setup lang="ts">
import { defineEmits } from 'vue';

const emit = defineEmits<{
  (e: 'click', message: string): void
}>();
</script>

重点:

  • defineEmits<{ (e: 'click', message: string): void }>(): 这告诉 TypeScript，MyButton 组件可以触发一个名为 click 的事件，该事件接收一个 string 类型的参数。 e: 'click' 指定事件名称， message: string 指定参数类型。 void 表示该事件不返回任何值。

父组件监听:

<template>
  <div>
    <MyButton @click="handleClick" />
    <p>Message: {{ message }}</p>
  </div>
</template>

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

const message = ref('');

const handleClick = (msg: string) => {
  message.value = msg;
};
</script>

现在，如果我们在 MyButton 组件中触发 click 事件时传递的参数不是 string 类型，TypeScript 会报错。 同样，如果在父组件中监听 click 事件时，handleClick 函数的参数类型不是 string，TypeScript 也会报错。

3.3 使用类型别名定义 emit

当事件数量较多或者参数类型复杂时，使用类型别名可以提高代码的可读性和可维护性。

// MyForm.vue

<template>
  <form @submit.prevent="handleSubmit">
    <label>Name: <input type="text" v-model="name" /></label><br />
    <label>Email: <input type="email" v-model="email" /></label><br />
    <button type="submit">Submit</button>
  </form>
</template>

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

interface FormData {
  name: string;
  email: string;
}

type Emits = {
  (e: 'submit', data: FormData): void;
  (e: 'cancel'): void;
};

const emit = defineEmits<Emits>();

const name = ref('');
const email = ref('');

const handleSubmit = () => {
  const data: FormData = { name: name.value, email: email.value };
  emit('submit', data);
};
</script>

重点:

  • FormData 接口: 定义了表单数据的类型。
  • Emits 类型别名: 定义了组件可以触发的事件和它们的参数类型。 这里定义了两个事件：submit 事件接收一个 FormData 类型的参数，cancel 事件不接收任何参数。
  • defineEmits<Emits>(): 指定 emit 的类型为 Emits。

父组件监听:

<template>
  <div>
    <MyForm @submit="handleSubmit" @cancel="handleCancel" />
    <p>Name: {{ formData.name }}</p>
    <p>Email: {{ formData.email }}</p>
  </div>
</template>

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

interface FormData {
  name: string;
  email: string;
}

const formData = ref<FormData>({ name: '', email: '' });

const handleSubmit = (data: FormData) => {
  formData.value = data;
};

const handleCancel = () => {
  formData.value = { name: '', email: '' };
};
</script>

3.4 总结 emit 类型定义

方法 描述 优点 缺点
简单事件 使用 defineEmits(['eventName']) 定义事件。 简单易用，适用于不需要类型检查的简单事件。 缺乏类型安全性，无法指定参数类型。
对象字面量 使用 defineEmits<{ (e: 'eventName', arg: ArgType): void }>() 定义事件和参数类型。 可以明确指定事件名称和参数类型，提高类型安全性。 代码略显冗长，当事件数量较多时，可读性较差。
类型别名 使用类型别名定义事件和参数类型，然后使用 defineEmits<YourType>() 指定类型。 提高代码的可读性和可维护性，适用于事件数量较多或者参数类型复杂的情况。 需要定义类型别名，略显繁琐。

4. 总结：类型安全组件的构建之路

通过为 props、v-model 和 emit 定义类型，我们可以构建类型安全的 Vue 3 组件。 类型安全可以帮助我们在开发阶段发现潜在的错误，提高代码的质量和可维护性。

最佳实践:

  • 始终为 props 定义类型。 即使是简单的 props，也应该指定类型。
  • 使用接口或类型别名定义复杂类型的 props 和 emit。
  • 使用 validator 函数进行运行时校验。 这可以帮助你捕获一些在 TypeScript 类型检查中无法发现的错误。
  • 充分利用 TypeScript 的类型推断能力。 在可能的情况下，尽量让 TypeScript 自动推断类型，以减少代码的冗余。
  • 保持代码的简洁和可读性。 选择最适合你项目的类型定义方法。

希望今天的讲座对你有所帮助！ 记住，类型安全是构建高质量 Vue 应用的关键。 让我们一起努力，写出更加健壮、可靠的代码！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注