Um eine in JavaScript geschriebene Bibliothek in TypeScript-Projekten
effektiv zu nutzen, sind Deklarationsdateien (*.d.ts)
unerlässlich. Diese Dateien beschreiben die Typen und Strukturen, die
Ihre JavaScript-Bibliothek zur Verfügung stellt.
Angenommen, Sie haben eine JavaScript-Bibliothek
MyLibrary.js. Die entsprechende Deklarationsdatei
MyLibrary.d.ts könnte so aussehen:
// MyLibrary.d.ts
declare class MyLibrary {
sayHello(name: string): string;
}Echte Bibliotheken können komplexere Strukturen beinhalten. Zum Beispiel:
// Erweiterte MyLibrary.d.ts
declare module "MyLibrary" {
export interface SomeInterface {
someProperty: number;
}
export class SomeClass {
constructor(option: SomeInterface);
someMethod(option?: number): void;
}
export function someFunction(callback: (e: Error, result: string) => void): void;
}Hier werden verschiedene Konzepte wie Module, Interfaces, optionale Parameter und Callback-Funktionen demonstriert.
Für Bibliotheken, die in TypeScript geschrieben sind, können
Deklarationsdateien automatisch mit tsc --declaration
generiert werden. Dies spart Zeit und reduziert menschliche Fehler.
In d.ts-Dateien können Sie externe Typen
importieren:
/// <reference types="some-other-library" />
declare module "MyLibrary" {
import { OtherLibraryType } from "some-other-library";
export class SomeClass {
// Verwendung von OtherLibraryType
}
}Für umfangreiche Bibliotheken sollten Sie Ihre Deklarationsdateien sorgfältig organisieren. Teilen Sie sie in mehrere Dateien auf, wenn Ihre Bibliothek aus mehreren Modulen oder Komponenten besteht.
Beim Erstellen von Deklarationsdateien können Fehler auftreten. Überprüfen Sie die Typzuweisungen sorgfältig und testen Sie die Deklarationen in einer TypeScript-Umgebung, um sicherzustellen, dass sie korrekt sind.
package.jsonUm Ihre Deklarationsdateien mit Ihrer Bibliothek zu verteilen,
verweisen Sie auf sie im types oder typings
Feld Ihrer package.json:
{
"name": "MyLibrary",
"version": "1.0.0",
"main": "MyLibrary.js",
"types": "MyLibrary.d.ts"
}TypeScript wird diese Dateien automatisch finden und verwenden, wenn Ihre Bibliothek in ein Projekt importiert wird.
Die Erstellung von TypeScript-Deklarationsdateien
(.d.ts) für eine existierende JavaScript-Bibliothek kann
ein manueller oder teilweise automatisierter Prozess sein. Hier sind
einige praktische Schritte und Tools, die dabei helfen können:
.d.ts-Datei, in der Sie die grundlegenden
Strukturen Ihrer Bibliothek deklarieren. Definieren Sie die öffentlichen
Funktionen, Klassen, und vielleicht auch globale Variablen oder
Typen.dts-gen an, das helfen kann, eine Basis-Deklarationsdatei
zu generieren. Dieses Tool erstellt eine erste .d.ts-Datei,
die dann manuell angepasst werden muss.
npm install -g dts-gendts-gen --module my-module-name
aus, um eine Grundstruktur für Ihre Bibliothek zu erhalten.JSDoc Kommentare
verwendet, können Sie den TypeScript-Compiler (tsc) mit der
--declaration-Flagge nutzen, um Deklarationsdateien zu
generieren.types oder typings Feld Ihrer
package.json referenziert wird.Die Erstellung von Deklarationsdateien kann je nach Komplexität der Bibliothek zeitaufwendig sein, aber sie ist ein wichtiger Schritt, um Ihre JavaScript-Bibliothek in TypeScript-Projekten nutzbar und sicher zu machen.
Lassen Sie uns durch ein konkretes Beispiel gehen, um zu zeigen, wie
man eine einfache JavaScript-Bibliothek erstellt und dann eine
zugehörige TypeScript-Deklarationsdatei (d.ts)
erstellt.
Zuerst erstellen wir eine kleine JavaScript-Bibliothek. Nehmen wir an, unsere Bibliothek hat eine Funktion, die eine Zahl nimmt und ihre Quadratwurzel zurückgibt:
MyMathLibrary.js:
// Eine einfache JavaScript-Funktion
function sqrt(number) {
if (number < 0) {
throw new Error("Negative Zahlen sind nicht erlaubt.");
}
return Math.sqrt(number);
}
module.exports = { sqrt };Jetzt erstellen wir eine Deklarationsdatei, die den Typ der
sqrt-Funktion beschreibt.
MyMathLibrary.d.ts:
// Deklarationsdatei für die MyMathLibrary
declare module "MyMathLibrary" {
/**
* Berechnet die Quadratwurzel einer Zahl.
* @param number Die Zahl, für die die Quadratwurzel berechnet wird.
* @returns Die Quadratwurzel der Zahl.
* @throws {Error} Wenn die Zahl negativ ist.
*/
export function sqrt(number: number): number;
}In dieser Deklarationsdatei haben wir den Typ des Parameters
(number) und den Rückgabetyp (number) für die
sqrt-Funktion definiert. Wir haben auch eine Dokumentation
hinzugefügt, die den Fehlerfall beschreibt.
Um die Bibliothek in einem TypeScript-Projekt zu verwenden, stellen
Sie sicher, dass sowohl die .js- als auch die
.d.ts-Datei im Projektverzeichnis oder in einem
zugänglichen node_modules-Verzeichnis liegen.
Sie können dann die Bibliothek in Ihrem TypeScript-Code importieren und verwenden:
main.ts:
import { sqrt } from "MyMathLibrary";
try {
console.log(sqrt(16)); // 4
console.log(sqrt(-1)); // Wird einen Fehler werfen
} catch (error) {
console.error(error.message);
}Wenn Sie Ihre Bibliothek und die Deklarationsdatei verteilen möchten,
stellen Sie sicher, dass Sie beide Dateien in Ihrem Paket einschließen.
Aktualisieren Sie Ihre package.json, um auf die
Deklarationsdatei zu verweisen:
package.json:
{
"name": "MyMathLibrary",
"version": "1.0.0",
"main": "MyMathLibrary.js",
"types": "MyMathLibrary.d.ts"
}Dieses einfache Beispiel zeigt, wie eine Deklarationsdatei für eine bestehende JavaScript-Bibliothek manuell erstellt wird. In komplexeren Fällen müssen Sie möglicherweise fortgeschrittenere Funktionen von TypeScript verwenden, um alle Aspekte Ihrer Bibliothek genau zu beschreiben.