Mr Josselin A - TypeScript










Directives Triple Slash

Parcours & Expérience





Références

L'actualité

Librairie

L'information

Introduction

Les directives à triple barre sont des commentaires d'une seule ligne contenant une seule balise XML. Le contenu du commentaire est utilisé comme directive de compilation.

Les directives à triple barre ne sont valables qu'en haut du fichier qui les contient. Une directive triple barre oblique ne peut être précédée que par des commentaires sur une ou plusieurs lignes, y compris d'autres directives triple barre oblique. S'ils se rencontrent à la suite d'une instruction ou d'une déclaration, ils sont traités comme des commentaires réguliers d'une seule ligne et n'ont aucune signification particulière.

/// ‹reference path="..." /›

La directive /// ‹reference path="..." /› est la plus commune de ce groupe. Il sert de déclaration de dépendance entre fichiers.

Les références en triple barre indiquent au compilateur d'inclure des fichiers supplémentaires dans le processus de compilation.

Ils servent également de méthode pour ordonner la sortie lors de l'utilisation de --out ou --outFile. Les fichiers sont émis à l'emplacement du fichier de sortie dans le même ordre que celui entré après le prétraitement.

Prétraitement des fichiers d'entrée

Le compilateur effectue une passe de prétraitement sur les fichiers d'entrée pour résoudre toutes les directives de référence à triple barre oblique. Au cours de ce processus, des fichiers supplémentaires sont ajoutés à la compilation.

Le processus commence par un ensemble de fichiers racine; Ce sont les noms de fichier spécifiés sur la ligne de commande ou dans la liste "files" du fichier tsconfig.json. Ces fichiers racine sont prétraités dans le même ordre où ils ont été spécifiés. Avant qu'un fichier ne soit ajouté à la liste, toutes les références à triple barre oblique sont traitées et leurs cibles sont incluses. Les références en triple barre oblique sont résolues de manière approfondie en premier lieu, dans l'ordre dans lequel elles ont été vues dans le fichier.

Un chemin de référence à triple barre oblique est résolu par rapport au fichier contenant, s'il n'est pas enraciné.

Les erreurs

C'est une erreur de référencer un fichier qui n'existe pas. C'est une erreur pour un fichier d'avoir une référence triple-slash à lui-même.

En utilisant --noResolve

Si l'indicateur de compilation --noResolve est spécifié, les références à triple barre oblique sont ignorées. ils n'entraînent ni l'ajout de nouveaux fichiers, ni la modification de l'ordre des fichiers fournis.

/// ‹reference types="..." /›

Semblable à une directive /// ‹reference path="..." /› , cette directive sert de déclaration de dépendance; une directive /// ‹reference types="..." /›, cependant, déclare une dépendance à un paquet.

Le processus de résolution de ces noms de package est similaire au processus de résolution des noms de module dans une importinstruction. Un moyen simple de penser aux directives de type référence à trois barres obliques s'applique importaux packages de déclaration.

Par exemple, l'inclusion /// ‹reference types="node" /› dans un fichier de déclaration déclare que ce fichier utilise des noms déclarés dans @types/node/index.d.ts ; et donc, ce paquet doit être inclus dans la compilation avec le fichier de déclaration.

Utilisez ces directives uniquement lorsque vous créez un fichier d.ts à la main.

Pour les fichiers de déclaration générés lors de la compilation, le compilateur ajoutera automatiquement /// ‹reference types="..." /› pour vous; Un /// ‹reference types="..." /› fichier de déclaration généré est ajouté si et seulement si le fichier obtenu utilise une déclaration du package référencé.
Pour déclarer une dépendance à un @typespaqu et dans un fichier .ts, utilisez-le --types sur la ligne de commande ou dans votre tsconfig.json. Voir l'utilisation @types, typeRoots et types dans les fichiers tsconfig.json pour plus de détails.

/// ‹reference lib="..." /›

Cette directive permet à un fichier d'inclure explicitement un fichier lib intégré existant.

Les fichiers lib intégrés sont référencés de la même manière que l'option "lib" du compilateur dans tsconfig.json (par exemple, use lib="es2015" et not lib="lib.es2015.d.ts", etc...).

Pour les auteurs de fichiers de déclaration qui utilisent des types intégrés, par exemple les API DOM ou les constructeurs d'exécution JS intégrés tels que Symbolou Iterable, les directives lib à triple barre oblique sont recommandées. Auparavant, ces fichiers .d.ts devaient ajouter des déclarations en aval / en double de ce type.

Par exemple, ajouter /// ‹reference lib="es2017.string" /› à l'un des fichiers d'une compilation équivaut à compiler avec --lib es2017.string.


/// ‹reference no-default-lib="true"/›

Cette directive marque un fichier comme une bibliothèque par défaut. Vous verrez ce commentaire en haut de lib.d.ts et ses différentes variantes.

Cette directive demande au compilateur de ne pas inclure la bibliothèque par défaut (c'est-à-dire lib.d.ts) dans la compilation. L'impact ici est similaire à celui de passer --noLib sur la ligne de commande.

Notez également que lorsqu'il passe --skipDefaultLibCheck, le compilateur ignore uniquement la vérification des fichiers avec /// ‹reference no-default-lib="true"/›.

/// ‹amd-module /›

Par défaut, les modules AMD sont générés de manière anonyme. Cela peut entraîner des problèmes lorsque d'autres outils sont utilisés pour traiter les modules résultants, tels que des bundles (par exemple r.js).

La directive amd-module permet de passer un nom de module optionnel au compilateur :

amdModule.ts
Cela entraînera l'attribution du nom NamedModule au module dans le cadre de l'appel de AMD define :
amdModule.js

/// ‹amd-dependency /›


Ramarque : cette directive est obsolète. Utilisez des déclarations import "moduleName"; à la place.

/// ‹amd-dependency path="x" /› informe le compilateur d'une dépendance de module non-TS qui doit être injectée dans l'appel requis du module résultant.

La directive amd-dependency peut également avoir une propriété name optionnelle. cela permet de donner un nom optionnel pour une dépendance amd :

Code JS généré :