Vue 之 vue3 与 TS 的配合使用整理

Posted 2022-12-12 zhuangwei_8256

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Vue 之 vue3 与 TS 的配合使用整理相关的知识，希望对你有一定的参考价值。

说明

本文主要是说明vue3中的一些ts的用法，且**文章内容都是从vue官网整理下来的**，如有重复，请说明，谢谢。

前言

配置 tsconfig.json

通过 create-vue 搭建的项目包含了预先配置好的 tsconfig.json。其底层配置抽象于 @vue/tsconfig 包中。在项目内我们使用 Project References 来确保运行在不同环境下的代码的类型正确 (比如应用代码和测试代码应该有不同的全局变量)。

手动配置 tsconfig.json 时，请留意以下选项：

compilerOptions.isolatedModules 应当设置为 true，因为 Vite 使用 esbuild 来转译 TypeScript，并受限于单文件转译的限制。
如果你正在使用选项式 API，需要将 compilerOptions.strict 设置为 true (或者至少开启 compilerOptions.noImplicitThis，它是 strict 模式的一部分)，才可以获得对组件选项中 this 的类型检查。否则 this 会被认为是 any。
如果你在构建工具中配置了路径解析别名，例如 @/* 这个别名被默认配置在了 create-vue 项目中，你需要通过 compilerOptions.paths 选项为 TypeScript 再配置一遍。

正文

TypeScript 与组合式 API

为组件的 props 标注类型

使用 `<script setup>`

当使用 <script setup> 时，defineProps() 宏函数支持从它的参数中推导类型：

<script setup lang="ts">
const props = defineProps(
  foo:  type: String, required: true ,
  bar: Number
)

props.foo // string
props.bar // number | undefined
</script>

这被称之为“运行时声明”，因为传递给 defineProps() 的参数会作为运行时的 props 选项使用。

然而，通过泛型参数来定义 props 的类型通常更直接：

<script setup lang="ts">
const props = defineProps<
  foo: string
  bar?: number
>()
</script>

这被称之为“基于类型的声明”。编译器会尽可能地尝试根据类型参数推导出等价的运行时选项。在这种场景下，我们第二个例子中编译出的运行时选项和第一个是完全一致的。

基于类型的声明或者运行时声明可以择一使用，但是不能同时使用。

我们也可以将 props 的类型移入一个单独的接口中：

<script setup lang="ts">
interface Props 
  foo: string
  bar?: number


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

语法限制

为了生成正确的运行时代码，传给 defineProps() 的泛型参数必须是以下之一：

一个类型字面量：

defineProps< /*... */ >()

对同一个文件中的一个接口或对象类型字面量的引用：

interface Props /* ... */

defineProps<Props>()

接口或对象字面类型可以包含从其他文件导入的类型引用，但是，传递给 defineProps 的泛型参数本身不能是一个导入的类型：

import  Props  from './other-file'

// 不支持！
defineProps<Props>()

这是因为 Vue 组件是单独编译的，编译器目前不会抓取导入的文件以分析源类型。我们计划在未来的版本中解决这个限制。

Props 解构默认值

当使用基于类型的声明时，我们失去了为 props 声明默认值的能力。这可以通过 withDefaults 编译器宏解决：

export interface Props 
  msg?: string
  labels?: string[]


const props = withDefaults(defineProps<Props>(), 
  msg: 'hello',
  labels: () => ['one', 'two']
)

这将被编译为等效的运行时 props default 选项。此外，withDefaults 帮助程序为默认值提供类型检查，并确保返回的 props 类型删除了已声明默认值的属性的可选标志。

或者，你可以使用目前为实验性的响应性语法糖：

<script setup lang="ts">
interface Props 
  name: string
  count?: number


// 对 defineProps() 的响应性解构
// 默认值会被编译为等价的运行时选项
const  name, count = 100  = defineProps<Props>()
</script>

这个行为目前需要显式地选择开启。

非 `<script setup>` 场景下

如果没有使用 <script setup>，那么为了开启 props 的类型推导，必须使用 defineComponent()。传入 setup() 的 props 对象类型是从 props 选项中推导而来。

import  defineComponent  from 'vue'

export default defineComponent(
  props: 
    message: String
  ,
  setup(props) 
    props.message // <-- 类型：string
  
)

为组件的 emits 标注类型

在 <script setup> 中，emit 函数的类型标注也可以通过运行时声明或是类型声明进行：

<script setup lang="ts">
// 运行时
const emit = defineEmits(['change', 'update'])

// 基于类型
const emit = defineEmits<
  (e: 'change', id: number): void
  (e: 'update', value: string): void
>()
</script>

这个类型参数应该是一个带调用签名的类型字面量。这个类型字面量的类型就是返回的 emit 函数的类型。我们可以看到，基于类型的声明使我们可以对所触发事件的类型进行更细粒度的控制。

若没有使用 <script setup>，defineComponent() 也可以根据 emits 选项推导暴露在 setup 上下文中的 emit 函数的类型：

import  defineComponent  from 'vue'

export default defineComponent(
  emits: ['change'],
  setup(props,  emit ) 
    emit('change') // <-- 类型检查 / 自动补全
  
)

为 ref() 标注类型

ref 会根据初始化时的值推导其类型：

import  ref  from 'vue'

// 推导出的类型：Ref<number>
const year = ref(2020)

// => TS Error: Type 'string' is not assignable to type 'number'.
year.value = '2020'

有时我们可能想为 ref 内的值指定一个更复杂的类型，可以通过使用 Ref 这个类型：

import  ref  from 'vue'
import type  Ref  from 'vue'

const year: Ref<string | number> = ref('2020')

year.value = 2020 // 成功！

或者，在调用 ref() 时传入一个泛型参数，来覆盖默认的推导行为：

// 得到的类型：Ref<string | number>
const year = ref<string | number>('2020')

year.value = 2020 // 成功！

如果你指定了一个泛型参数但没有给出初始值，那么最后得到的就将是一个包含 undefined 的联合类型：

// 推导得到的类型：Ref<number | undefined>
const n = ref<number>()

为 reactive() 标注类型

reactive() 也会隐式地从它的参数中推导类型：

import  reactive  from 'vue'

// 推导得到的类型： title: string 
const book = reactive( title: 'Vue 3 指引' )

要显式地标注一个 reactive 变量的类型，我们可以使用接口：

import  reactive  from 'vue'

interface Book 
  title: string
  year?: number


const book: Book = reactive( title: 'Vue 3 指引' )

不推荐使用 reactive() 的泛型参数，因为处理了深层次 ref 解包的返回值与泛型参数的类型不同。

为 computed() 标注类型

computed() 会自动从其计算函数的返回值上推导出类型：

import  ref, computed  from 'vue'

const count = ref(0)

// 推导得到的类型：ComputedRef<number>
const double = computed(() => count.value * 2)

// => TS Error: Property 'split' does not exist on type 'number'
const result = double.value.split('')

你还可以通过泛型参数显式指定类型：

const double = computed<number>(() => 
  // 若返回值不是 number 类型则会报错
)

为事件处理函数标注类型

在处理原生 DOM 事件时，应该为我们传递给事件处理函数的参数正确地标注类型。让我们看一下这个例子：

<script setup lang="ts">
function handleChange(event) 
  // `event` 隐式地标注为 `any` 类型
  console.log(event.target.value)

</script>

<template>
  <input type="text" @change="handleChange" />
</template>

没有类型标注时，这个 event 参数会隐式地标注为 any 类型。这也会在 tsconfig.json 中配置了 “strict”: true 或 “noImplicitAny”: true 时报出一个 TS 错误。因此，建议显式地为事件处理函数的参数标注类型。此外，你可能需要显式地强制转换 event 上的属性：

function handleChange(event: Event) 
  console.log((event.target as htmlInputElement).value)

为 provide / inject 标注类型

provide 和 inject 通常会在不同的组件中运行。要正确地为注入的值标记类型，Vue 提供了一个 InjectionKey 接口，它是一个继承自 Symbol 的泛型类型，可以用来在提供者和消费者之间同步注入值的类型：

import  provide, inject  from 'vue'
import type  InjectionKey  from 'vue'

const key = Symbol() as InjectionKey<string>

provide(key, 'foo') // 若提供的是非字符串值会导致错误

const foo = inject(key) // foo 的类型：string | undefined

建议将注入 key 的类型放在一个单独的文件中，这样它就可以被多个组件导入。

当使用字符串注入 key 时，注入值的类型是 unknown，需要通过泛型参数显式声明：

const foo = inject<string>('foo') // 类型：string | undefined

注意注入的值仍然可以是 undefined，因为无法保证提供者一定会在运行时 provide 这个值。

当提供了一个默认值后，这个 undefined 类型就可以被移除：

const foo = inject<string>('foo', 'bar') // 类型：string

如果你确定该值将始终被提供，则还可以强制转换该值：

const foo = inject('foo') as string

为模板引用标注类型

模板引用需要通过一个显式指定的泛型参数和一个初始值 null 来创建：

<script setup lang="ts">
import  ref, onMounted  from 'vue'

const el = ref<HTMLInputElement | null>(null)

onMounted(() => 
  el.value?.focus()
)
</script>

<template>
  <input ref="el" />
</template>

注意为了严格的类型安全，有必要在访问 el.value 时使用可选链或类型守卫。这是因为直到组件被挂载前，这个 ref 的值都是初始的 null，并且在由于 v-if 的行为将引用的元素卸载时也可以被设置为 null。

为组件模板引用标注类型

有时，你可能需要为一个子组件添加一个模板引用，以便调用它公开的方法。举例来说，我们有一个 MyModal 子组件，它有一个打开模态框的方法：

<!-- MyModal.vue -->
<script setup lang="ts">
import  ref  from 'vue'

const isContentShown = ref(false)
const open = () => (isContentShown.value = true)

defineExpose(
  open
)
</script>

为了获取 MyModal 的类型，我们首先需要通过 typeof 得到其类型，再使用 TypeScript 内置的 InstanceType 工具类型来获取其实例类型：

<!-- App.vue -->
<script setup lang="ts">
import MyModal from './MyModal.vue'

const modal = ref<InstanceType<typeof MyModal> | null>(null)

const openModal = () => 
  modal.value?.open()

</script>

注意，如果你想在 TypeScript 文件而不是在 Vue SFC 中使用这种技巧，需要开启 Volar 的 Takeover 模式。

TypeScript 与选项式 API

为组件的 props 标注类型

选项式 API 中对 props 的类型推导需要用 defineComponent() 来包装组件。有了它，Vue 才可以通过 props 以及一些额外的选项，比如 required: true 和 default 来推导出 props 的类型：

import  defineComponent  from 'vue'

export default defineComponent(
  // 启用了类型推导
  props: 
    name: String,
    id: [Number, String],
    msg:  type: String, required: true ,
    metadata: null
  ,
  mounted() 
    this.name // 类型：string | undefined
    this.id // 类型：number | string | undefined
    this.msg // 类型：string
    this.metadata // 类型：any
  
)

然而，这种运行时 props 选项仅支持使用构造函数来作为一个 prop 的类型——没有办法指定多层级对象或函数签名之类的复杂类型。

我们可以使用 PropType 这个工具类型来标记更复杂的 props 类型：

import  defineComponent  from 'vue'
import type  PropType  from 'vue'

interface Book 
  title: string
  author: string
  year: number


export default defineComponent(
  props: 
    book: 
      // 提供相对 `Object` 更确定的类型
      type: Object as PropType<Book>,
      required: true
    ,
    // 也可以标记函数
    callback: Function as PropType<(id: number) => void>
  ,
  mounted() 
    this.book.title // string
    this.book.year // number

    // TS Error: argument of type 'string' is not
    // assignable to parameter of type 'number'
    this.callback?.('123')
  
)

注意事项如果你的 TypeScript 版本低于 4.7，在使用函数作为 prop 的 validator 和 default
选项值时需要格外小心——确保使用箭头函数：

import  defineComponent  from 'vue'
import type  PropType  from 'vue'

interface Book 
  title: string
  year?: number


export default defineComponent(
  props: 
    bookA: 
      type: Object as PropType<Book>,
      // 如果你的 TypeScript 版本低于 4.7，确保使用箭头函数
      default: () => (
        title: 'Arrow Function Expression'
      ),
      validator: (book: Book) => !!book.title
    
  
)

这会防止 TypeScript 将 this 根据函数内的环境作出不符合我们期望的类型推导。这是之前版本的一个设计限制，不过现在已经在
TypeScript 4.7 中解决了。

为组件的 emits 标注类型

我们可以给 emits 选项提供一个对象来声明组件所触发的事件，以及这些事件所期望的参数类型。试图触发未声明的事件会抛出一个类型错误：

import  defineComponent  from 'vue'

export default defineComponent(
  emits: 
    addBook(payload:  bookName: string ) 
      // 执行运行时校验
      return payload.bookName.length > 0
    
  ,
  methods: 
    onSubmit() 
      this.$emit('addBook', 
        bookName: 123 // 类型错误
      )

      this.$emit('non-declared-event') // 类型错误
    
  
)

为计算属性标记类型

计算属性会自动根据其返回值来推导其类型：

import  defineComponent  from 'vue'

export default defineComponent(
  data() 
    return 
      message: 'Hello!'
    
  ,
  computed: 
    greeting() 
      return this.message + '!'
    
  ,
  mounted() 
    this.greeting // 类型：string
  
)

在某些场景中，你可能想要显式地标记出计算属性的类型以确保其实现是正确的：

import  defineComponent  from 'vue'

export default defineComponent(
  data() 
    return 
      message: 'Hello!'
    
  ,
  computed: 
    // 显式标注返回类型
    greeting(): string 
      return this.message + '!'
    ,

    // 标注一个可写的计算属性
    greetingUppercased: 
      get(): string 
        return this.greeting.toUpperCase()
      ,
      set(newValue: string) 
        this.message = newValue.toUpperCase()
      
    
  
)

在某些 TypeScript 因循环引用而无法推导类型的情况下，可能必须进行显式的类型标注。

为事件处理函数标注类型

在处理原生 DOM 事件时，应该为我们传递给事件处理函数的参数正确地标注类型。让我们看一下这个例子：

<script lang="ts">
import  defineComponent  from 'vue'

export default defineComponent(
  methods: 
    handleChange(event) 
      // `event` 隐式地标注为 `any` 类型
      console.log(event.target.value)
    
  
)
</script>

<template>
  <input type=以上是关于Vue 之 vue3 与 TS 的配合使用整理的主要内容，如果未能解决你的问题，请参考以下文章 
 Vue3+Ts各种错误整理
 Vue3+Ts各种错误整理
 Vue3+Ts各种错误整理
 Vue3+Ts各种错误整理
 vite+vue3+ts 项目初始化操作
 vue3+vite+ts 搭建项目

Vue 之 vue3 与 TS 的配合使用整理

目录

说明

前言

配置 tsconfig.json

正文

TypeScript 与组合式 API

为组件的 props 标注类型

使用 <script setup>

语法限制

Props 解构默认值

非 <script setup> 场景下

为组件的 emits 标注类型

为 ref() 标注类型

为 reactive() 标注类型

为 computed() 标注类型

为事件处理函数标注类型

为 provide / inject 标注类型

为模板引用标注类型

为组件模板引用标注类型

TypeScript 与选项式 API

为组件的 props 标注类型

为组件的 emits 标注类型

为计算属性标记类型

为事件处理函数标注类型

使用 `<script setup>`

非 `<script setup>` 场景下