Geheimnisse von *.d.ts: Wie TypeScript fremden Code sieht

Einleitung: Warum Ihr Code mit lodash „befreundet“ ist?

Haben Sie sich jemals gefragt, wie TypeScript die Typen für eine gewöhnliche JavaScript-Bibliothek wie lodash oder jQuery kennt? Sie schreiben einfach import _ from 'lodash', und plötzlich haben Sie Autovervollständigung und Typprüfung. Magie? Nein, das ist die Arbeit der geheimnisvollen Dateien *.d.ts.

Auf Stack Overflow hat die Frage „About \"*.d.ts\" in TypeScript“ tausende Aufrufe erhalten – Entwickler wollen verstehen, was sich hinter dieser Erweiterung verbirgt. Heute werfen wir einen Blick unter die Haube von TypeScript und analysieren, wie Typdeklarationen funktionieren. Sie erfahren nicht nur die Theorie, sondern erhalten auch praktische Beispiele, die Ihnen helfen, eigene Typen für beliebige JavaScript-Projekte zu erstellen.

Was ist .d.ts eigentlich?

Dateien mit der Erweiterung .d.ts sind TypeScript-Deklarationsdateien. Sie enthalten nur Typbeschreibungen, aber keine Implementierung. Betrachten Sie sie als einen „Vertrag“: TypeScript sieht sich diese Datei an und versteht, welche Funktionen, Klassen und Variablen existieren und welche Typen sie haben.

Der Hauptunterschied zu normalen .ts-Dateien: .d.ts wird nicht in JavaScript kompiliert. Sie existieren nur für die statische Analyse und Autovervollständigung.

// myLibrary.d.tsexport function greet(name: string): void;export const VERSION: string;

Wenn Sie diese Bibliothek nun importieren, weiß TypeScript: greet akzeptiert einen String und gibt nichts zurück, und VERSION ist ein String. Ohne diese Datei würden Sie den Fehler „Could not find a declaration file for module“ erhalten.

Wie findet TypeScript .d.ts?

Der Suchmechanismus für Deklarationen erfolgt in mehreren Schritten:

• Automatische Suche: Wenn neben einer .js-Datei eine .d.ts-Datei mit demselben Namen liegt, wird TypeScript sie automatisch übernehmen.
• Das Feld types oder typings in package.json: Viele Bibliotheken geben den Pfad zu ihrer Deklarationsdatei an. Zum Beispiel: "types": "./lib/index.d.ts".
• Die Direktive /// <reference path="" />: Manuelle Angabe einer Deklarationsdatei (veraltete, aber noch vorkommende Methode).
• @types-Pakete: Wenn eine Bibliothek keine eigenen Typen enthält, veröffentlicht die Community sie auf npm unter dem Namen @types/Bibliotheksname.

Wenn Sie npm install @types/react ausführen, laden Sie genau eine Sammlung von .d.ts-Dateien herunter, die React beschreiben.

Unter der Haube: Wie TypeScript .d.ts verarbeitet

Stellen wir uns vor, TypeScript sei ein Detektiv, der den „Fall der Typen“ untersucht. Die .d.ts-Dateien sind die Zeugenaussagen. Sie sagen: „Hier ist die Funktion add, sie akzeptiert zwei Zahlen und gibt eine Zahl zurück.“ TypeScript glaubt diesen Aussagen und überprüft nicht, ob sie tatsächlich stimmen (da es keine Implementierung gibt).

Ambient Declarations (Umgebungsdeklarationen)

Eine der leistungsstärksten Funktionen von .d.ts ist die Deklaration von Ambient Modules. Damit können Sie Typen für Module beschreiben, die nicht in Ihrem Code vorhanden sind. Zum Beispiel möchten Sie die globale Variable $ von jQuery verwenden:

// globals.d.tsdeclare var $: (selector: string) => any;

Oder ein ganzes Modul beschreiben:

// my-custom-module.d.tsdeclare module 'my-custom-module' {    export function doSomething(x: number): string;    export interface Config {        timeout: number;    }}

Jetzt können Sie import { doSomething } from 'my-custom-module' schreiben – und TypeScript kennt die Typen.

Globale Typen vs. Modultypen

Ein wichtiger Unterschied: .d.ts-Dateien können entweder global sein (wenn sie kein import/export enthalten) oder modular (wenn sie eines enthalten). Globale Deklarationen sind sichtbar