Использование Vue с TypeScript ​

Такая система типов, как TypeScript, может обнаружить множество распространённых ошибок с помощью статического анализа во время сборки. Это снижает вероятность возникновения ошибок во время выполнения в продакшене, а также позволяет более уверенно рефакторить код в масштабных приложениях. TypeScript также улучшает эргономику разработчика благодаря автодополнению типов в IDE.

Vue написан на TypeScript и обеспечивает первоклассную поддержку TypeScript. Все официальные пакеты Vue поставляются с декларациями типов, которые должны работать «из коробки».

Настройка проекта ​

create-vue, официальный инструмент для создания проектов, предлагает возможности для создания проекта Vue на базе Vite с поддержкой TypeScript.

Обзор ​

При установке на основе Vite сервер разработки и пакетный модуль выполняют только транспиляцию и не выполняют проверку типов. Благодаря этому сервер разработки Vite остается молниеносно быстрым даже при использовании TypeScript.

• Во время разработки мы рекомендуем полагаться на хорошую настройку IDE для мгновенной обратной связи с ошибками типа.

• При использовании SFC используйте утилиту vue-tsc для проверки типов в командной строке и генерации объявлений типов. vue-tsc — это обёртка для tsc, собственного интерфейса командной строки TypeScript. Работает в основном так же, как и tsc, за исключением того, что поддерживает Vue SFC в дополнение к файлам TypeScript. Вы можете запустить vue-tsc в режиме watch параллельно с сервером разработки Vite, или использовать плагин Vite, например vite-plugin-checker, который запускает проверки в отдельном рабочем потоке.

• Vue CLI также обеспечивает поддержку TypeScript, но больше не рекомендуется. Смотрите примечания ниже.

Поддержка IDE ​

• Visual Studio Code (VS Code) настоятельно рекомендуется благодаря отличной встроенной поддержке TypeScript.

  • Vue - Official (ранее — Volar) — официальное расширение VS Code, обеспечивающее поддержку TypeScript в SFC Vue, а также множество других замечательных возможностей.

    Совет

    Расширение Vue - Official заменяет Vetur, наше предыдущее официальное расширение VS Code для Vue 2. Если у вас установлен Vetur, не забудьте отключить его в проектах Vue 3.

• WebStorm также обеспечивает встроенную поддержку TypeScript и Vue. Другие IDE от JetBrains тоже поддерживают их, либо из коробки, либо с помощью бесплатного плагина. Начиная с версии 2023.2, WebStorm и плагин Vue Plugin поставляются со встроенной поддержкой Vue Language Server. Вы можете настроить службу Vue на использование интеграции Volar для всех версий TypeScript в разделе Settings > Languages & Frameworks > TypeScript > Vue. По умолчанию Volar будет использоваться для TypeScript версий 5.0 и выше.

Настройка tsconfig.json ​

Проекты, созданные с помощью create-vue, включают в себя предварительно настроенный tsconfig.json. Базовый конфиг абстрагирован в пакете @vue/tsconfig. Внутри проекта мы используем Project References, чтобы обеспечить правильные типы для кода, работающего в разных средах (например, код приложения и тестовый код должны иметь разные глобальные переменные).

Если настраивать tsconfig.json вручную, можно воспользоваться следующими примечательными опциями:

• compilerOptions.isolatedModules имеет значение true, поскольку Vite использует esbuild для транспиляции TypeScript и подвержен ограничениям на транспиляцию одного файла. compilerOptions.verbatimModuleSyntax является надмножеством isolatedModules и тоже является хорошим выбором — именно его использует @vue/tsconfig.

• Если вы используете Options API, вам необходимо установить compilerOptions.strict в true (или, по крайней мере, включить compilerOptions.noImplicitThis, который является частью флага strict), чтобы задействовать проверку типа this в опциях компонента. В противном случае this будет рассматриваться как any.

• Если вы настроили псевдонимы резольвера в вашем инструменте сборки, например псевдоним @/*, настроенный по умолчанию в проекте create-vue, вам нужно также настроить его для TypeScript через compilerOptions.paths.

См. также:

• Официальная документация по опциям компилятора TypeScript
• Предостережения по компиляции TypeScript в esbuild

Примечание о Vue CLI и ts-loader. ​

В системах на основе webpack, таких как Vue CLI, принято выполнять проверку типов как часть конвейера преобразования модулей, например, с помощью ts-loader. Однако это не совсем верное решение, поскольку для проверки типов системе типов необходимо знать весь граф модуля. Шаг преобразования отдельного модуля просто не подходит для этой задачи. Это приводит к следующим проблемам:

• ts-loader может проверять только посттрансформационный код. Это не совпадает с ошибками, которые мы видим в IDE или в vue-tsc, которые отображаются непосредственно в исходном коде.

• Проверка типов может быть медленной. Когда она выполняется в одном потоке/процессе с преобразованиями кода, это существенно влияет на скорость сборки всего приложения.

• У нас уже есть проверка типов, выполняемая прямо в IDE в отдельном процессе, так что стоимость замедления работы разработчика просто не является хорошим компромиссом.

Если вы в настоящее время используете Vue 3 + TypeScript через Vue CLI, мы настоятельно рекомендуем перейти на Vite. Мы также работаем над параметрами CLI, чтобы включить поддержку TS только для транспилирования, чтобы вы могли переключиться на vue-tsc для проверки типов.

Общие замечания по использованию ​

defineComponent() ​

Чтобы TypeScript мог правильно выводить типы в опциях компонентов, нам нужно определить компоненты с помощью defineComponent():

import { defineComponent } from 'vue'

export default defineComponent({
  // включение вывода типа
  props: {
    name: String,
    msg: { type: String, required: true }
  },
  data() {
    return {
      count: 1
    }
  },
  mounted() {
    this.name // тип: string | undefined
    this.msg // тип: string
    this.count // тип: number
  }
})

defineComponent() также поддерживает вывод параметров, переданных в setup(), при использовании Composition API без <script setup>:

import { defineComponent } from 'vue'

export default defineComponent({
  // включение вывода типа
  props: {
    message: String
  },
  setup(props) {
    props.message // тип: string | undefined
  }
})

См. также:

• Заметка о webpack Treeshaking
• Тесты типов для defineComponent

Использование в однофайловых компонентах ​

Чтобы использовать TypeScript в SFC, добавьте атрибут lang="ts" к тегам <script>. Когда присутствует lang="ts", все шаблонные выражения также имеют более строгую проверку типов.

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

export default defineComponent({
  data() {
    return {
      count: 1
    }
  }
})
</script>

<template>
  <!-- включена проверка типа и автозавершение -->
  {{ count.toFixed(2) }}
</template>

lang="ts" также можно использовать с <script setup>:

<script setup lang="ts">
// TypeScript включен
import { ref } from 'vue'

const count = ref(1)
</script>

<template>
  <!-- включена проверка типа и автозавершение -->
  {{ count.toFixed(2) }}
</template>

TypeScript в шаблонах ​

Шаблон <template> также поддерживает TypeScript в выражениях привязки, когда используется <script lang="ts"> или <script setup lang="ts">. Это полезно в тех случаях, когда необходимо выполнить приведение типов в шаблонных выражениях.

Вот надуманный пример:

<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  <!-- ошибка, потому что x может быть строкой -->
  {{ x.toFixed(2) }}
</template>

Это можно обойти с помощью приведения строчного типа:

<script setup lang="ts">
let x: string | number = 1
</script>

<template>
  {{ (x as number).toFixed(2) }}
</template>

Использование с TSX ​

Vue также поддерживает авторские компоненты с JSX/TSX. Подробности описаны в руководстве Рендер-функции и JSX.

Универсальные компоненты ​

Универсальные компоненты поддерживаются в двух случаях:

• В однофайловых компонентах: <script setup> с атрибутом generic
• Рендер-функция / компоненты JSX: Сигнатура функции defineComponent()

Рецепты, специфичные для API ​

• TS с Composition API
• TS с Options API