TypeScript Fichiers de déclaration

Le fichier de déclaration est letraducteur entre les bibliothèques TypeScript et JavaScript, qui indique à TypeScript quelles fonctions une bibliothèque JavaScript expose, quels sont les types des paramètres et quels sont les types des valeurs de retour.


Commençons par un problème.

Supposons que vous écriviez un projet en TypeScript et que vous deviez inclure une bibliothèque JavaScript tierce (comme jQuery). Vous pourriez écrire du code comme ceci :

$('#foo');
// 或
jQuery('#foo');

Ce code fonctionne parfaitement dans un projet JavaScript pur, mais dans un fichier TypeScript, il provoquera directement une erreur :

jQuery('#foo');

// index.ts(1,1): error TS2304: Cannot find name 'jQuery'.

Pourquoi cela provoque-t-il une erreur ? Parce que TypeScript ne reconnaît pas$etjQueryce que c'est.

La fonctionnalité principale de TypeScript est la vérification des types—elle doit connaître le type de chaque variable et de chaque fonction au moment de la compilation. Mais jQuery est une bibliothèque JavaScript pure sans informations de type, donc TypeScript ne peut naturellement pas la comprendre.


Solution rapide : le mot-clé declare

La façon la plus simple est d'utiliser ledeclaremot-clé pour indiquer manuellement à TypeScript : "Cette variable existe, et son type est comme ceci" :

declare var jQuery: (selector: string) => any;

jQuery('#foo');

La signification de cette ligne de code est : déclarer une variablejQuery, qui est une fonction qui prend un paramètre de typestring, et la valeur de retour peut être de n'importe quel type (any)。

Maintenant, TypeScript ne signalera pas d'erreur, car le compilateur sait déjà quel type est jQuery.

declareLes types déclarés avec le mot-clé ne prennent effet qu'à la compilation ; ils sont complètement supprimés dans le code JavaScript compilé et n'affectent pas le comportement à l'exécution.

Le code JavaScript compilé de l'exemple ci-dessus est :

jQuery('#foo');

Comme vous pouvez le voir,declarel'instruction a disparu, ne laissant que le code d'appel réel.

Maisdeclarecela ne peut résoudre que le problème temporaire d'un seul fichier. Si une bibliothèque possède de nombreuses méthodes et de nombreuses classes, il est évidemment irréaliste d'écrire declare manuellement dans chaque fichier. C'est là que les fichiers de déclaration entrent en jeu.


Fichiers de déclaration : une solution définitive

Un fichier de déclaration regroupe toutes lesdeclaredéclarations dans un seul fichier séparé, et tout fichier TypeScript du projet peut y faire référence.

Conventions de nommage des fichiers

Les fichiers de déclaration utilisent uniformément.d.tscomme suffixe,dqui signifie déclaration. Par exemple :

example.d.ts

Syntaxe de base

La syntaxe pour déclarer un module est la suivante :

declare module Module_Name {
}

Dans un fichier TypeScript, utilisez la directive triple-slash pour inclure le fichier de déclaration :

/// <reference path = "example.d.ts" />

La directive triple-slash est une syntaxe propre à TypeScript utilisée pour indiquer au compilateur d'inclure le fichier de déclaration spécifié lors de la compilation.

Les fichiers de déclaration de nombreuses bibliothèques tierces populaires (telles que jQuery, Lodash) sont déjà maintenus par la communauté et stockés dansDefinitelyTypedle projet. Il vous suffit d'installer le paquet correspondant@types/xxxvia npm et vous pouvez l'utiliser sans l'écrire manuellement.


Exemple complet : création de fichiers de déclaration à partir de zéro

L'exemple complet suivant illustre l'ensemble du processus de création et d'utilisation d'un fichier de déclaration.

L'ensemble du processus implique les fichiers suivants :

FichierObjectif
CalcThirdPartyJsLib.jsBibliothèque JavaScript tierce (JS pur, sans informations de type)
Calc.d.tsFichier de déclaration (écrit manuellement, décrit les types de la bibliothèque)
CalcTest.tsCode métier TypeScript (référence le fichier de déclaration, appelle la bibliothèque)
CalcTest.jsSortie compilée (fichier JS compilé par tsc)
example.htmlPage finale en cours d'exécution dans le navigateur

Étape 1 : Créer la bibliothèque JavaScript tierce

Supposons que nous ayons une bibliothèque tierce qui fournit une fonctionnalité de sommation cumulative. Elle utilise l'espace de nomsExamplepour organiser le code et éviter les conflits de noms de variables :

Code du fichier CalcThirdPartyJsLib.js :

// Chemin du fichier : CalcThirdPartyJsLib.js
// Ceci est une bibliothèque JavaScript tierce simulée

// Déclarer la variable d'espace de noms Example (créer un objet vide s'il n'existe pas)
var Example;

// Utiliser une expression de fonction immédiatement invoquée (IIFE) pour encapsuler le code et empêcher les variables internes de fuir vers la portée globale
(function(Exemple) {
    // Constructeur Calc, utilisé pour créer des objets de calculatrice
    var Calc = (function () {
        function Calc() {
            // Aucun paramètre d'initialisation n'est nécessaire pour le moment ; conservez le constructeur pour une extension future
        }
    })

    // méthode doSum : calcule la somme de tous les entiers de 0 à limit
    // limit (obligatoire) : la borne supérieure de la somme, incluse
    // Exemple : lorsque limit=10, calcule 0+1+2+...+10 = 55
    Calc.prototype.doSum = function (limit) {
        var sum = 0;

        for (var i = 0; i <= limit; i++) {
            sum = sum + i;
        }
        return sum;
    }

    // Attachez le constructeur Calc à l'espace de noms Example
    // Ainsi, l'extérieur peut créer des instances via new Example.Calc()
    Example.Calc = Calc;
    return Calc;
})(Example || (Example = {}));

// Code d'auto-test interne de la bibliothèque
var test = new Example.Calc();

Cette bibliothèque utilise un modèle courant : l'expression de fonction immédiatement invoquée (IIFE). En termes simples, elle enveloppe le code dans une fonction et l'exécute immédiatement, de sorte que les variables définies à l'intérieur de la fonction ne fuient pas, évitant ainsi les conflits de noms avec d'autres codes.

Étape 2 : Écrire le fichier de déclaration

Maintenant, nous avons une bibliothèque JS, mais elle n'a aucune information de type. Nous devons créer un fichier de déclaration qui décrit uniquement la « forme » de la bibliothèque—quelles classes il y a, quelles méthodes il y a, quels sont les types des paramètres et des valeurs de retour—mais ne contient aucune logique de code réelle :

Code du fichier Calc.d.ts :

// Chemin du fichier : Calc.d.ts
// Ceci est un fichier de déclaration ; il contient uniquement des informations de type, et non du code exécutable

// Déclare le module Example, correspondant à l'espace de noms Example dans la bibliothèque JS
declare module Example {
   // Déclare la classe Calc, indiquant à TypeScript que cette classe peut être instanciée avec new
   export class Calc {
      // Déclare la méthode doSum : prend un paramètre number et renvoie un number
      // Remarque : seule la signature de la méthode est déclarée ici, sans corps de méthode (accolades)
      doSum(limit: number): number;
   }
}

La plus grande différence entre un fichier de déclaration et un fichier .ts normal : un fichier de déclaration ne contient que des signatures de type, pas de code d'implémentation. Il répond seulement à « à quoi ressemble cette fonction », pas à « ce que fait cette fonction ».

Étape 3 : Utilisez-le dans du code TypeScript

Écrivez maintenant le code métier. Après avoir référencé le fichier de déclaration, vous pouvez utiliser cette bibliothèque JS tierce comme une bibliothèque TypeScript native :

Code du fichier CalcTest.ts :

// Chemin du fichier : CalcTest.ts
// Directive triple slash : indique au compilateur TypeScript d'inclure le fichier de déclaration
/// <reference path = "Calc.d.ts" />

// Créez une instance de Calc ; TypeScript peut maintenant identifier correctement le type de obj
var obj = new Example.Calc();

// obj.doSum("Hello"); // Erreur de compilation ! "Hello" est une chaîne, mais doSum exige un argument de type number
console.log(obj.doSum(10)); // Appel correct : passer 10, en attendant 55

Faites attention à cette ligne commentée :

obj.doSum("Hello");

Si vous décommentez cette ligne, TypeScript signalera une erreur lors de la compilation, car le fichier de déclaration spécifie déjà que doSum n'accepte qu'un paramètre de type number. C'est la vérification de type qui vous protège : les erreurs sont exposées pendant l'écriture du code, au lieu de provoquer un plantage à l'exécution dans le navigateur.

Étape 4 : Compiler TypeScript

Utilisez la commande intégréetscpour compiler :

tsc CalcTest.ts

Après la compilation, il générera le fichierCalcTest.js, avec le contenu suivant :

Sortie compilée de CalcTest.js :

// Chemin du fichier : CalcTest.js (généré automatiquement par la commande tsc)
/// <reference path = "Calc.d.ts" />
var obj = new Example.Calc();
//obj.doSum("Hello"); // Erreur de compilation
console.log(obj.doSum(10)); // Sortie : affiche 55 dans la console

On peut voir que les directives triple-slash et les informations de type dans les fichiers de déclaration ont disparu de la sortie compilée, ne laissant que du code d'exécution JavaScript pur.

Étape 5 : Exécuter dans le navigateur

Enfin, créez une page HTML pour lier tous les fichiers JS ensemble :

Exemple

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Tutoriel d'exemple (example.com)</title>
<!-- Étape 1 : Chargez la bibliothèque tierce pour rendre l'espace de noms Example globalement disponible -->
<script src = "CalcThirdPartyJsLib.js"></script>
<!-- Étape 2 : Chargez le code métier compilé -->
<script src = "CalcTest.js"></script>
</head>
<body>
    <h1>Test du fichier de déclaration</h1>
    <p>Essayons.</p>
</body>
</html>

Ouvrez ce fichier HTML dans un navigateur, ouvrez la console (F12), et vous pouvez voir la sortie :

55

Voici la valeur de retour de doSum(10) : 0+1+2+...+10 = 55.

声明文件测试结果


Résumé

Un fichier de déclaration est essentiellement un « manuel de types » qui permet à TypeScript de comprendre et de vérifier des bibliothèques JavaScript pures.

L'ensemble du flux de travail peut être résumé en trois étapes :

1. Obtenez une bibliothèque JS et analysez quelles API elle expose.

2. Écrivez.d.tsun fichier de déclaration, décrivant les signatures de type de ces API.

3. Référencez le fichier de déclaration dans le code TypeScript pour bénéficier d'une protection complète de vérification des types.

Pour les bibliothèques tierces couramment utilisées dans le développement quotidien, la grande majorité dispose déjà de fichiers de déclaration prêts à l'emploi (installés vianpm install @types/xxx). Ce n'est que lorsque vous utilisez une bibliothèque très obscure ou une bibliothèque privée interne que vous devez écrire manuellement des fichiers de déclaration.

Autres extensions