Rivalry2

HTML Diff

0 added 0 removed

Original 2026-01-01

Modified 2026-02-26

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

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

3 <h2>Содержание</h2>

4 <ul><li><a>Синтаксис TypeScript</a></li>

5 <li><a>Документируем JavaScript</a></li>

6 <li><a>Установка TypeScript</a></li>

7 <li><a>Базовые аннотации</a></li>

8 <li><a>Документирование параметров</a></li>

9 <li><a>Утверждения типов (Type Assertions)</a></li>

10 <li><a>Импорт определений типов</a></li>

11 <li><a>Определение типов в файлах JavaScript</a></li>

12 <li><a>Определение типов в React</a></li>

13 <li><a>Расширенные возможности</a></li>

14 <li><a>Резюме</a></li>

15 </ul><h2>Синтаксис TypeScript</h2>

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

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

18 <h2>Документируем JavaScript</h2>

19 <h3>Синтаксис JSDoc</h3>

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

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

22 <h3>Почему JSDoc</h3>

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

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

25 <h2>Установка TypeScript</h2>

26 <h3>Как установить TypeScript</h3>

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

28 <h3>Как включить проверку типов JSDoc</h3>

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

30 <h3>Настраиваем TypeScript</h3>

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

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

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

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

35 <h2>Базовые аннотации</h2>

36 <h3>Аннотации параметров функций</h3>

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

38 <h3>Документирование кода</h3>

39 <p>JSDoc - инструмент для документирования. Кроме добавления аннотаций типов, вы можете документировать функции.</p>

40 <p>Потренируемся в документировании.</p>

41 <h2>Документирование параметров</h2>

42 <h3>Опциональные типы</h3>

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

44 <h3>Документируем опции</h3>

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

46 <h2>Утверждения типов (Type Assertions)</h2>

47 <h3>Переменные</h3>

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

49 <h3>Параметры функций</h3>

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

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

52 <h2>Импорт определений типов</h2>

53 <h3>Импортируем типы</h3>

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

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

56 <h3>Определяем типы во внешних файлах</h3>

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

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

59 <h2>Определение типов в файлах JavaScript</h2>

60 <h3>Типы объектов</h3>

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

62 <h3>Объединение типов</h3>

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

64 <p>Как насчёт React?</p>

65 <h2>Определение типов в React</h2>

66 <h3>Функциональные компоненты</h3>

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

68 <blockquote><p>Подробности о функциональных компонентах можно узнать в курсе по React, который входит<a>в профессию "Фронтенд JavaScript"</a>.</p>

69 </blockquote><h3>Компоненты на классах</h3>

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

71 <h2>Расширенные возможности</h2>

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

73 <ul><li>Темплейты - @templates.</li>

74 <li>Возврат значений - @returns.</li>

75 <li>Условия типов - @returns.</li>

76 <li>Функциональные типы - @callback.</li>

77 <li>Перечисления - @enum.</li>

78 </ul><p>Ещё больше возможностей найдёте<a>в официальной документации</a>.</p>

79 <h2>Резюме</h2>

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

81 <p><strong>Проверка типов JavaScript</strong></p>

82 <p><strong>Документирование функций</strong></p>

83 <p><strong>Импорт определений типов (позволяет определять типы во внешних файлах)</strong></p>

84 <p><strong>Опциональные типы</strong></p>

85 <p><strong>Анонимные функции</strong></p>

86 <p><strong>Документирование свойств параметров объектов</strong></p>

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