Аннотации типов JSDoc как переходный этап
Добавляйте типы в файлы JS с помощью JSDoc перед преобразованием
«Аннотации типов JSDoc как переходный этап» — бесплатный урок TypeScript Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения TypeScript Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс TypeScript Academy содержит 4 уроков всего.
JSDoc как мост к TypeScript
TypeScript может читать аннотации типов JSDoc в файлах JavaScript, если включён параметр checkJs: true. Благодаря этому вы можете добавлять типы в JS, не переименовывая файлы.
/** @type {string} */
let name = "Alice"; // TypeScript checks this as string@param и @returns
Аннотируйте параметры функций и возвращаемые типы с помощью тегов JSDoc.
/**
* @param {string} name
* @param {number} age
* @returns {string}
*/
function greet(name, age) {
return `${name} is ${age}`;
}@typedef для типов объектов
Используйте @typedef, чтобы определять повторно используемые псевдонимы типов в JSDoc.
/**
* @typedef {Object} User
* @property {string} id
* @property {string} name
* @property {boolean} isActive
*/
/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };@template для обобщённых типов
Используйте @template, чтобы записывать обобщённые функции в JSDoc.
/**
* @template T
* @param {T[]} arr
* @returns {T | undefined}
*/
function first(arr) {
return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefinedИмпорт типов из файлов .ts
JSDoc поддерживает @type {import("./types").User} для импорта типов TypeScript в файлы JS.
/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };@ts-check для проверки отдельного файла
Добавьте // @ts-check в начало файла JS, чтобы включить проверку TypeScript только для этого файла, не включая глобально checkJs: true.
// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number@ts-ignore и @ts-expect-error
Подавляйте отдельные ошибки типов JSDoc с помощью директив в строке, не отключая проверку всего файла.
// @ts-ignore
const x = badFunction(); // single error suppressed
// @ts-expect-error
const y = anotherBad(); // error expected hereПеречисления JSDoc
Имитируйте перечисления TypeScript в JSDoc с помощью @enum.
/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };Утверждения типов в JSDoc
Используйте /** @type {SomeType} */ (expression) для утверждений типов JSDoc — это эквивалент конструкции TypeScript as SomeType.
const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typedКогда переходить на .ts
Аннотации JSDoc — это мост, а не конечная цель. Когда файл полностью аннотирован и стабилен, переименуйте его в .ts и замените комментарии с типами JSDoc на собственный синтаксис TypeScript.
// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)Итоги: JSDoc как мост
Аннотации типов JSDoc позволяют проверять TypeScript в файлах JS, не переименовывая их. Используйте @type, @param, @typedef и @template, чтобы постепенно повысить безопасность типов перед переходом на собственный синтаксис TypeScript.
Быстрая проверка
Какой тег JSDoc включает проверку TypeScript в одном файле без глобального параметра checkJs?
Что вы узнали
Аннотации типов JSDoc служат мостом между JavaScript и TypeScript: используйте @type, @param, @typedef и @template, чтобы добавлять типы в файлы JS. Включайте проверку отдельного файла с помощью // @ts-check, а затем переходите на собственный синтаксис TypeScript, когда файл будет готов.
Часто задаваемые вопросы
Урок «Аннотации типов JSDoc как переходный этап» бесплатный?
Да — полный текст урока «Аннотации типов JSDoc как переходный этап» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс TypeScript Academy, подпишись на CoddyKit PRO. Курс TypeScript Academy содержит 4 уроков всего.
Чему я научусь в уроке «Аннотации типов JSDoc как переходный этап»?
Добавляйте типы в файлы JS с помощью JSDoc перед преобразованием Ты практикуешь TypeScript Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать TypeScript Academy?
Предыдущий опыт не требуется. TypeScript Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.
Сколько времени занимает урок «Аннотации типов JSDoc как переходный этап»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке TypeScript Academy?
Да. Каждый урок TypeScript Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Начало миграции: allowJs и checkJs
- Аннотации типов JSDoc как переходный этап
- Стратегия преобразования файл за файлом
- Работа с нетипизированными сторонними библиотеками