Skip to content

Використання Vue з TypeScript

Система типів, така як TypeScript, може виявляти багато помилок за допомогою статичного аналізу під час збірки. Це зменшує ймовірність появи помилок під час виконання у production, а також дозволяє більш впевнено рефакторювати код у великомасштабних проєктах. TypeScript також покращує ергономіку розробника завдяки автоматичному заповненню типів у IDE.

Vue написаний на TypeScript, тому забезпечує першокласну підтримку TypeScript. Усі офіційні пакети Vue постачаються в комплекті з деклараціями типів, які працюють з коробки.

Налаштування проєкту

create-vue, офіційний інструмент створення проєктів Vue, який базується на Vite, пропонує опції створення проєктів Vue з TypeScript.

Огляд

З базовими налаштуваннями Vite, сервер розробки й комплектувальник використовуються лише для транспіляції, та не виконують жодної перевірки типів. Це забезпечує блискавичну роботу сервера розробників Vite навіть при використанні TypeScript.

  • Під час розробки рекомендуємо покладатися на хорошу IDE підтримку для миттєвого зворотного зв'язку при помилках типу.

  • Якщо ви використовуєте одно-файлові компоненти, використовуйте vue-tsc утиліту для перевірки типу командного рядка та створення декларації типу. vue-tsc це обгортка навколо tsc, власного інтерфейсу командного рядка TypeScript. Він працює майже так само, як tsc, за винятком того, що він підтримує одно-файлові компоненти на додаток до файлів TypeScript. Ви можете запустити vue-tsc у режимі перегляду, паралельно із сервером розробки Vite або використати плагін для Vite, наприклад vite-plugin-checker який запускає перевірку в окремому робочому потоці.

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

Підтримка IDE

  • Visual Studio Code (VSCode) настійно рекомендується через чудову готову підтримку TypeScript.

    • Volar є офіційним розширенням VSCode, яке забезпечує підтримку TypeScript в одно-файлових компонентах, а також багато інших чудових функцій.

      TIP

      Volar замінює Vetur, наше попереднє офіційне розширення VSCode для Vue 2. Якщо у вас наразі встановлено Vetur, обов'язково вимкніть його в проєктах Vue 3.

    • TypeScript Vue Plugin також необхідний для підтримки імпорту *.vue у файли TS.

  • WebStorm також забезпечує готову підтримку для TypeScript і Vue. Інші IDE JetBrains також підтримують їх, або з коробки, або через вільні плагіни. Починаючи з версії 2023.2, WebStorm і Vue Plugin мають вбудовану підтримку для Vue Language Server. Ви можете налаштувати службу Vue на використання інтеграції Volar у всіх версіях TypeScript у меню «Параметри» > «Мови та фреймворки» > «TypeScript» > Vue. За замовчуванням Volar використовуватиметься для TypeScript версії 5.0 і вище.

Конфігурація tsconfig.json

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

Під час ручної конфігурації tsconfig.json зверніть увагу на важливі опції:

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

  • Якщо ви використовуєте опційний АРІ, вам потрібно встановити compilerOptions.strict на true (або принаймні увімкнути compilerOptions.noImplicitThis, який є частиною strict), щоб використовувати перевірку типів this в опціях компонента. Інакше this розглядатиметься як any.

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

Також до вашої уваги:

Режим Takeover в Volar

Цей розділ стосується лише VSCode + Volar.

Щоб забезпечити спільну роботу одно-файлових компонентів і TypeScript, Volar створює окремий екземпляр мовної служби TS із підтримкою Vue і використовує його в одно-файлових компонентах. Водночас звичайні файли TS все ще обробляються вбудованою мовною службою VSCode, тому нам потрібен Плагін TypeScript для Vue для підтримки імпорту одно-файлових компонентів у файли TS. Це налаштування працює за замовчуванням, але для кожного проєкту ми запускаємо два екземпляри мовної служби TS: одну від Volar і одну від вбудованої служби VSCode. Це трохи неефективно та може призвести до проблем із продуктивністю у великих проєктах.

Для покращення продуктивності, Volar надає функцію під назвою «Режим Takeover». Цей режим забезпечує підтримку як файлів Vue, так і файлів TS, за допомогою єдиного екземпляра мовної служби TS.

Щоб увімкнути режим Takeover, вам потрібно вимкнути вбудовану службу мови TS VSCode лише у робочій області вашого проєкту, виконавши такі дії:

  1. У робочій області проєкту відкрийте панель команд за допомогою Ctrl + Shift + P (macOS: Cmd + Shift + P).
  2. Введіть built і виберіть "Extensions: Show Built-in Extensions".
  3. Введіть typescript у вікні пошуку розширення (не видаляйте префікс @builtin).
  4. Натисніть маленьку піктограму шестірні «TypeScript and JavaScript Language Features» і виберіть «Disable (Workspace)».
  5. Перезавантажте робочу область. Режим Takeover буде ввімкнено, коли ви відкриєте файл Vue або TS.

Примітка щодо 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():

ts
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>:

ts
import { defineComponent } from 'vue'

export default defineComponent({
  // увімкнено визначення типу
  props: {
    message: String
  },
  setup(props) {
    props.message // тип: string | undefined
  }
})

Також до вашої уваги:

TIP

defineComponent() також дає змогу визначати типи для компонентів, визначених у звичайному JavaScript.

Використання в однофайлових компонентах

Щоб використовувати TypeScript в одно-файлових компонентах, додайте атрибут lang="ts" до тегів <script>. Якщо присутній lang="ts", всі вирази шаблону також підлягають більш суворій перевірці типу.

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

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

<template>
  <!-- увімкнено перевірку типу та автодоповнення -->
  {{ count.toFixed(2) }}
</template>

lang="ts" також можна використовувати з <script setup>:

vue
<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">. Це корисно в тих випадках, коли вам потрібно виконати приведення типів у виразах шаблону.

Ось надуманий приклад:

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

<template>
  <!-- помилка, оскільки x може бути string -->
  {{ x.toFixed(2) }}
</template>

Це можна вирішити за допомогою вбудованого приведення типу:

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

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

TIP

У разі використання Vue CLI, або інструмент збірки на основі webpack, TypeScript вимагає у виразах шаблону vue-loader@^16.8.0.

Використання з TSX

Vue також підтримує авторські компоненти з JSX / TSX. Подробиці описано в посібнику Функція візуалізації та JSX.

Компоненти загального типу

Компоненти загального типу підтримуються у двох випадках:

API-специфічні рецепти

Використання Vue з TypeScript has loaded