Vue3 与 TypeScript 实战：核心细节与最佳实践

引言

Vue3 的 Composition API 与 TypeScript 的强类型支持完美契合，极大提升了代码的可维护性和开发体验。本文将深入探讨 Vue3 + TypeScript 的关键细节，并通过实际代码示例展示如何高效结合二者。

一、组合式 API 与类型推导

Vue3 的 setup 函数与 TypeScript 的类型推导结合，让组件逻辑更清晰。

示例：带类型推导的组件

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

// 自动推导类型：count.value 为 number
const count = ref(0);

// 明确类型声明
const message = ref<string>('Hello');

// 带类型的函数
const increment = (step: number): void => {
  count.value += step;
};
</script>

关键点：

• ref 自动推导基础类型（如 number）

• 泛型 ref<string> 显式声明复杂类型

• 函数参数和返回值类型增强可读性

二、Props 的类型安全

通过 TypeScript 的接口（interface）定义 Props，实现编译时类型检查。

示例：类型安全的 Props

<script setup lang="ts">
interface Props {
  title: string;
  count?: number;  // 可选属性
  items: Array<{ id: number; name: string }>;
}

const props = defineProps<Props>();
</script>

关键点：

• 使用 interface 或 type 定义 Props 结构

• defineProps<Props>() 直接绑定类型

• 可选属性通过 ? 标记

三、响应式状态与复杂类型

Vue3 的 reactive 和 ref 与 TypeScript 的类型系统深度协作。

示例：复杂对象类型

interface User {
  id: number;
  name: string;
  roles: string[];
}

// 明确响应式对象的类型
const user = reactive<User>({
  id: 1,
  name: 'Alice',
  roles: ['admin'],
});

// 使用 ref 包裹对象
const config = ref<{ apiUrl: string; timeout: number }>({
  apiUrl: 'https://api.example.com',
  timeout: 5000,
});

关键点：

• reactive 直接接收泛型类型

• ref 泛型声明复杂对象类型

• 嵌套对象属性自动类型推断

四、自定义 Hooks 的类型约束

使用 TypeScript 封装可复用的 Composition 函数。

示例：带类型的自定义 Hook

// useCounter.ts
import { ref, type Ref } from 'vue';

export default function useCounter(initialValue: number = 0) {
  const count: Ref<number> = ref(initialValue);

  const increment = (step: number = 1): void => {
    count.value += step;
  };

  return {
    count,
    increment,
  };
}

使用 Hook：

<script setup lang="ts">
import useCounter from './useCounter';

const { count, increment } = useCounter(10);
</script>

优势：

• 输入参数类型 (initialValue: number)

• 返回值类型自动推导

• 明确的泛型类型（如 Ref<number>）

五、模板中的类型安全

Vue3 模板中的事件和插槽也能享受 TypeScript 支持。

示例：带类型的事件处理器

<script setup lang="ts">
const emit = defineEmits<{
  (e: 'update', payload: { id: number; value: string }): void;
  (e: 'delete', id: number): void;
}>();

const handleClick = () => {
  emit('update', { id: 1, value: 'new' }); // ✅ 正确
  emit('delete', '123'); // ❌ 错误：参数类型不匹配
};
</script>

六、第三方库的类型扩展

为 Vue 插件或全局属性添加类型声明。

示例：扩展全局属性

// global.d.ts
import axios from 'axios';

declare module 'vue' {
  interface ComponentCustomProperties {
    $http: typeof axios;
    $translate: (key: string) => string;
  }
}

注意事项

1. 避免隐式 any：在 tsconfig.json 中启用 strict: true

2. 类型文件组织：使用 .d.ts 文件管理全局类型

3. 响应式对象的陷阱：

   // 错误：直接解构会丢失响应性
   const { x, y } = reactive({ x: 1, y: 2 });
   // 正确：使用 toRefs
   const { x, y } = toRefs(reactive({ x: 1, y: 2 }));

总结

Vue3 与 TypeScript 的结合为前端开发带来：

• 类型安全：减少运行时错误

• 代码自解释：类型即文档

• 开发效率：IDE 智能提示

• 可维护性：清晰的组件契约