Vue 教程：基于 TypeScript 的组件 Props 类型定义与运行时校验

快速概述

在 Vue 3 中，使用 TypeScript 为组件 Props 定义类型，可以同时获得编译期的类型检查与运行时的 props 校验，避免父组件传入错误数据类型导致的隐性 bug。该方案适用于使用 Vue 3 + TypeScript 的工程化项目，要求环境已安装 Node.js（^20.19.0 或 >=22.12.0）以及 Vue 官方脚手架 create-vue。

核心概念与原理

Vue 组件的 props 是父组件向子组件传递数据的机制。在选项式 API 中，props 选项支持类型验证与默认值设置；在组合式 API 中，配合 TypeScript 的 defineProps 宏，可以直接使用类型标注来声明 props 的类型，同时 Vue 会根据类型自动生成运行时校验逻辑。 运行时校验确保传入值符合预期，类型标注则提供 IDE 提示与编译期检查。

实战步骤与代码

1. 创建项目：运行 npm create vue@latest，在提示中选择 TypeScript 支持。
2. 定义带类型的 Props：在 <script setup lang="ts"> 中使用 defineProps 声明类型。

<script setup lang="ts">
// 定义 props 类型接口
interface Props {
  title: string;          // 必填字符串
  count?: number;         // 可选数字
  items: string[];        // 字符串数组
}
// 使用泛型定义 props，并设置默认值 const props = withDefaults(defineProps<Props>(), { count: 0,               // 默认值 items: () => []        // 数组默认值需用工厂函数 }); </script>

若使用选项式 API，可在 props 选项中配置类型与校验：

<script lang="ts"> export default { props: { title: { type: String, required: true }, count: { type: Number, default: 0 } } }; </script>

常见坑点与优化

• 默认值陷阱：对象或数组类型的默认值必须使用工厂函数返回，否则多个实例会共享同一引用。
• 类型校验失效：在 defineProps 中仅使用类型标注时，运行时仍会进行基础类型校验，但复杂对象建议使用 validator 函数。
• 性能优化：避免在 props 中传递大型对象，使用 shallowRef 或拆分细粒度 props 减少响应式追踪开销。

总结

通过 TypeScript 定义 Props 类型，既提升了代码可维护性，又保留了 Vue 的运行时校验能力。推荐在项目初始化时即启用 TypeScript，并遵循官方脚手架的最佳实践。