Как использовать аннотации типов в файлах JavaScript
2026-02-26 18:17 Diff
https://ru.hexlet.io/blog/posts/kak-ispolzovat-annotatsii-tipov-v-faylah-javascript

TypeScript (TS) позволяет использовать аннотации типов в коде JavaScript. TS даже может проверять код при сборке, благодаря чему вы увидите ошибки до того, как они попадут в продакшен. Вы избавитесь от undefined is not a function навсегда.

TypeScript по умолчанию требует некоторых изменений при настройке окружения. Вам придётся переименовать файлы JavaScript в .ts, .tsx, а также использовать компиляторы tsc или Babel.

Содержание

Синтаксис TypeScript

Часто людям не нравится работать с TypeScript из-за необходимости использовать новый для них синтаксис. Если вам знакома эта ситуация, статья как раз для вас.

Синтаксис TypeScript позволяет использовать аннотации типов инлайн. Но сначала поговорим об альтернативах.

Документируем JavaScript

Синтаксис JSDoc

TypeScript можно документировать с помощью JSDoc. Это стандартный синтаксис для документирования JavaScript. JSDoc используется для создания документации, но TypeScript понимает аннотации типов, созданные с помощью этого инструмента.

Это значит, что у вас есть возможности использовать преимущество TypeScript, в частности, проверку типов, без необходимости конвертировать весь код.

Почему JSDoc

Применение JSDoc — полезная практика, даже если вы не используете TypeScript. Фактически это стандарт документирования JavaScript, и его поддерживают разные инструменты и редакторы.

Если вы уже применяете JSDoc, вам будет удобно использовать проверку типов в коде, аналогичную той, которая применяется в TypeScript. Для этого нужно уделить время настройке TypeScript.

Установка TypeScript

Как установить TypeScript

Чтобы установить в проект TypeScript, используйте такую команду:

Как включить проверку типов JSDoc

Теперь нужно настроить TypeScript, чтобы он проверял код в файлах JavaScript. По умолчанию он проверяет только файлы с расширением .ts. Настройки TypeScript надо указывать в файле tsconfig.json. Обратите внимание на опцию noEmit. Мы используем её, так как планируем применять TypeScript только для проверки типов.

Настраиваем TypeScript

В начале файлов .js, в которых вам нужна проверка типов, добавьте комментарий:

Запустите проверку типов. Это можно сделать с помощью команды:

Рекомендуется использовать проверку типов также в инструментах непрерывной интеграции (CI).

Дальше поговорим о документировании кода с помощью JSDoc.

Базовые аннотации

Аннотации параметров функций

Для аннотации параметров функций используйте @param. Его нужно указать в комментариях JSDoc, которые начинаются с двух идущих подряд астериксов.

Документирование кода

JSDoc — инструмент для документирования. Кроме добавления аннотаций типов, вы можете документировать функции.

Потренируемся в документировании.

Документирование параметров

Опциональные типы

Чтобы показать опциональность типа, добавьте после него знак равенства. В примере ниже number= — то же самое, что и number | null | undefined. Такой синтаксис можно использовать только в типах JSDoc.

Документируем опции

Вы можете документировать свойства параметров, например, options.count или options.separator. Эту возможность можно использовать для документирования props в функциональных компонентах React.

Утверждения типов (Type Assertions)

Переменные

Используйте @type, когда пишете инлайн определение для аргументов функций. Это обычно избыточно для констант, так как TypeScript чётко работает с типами. Подход полезен при работе с изменяемыми данными, например, с переменными.

Параметры функций

@type можно использовать для определения типов аргументов функций инлайн. Это особенно удобно при работе с анонимными функциями.

Далее поговорим о выносе определений типов в отдельные файлы.

Импорт определений типов

Импортируем типы

Сложные и переиспользуемые типы лучше определять во внешних файлах. Они имеют расширение .d.ts. Обратите внимание, это должны быть именно файлы TypeScript. Импортировать определения из файлов JavaScript невозможно.

Типы можно импортировать с помощью представленного ниже синтаксиса. Определения должны определяться во внешних файлах с расширением .d.ts, как сказано выше.

Определяем типы во внешних файлах

Ниже представлен синтаксис определения типов во внешних файлах TypeScript. Ещё раз обратите внимание, импортировать определения типов из файлов JavaScript невозможно.

Теперь разберёмся, можно ли определять типы в JavaScript-файлах.

Определение типов в файлах JavaScript

Типы объектов

Для определения типов объектов используйте @typedef. Предпочтительно делать это во внешних файлах с расширением .d.ts. Но вы можете использовать представленный ниже синтаксис и в файлах JavaScript.

Объединение типов

Используйте объединение типов (|) для определения двух или более возможных вариантов. Для простоты используйте @typedef.

Как насчёт React?

Определение типов в React

Функциональные компоненты

Функциональные компоненты представляют собой функции. Поэтому вы можете документировать их способами, о которых говорилось выше в разделе о документировании функций. В следующем примере показано документирование с помощью типов объектов.

Подробности о функциональных компонентах можно узнать в курсе по React, который входит в профессию «Фронтенд JavaScript».

Компоненты на классах

Используйте @extends для определения типов props и state. Также для решения этой задачи можно использовать @typedef инлайн или с импортом.

Расширенные возможности

Синтаксис JSDoc не такой выразительный, как TypeScript, но эти инструменты всё-таки похожи. Ниже перечислены некоторые дополнительные возможности TS, доступные в JSDoc.

  • Темплейты — @templates.
  • Возврат значений — @returns.
  • Условия типов — @returns.
  • Функциональные типы — @callback.
  • Перечисления — @enum.

Ещё больше возможностей найдёте в официальной документации.

Резюме

Ниже представлены перечисленные в статье способы работы с аннотациями типов.

Проверка типов JavaScript

Документирование функций

Импорт определений типов (позволяет определять типы во внешних файлах)

Опциональные типы

Анонимные функции

Документирование свойств параметров объектов

Адаптированный перевод статьи Type annotations in JavaScript files by Rico Sta. Cruz. Мнение администрации Хекслета может не совпадать с мнением автора оригинальной публикации.