Annotations de types JSDoc comme passerelle
Ajoutez des types aux fichiers JS avec JSDoc avant la conversion
Annotations de types JSDoc comme passerelle est une leçon TypeScript Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage TypeScript Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours TypeScript Academy comprend 4 leçons au total.
JSDoc comme pont vers TypeScript
TypeScript peut lire les annotations de types JSDoc dans les fichiers JavaScript lorsque checkJs: true est activé. Vous pouvez ainsi ajouter des types au JS sans renommer les fichiers.
/** @type {string} */
let name = "Alice"; // TypeScript checks this as string@param et @returns
Annotez les paramètres des fonctions et leurs types de retour à l'aide des balises JSDoc.
/**
* @param {string} name
* @param {number} age
* @returns {string}
*/
function greet(name, age) {
return `${name} is ${age}`;
}@typedef pour les types d'objets
Utilisez @typedef pour définir des alias de types réutilisables dans JSDoc.
/**
* @typedef {Object} User
* @property {string} id
* @property {string} name
* @property {boolean} isActive
*/
/** @type {User} */
const user = { id: "1", name: "Alice", isActive: true };@template pour les types génériques
Utilisez @template pour écrire des fonctions génériques dans JSDoc.
/**
* @template T
* @param {T[]} arr
* @returns {T | undefined}
*/
function first(arr) {
return arr[0];
}
// TypeScript infers: first<T>(arr: T[]): T | undefinedImporter des types depuis des fichiers .ts
JSDoc prend en charge @type {import("./types").User} pour importer des types TypeScript dans les fichiers JS.
/** @type {import("./types").User} */
const admin = { id: "admin", name: "Admin", isActive: true };@ts-check pour la vérification fichier par fichier
Ajoutez // @ts-check en haut d'un fichier JS pour activer la vérification TypeScript uniquement pour ce fichier, sans activer globalement checkJs: true.
// @ts-check
/** @type {number} */
const count = "oops"; // Error: string not assignable to number@ts-ignore et @ts-expect-error
Supprimez des erreurs de types JSDoc précises avec des directives intégrées, sans désactiver la vérification de tout le fichier.
// @ts-ignore
const x = badFunction(); // single error suppressed
// @ts-expect-error
const y = anotherBad(); // error expected hereÉnumérations JSDoc
Simulez les énumérations TypeScript dans JSDoc à l'aide de @enum.
/** @enum {string} */
const Direction = { Left: "left", Right: "right", Up: "up" };Assertions de types dans JSDoc
Utilisez /** @type {SomeType} */ (expression) pour effectuer des assertions de types JSDoc, ce qui équivaut à as SomeType en TypeScript.
const el = /** @type {HTMLInputElement} */ (document.getElementById("input"));
el.value; // el: HTMLInputElement — typedQuand passer à .ts
Les annotations JSDoc sont un pont, pas une destination. Lorsqu'un fichier est entièrement annoté et stable, renommez-le en .ts et supprimez les commentaires de types JSDoc au profit de la syntaxe TypeScript native.
// Rename: utils.js → utils.ts
// Replace JSDoc: /** @param {string} x */ → (x: string)Récapitulatif : JSDoc comme pont
Les annotations de types JSDoc permettent à TypeScript de vérifier les fichiers JS sans les renommer. Utilisez @type, @param, @typedef et @template pour ajouter progressivement la sécurité des types avant de passer à TypeScript natif.
Vérification rapide
Quelle balise JSDoc active la vérification TypeScript dans un seul fichier sans activer globalement checkJs ?
Ce que vous avez appris
Les annotations de types JSDoc font le lien entre JavaScript et TypeScript : utilisez @type, @param, @typedef et @template pour ajouter des types aux fichiers JS. Activez la vérification fichier par fichier avec // @ts-check, puis passez à TypeScript natif lorsque le fichier est prêt.
Questions Fréquemment Posées
La leçon « Annotations de types JSDoc comme passerelle » est-elle gratuite ?
Oui — le texte complet de « Annotations de types JSDoc comme passerelle » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours TypeScript Academy, passe à CoddyKit PRO. Le cours TypeScript Academy comprend 4 leçons au total.
Qu'est-ce que j'apprendrai dans « Annotations de types JSDoc comme passerelle » ?
Ajoutez des types aux fichiers JS avec JSDoc avant la conversion Tu pratiques TypeScript Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.
Dois-je avoir de l'expérience pour commencer TypeScript Academy ?
Aucune expérience préalable n'est requise. TypeScript Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.
Combien de temps prend la leçon « Annotations de types JSDoc comme passerelle » ?
La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.
Peux-tu écrire et exécuter du code dans cette leçon TypeScript Academy ?
Oui. Chaque leçon TypeScript Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.
Toutes les leçons de ce cours
- Commencer la migration : allowJs et checkJs
- Annotations de types JSDoc comme passerelle
- Stratégie de conversion fichier par fichier
- Gérer les bibliothèques tierces non typées