TypeScriptInterfaces et classes

declare et les fichiers .d.ts

Décrire les types de quelque chose qui existe hors de votre code TypeScript : variables globales, bibliothèques JavaScript et modules.

Sur cette page

Exemple
Définition et utilisation
Syntaxe
Types de déclarations
Plus d’exemples
Bonnes pratiques
Entrées associées

Exemple

TypeScript

// src/types/globals.d.ts
declare const APP_VERSION: string
declare function trackEvent(name: string, data?: Record<string, unknown>): void

// src/lesson.ts
trackEvent('lesson_completed', { lesson: 'flexbox', version: APP_VERSION })

trackEvent(42)
// Erreur : Argument of type 'number' is not assignable to parameter of type 'string'.

La valeur APP_VERSION est insérée par le bundler pendant la construction, et la fonction trackEvent est ajoutée par un script d’analytique inclus dans la page. Le compilateur ne les connaît que grâce aux déclarations.

Définition et utilisation

Le mot-clé declare indique au compilateur que quelque chose existe, même si cela n’a pas été défini à cet endroit : une variable injectée par un autre script de la page, une fonction d’une bibliothèque écrite en JavaScript, ou un module entier. La déclaration décrit seulement le type et disparaît après compilation, elle ne crée aucun code.

Les fichiers avec l’extension .d.ts ne contiennent que ce genre de descriptions, sans implémentation. Le compilateur les génère à partir de votre code avec l’option declaration, et les auteurs de bibliothèques les incluent dans leurs paquets npm. Pour les paquets sans types propres, il existe des paquets @types/… du dépôt DefinitelyTyped, par exemple @types/lodash.

Dans votre propre projet, un fichier .d.ts est utile pour décrire des variables globales, étendre des types intégrés avec declare global, et importer des fichiers qui ne sont pas du code, par exemple declare module "*.svg". Le fichier doit être couvert par include dans tsconfig.json, sinon le compilateur ne le verra pas.

Syntaxe

declare const name: type
declare function name(param: type): type
declare module "package" { … }
declare global { … }

Types de déclarations

declare const
Une variable globale, par exemple injectée par un bundler ou un script inclus dans la page. À la place de const, vous pouvez utiliser let ou var.
declare function
Une fonction disponible globalement. Vous pouvez donner plusieurs signatures, tout comme avec les surcharges.
declare class
Une classe définie hors de TypeScript, par exemple dans une bibliothèque plus ancienne.
declare module
Les types d’un module entier : un paquet npm ("legacy-charts") ou un motif de fichiers ("*.svg").
declare global
Ajoute des déclarations à la portée globale depuis l’intérieur d’un module, par exemple un nouveau champ sur Window.

Syntaxe	Description
declare const	Une variable globale, par exemple injectée par un bundler ou un script inclus dans la page. À la place de `const`, vous pouvez utiliser `let` ou `var`.
declare function	Une fonction disponible globalement. Vous pouvez donner plusieurs signatures, tout comme avec les surcharges.
declare class	Une classe définie hors de TypeScript, par exemple dans une bibliothèque plus ancienne.
declare module	Les types d’un module entier : un paquet npm (`"legacy-charts"`) ou un motif de fichiers (`"*.svg"`).
declare global	Ajoute des déclarations à la portée globale depuis l’intérieur d’un module, par exemple un nouveau champ sur `Window`.

Plus d’exemples

Types pour un paquet sans types

TypeScript

// src/types/legacy-charts.d.ts
declare module 'legacy-charts' {
  interface ChartOptions {
    title: string
    values: number[]
    color?: string
  }

  export default function drawChart(element: HTMLElement, options: ChartOptions): void
}

// src/progress.ts
import drawChart from 'legacy-charts'

drawChart(document.body, { title: 'Progression' })
// Erreur : Argument of type '{ title: string; }' is not assignable to parameter of type 'ChartOptions'.
//   Property 'values' is missing in type '{ title: string; }' but required in type 'ChartOptions'.

Un nouveau champ sur l’objet window

TypeScript

// src/types/window.d.ts
export {}

declare global {
  interface Window {
    dataLayer: unknown[]
  }
}

// n’importe quel fichier du projet
window.dataLayer.push({ event: 'signup' })

La ligne export {} transforme le fichier en module. Sans elle, le compilateur signale « Augmentations for the global scope can only be directly nested in external modules or ambient module declarations ».

Bonnes pratiques

Avant d’écrire vos propres types pour un paquet, vérifiez si un paquet @types/nom-du-paquet existe. Le message « Could not find a declaration file for module » le suggère généralement de lui-même.
Le raccourci declare module "paquet"; sans corps fait taire l’erreur, mais tout ce qui vient du module reçoit alors le type any. Considérez-le comme une solution temporaire.
declare ne crée rien. Si la variable n’existe vraiment pas dans le programme en cours d’exécution, la compilation réussit, et le programme s’arrête sur une erreur « is not defined ».

Entrées associées

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.

Leçons gratuitesPratiquez TypeScript dans le cours JavaScript et TypeScriptDes exercices avec indices, un éditeur de code et une progression enregistrée au fur et à mesure.Voir le cours