Über "*.d.ts" in TypeScript

Question

Ich bin neugierig auf .d.ts Deklarationsdateien, weil ich neu in der TypeScript-Programmiersprache bin. Mir wurde von jemandem gesagt, dass .d.ts Dateien ähnlich sind wie .h Headerdateien in den C & C++ Programmiersprachen, jedoch scheinen die .d.ts Dateien nicht ganz gleich zu funktionieren. Derzeit verstehe ich nicht, wie man die .d.ts Dateien korrekt benutzen kann. Es scheint, als ob ich meine .js oder .ts Dateien nicht zu den .d.ts Dateien hinzufügen kann, daher wird mein Projekt nur funktionieren, wenn es alle drei Dateitypen enthält. Das scheint mir viele Dateien zu sein. Um mir besser zu helfen zu verstehen, wie die .d.ts Dateien mit JavaScript & TypeScript zusammenhängen, habe ich einige Fragen, die ich gerne stellen würde.

---

1. Was ist die Beziehung zwischen den drei Dateien?

2. Wie kann ich die *.d.ts Datei verwenden, bedeutet das, dass ich die *.ts Datei dauerhaft löschen kann?

3. Wenn ja, wie kann die *.d.ts Datei wissen, welche JS-Datei sich auf sie bezieht?

---

Es wäre sehr nett, wenn mir jemand ein Beispiel geben könnte.

Answer 1

Diese Antwort nimmt an, dass Sie einige JavaScript haben, das Sie nicht in TypeScript konvertieren möchten, aber Sie möchten von der Typenüberprüfung mit minimalen Änderungen an Ihrer .js profitieren. Eine .d.ts-Datei ist sehr ähnlich wie eine C- oder C++-Headerdatei. Ihr Zweck ist es, eine Schnittstelle zu definieren. Hier ist ein Beispiel:

mashString.d.ts

/** Macht einen String schwerer lesbar. */
declare function mashString(
    /** Der zu verschleiernde String */
    str: string
):string;
export = mashString;

mashString.js

// @ts-check
/** @type {import("./mashString")} */
module.exports = (str) => [...str].reverse().join("");

main.js

// @ts-check
const mashString = require("./mashString");
console.log(mashString("12345"));

Die Beziehung hier ist: mashString.d.ts definiert eine Schnittstelle, mashString.js implementiert die Schnittstelle und main.js verwendet die Schnittstelle.

Um die Typenüberprüfung zum Laufen zu bringen, fügen Sie // @ts-check zu Ihren .js-Dateien hinzu. Aber dies überprüft nur, ob main.js die Schnittstelle korrekt verwendet. Um auch sicherzustellen, dass mashString.js diese korrekt implementiert, fügen wir /** @type {import("./mashString")} */ vor dem Export hinzu.

Sie können Ihre anfänglichen .d.ts-Dateien mit tsc -allowJs main.js -d erstellen und sie dann manuell bearbeiten, um die Typenüberprüfung und Dokumentation zu verbessern.

In den meisten Fällen haben die Implementierung und die Schnittstelle denselben Namen, hier mashString. Aber Sie können alternative Implementierungen haben. Zum Beispiel könnten wir mashString.js in reverse.js umbenennen und eine alternative encryptString.js haben.

Answer 2

Aus der offiziellen Dokumentation (https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#dts-files):

.d.ts Dateien sind Deklarationsdateien, die nur Typinformationen enthalten. Diese Dateien erzeugen keine .js Ausgaben; sie werden nur zum Typenchecken verwendet.

Answer 3

Ich denke, ich könnte hier meine Gedanken hinzufügen

// somefile.d.ts
export type SomeItem = {
  weight: number
}

export type ItemStorage = {
  name: string
  items: SomeItem[]
}

// somefile.js
// @ts-check
/** @typedef { import('./somefile.d.ts').SomeItem } SomeItem */
/** @typedef { import('./somefile.d.ts').ItemStorage } ItemStorage */

/**
 * @param { StorageItem } item
 */
function doSomething(item) {
  item. // intellisense
  // your code here
}

Das Gute daran ist, dass man allmählich Typen in ein vorhandenes JavaScript-Projekt integrieren kann.

Answer 4

Da der Quellcode die endgültige Wahrheit ist. Hier scheint die Implementierung dafür zu sein:

/*
 * Jede Art von Modulauflösung hat ihr spezifisches Verständnis, wie ein Modul aus einem bestimmten Pfad auf der Festplatte geladen werden soll
 * z.B. für den Pfad '/a/b/c':
 * - Der Node-Loader wird zuerst versuchen zu überprüfen, ob '/a/b/c' auf eine Datei mit einer unterstützten Erweiterung verweist, und wenn dies fehlschlägt
 * wird versucht, das Modul aus dem Verzeichnis zu laden: das Verzeichnis '/a/b/c' sollte existieren und entweder 'package.json' mit
 * 'typings'-Eintrag oder die Datei 'index' mit einer unterstützten Erweiterung haben
 * - Der klassische Loader wird versuchen, '/a/b/c' nur als Datei zu interpretieren.
 */
type ResolutionKindSpecificLoader = (extensions: Extensions, candidate: string, onlyRecordFailures: boolean, state: ModuleResolutionState) => Resolved | undefined;

und

/**
 * Arten von Dateien, die wir derzeit suchen.
 */
const enum Extensions {
    TypeScript  = 1 << 0, // '.ts', '.tsx', '.mts', '.cts'
    JavaScript  = 1 << 1, // '.js', '.jsx', '.mjs', '.cjs'
    Declaration = 1 << 2, // '.d.ts', etc.
    Json        = 1 << 3, // '.json'

    ImplementationFiles = TypeScript | JavaScript,
}

Die vollständige Datei befindet sich unter https://github.com/microsoft/TypeScript/blob/main/src/compiler/moduleNameResolver.ts.

Answer 5

Zum Beispiel haben Sie das Problem, das Modul 'alertifyjs' aus npm zu verwenden.

1. Erstellen Sie 'beliebigenNamen.d.ts' (z. B. haben Sie diese Datei im src-Ordner erstellt)
2. In der Datei declare module 'alertifyjs'; Bildbeschreibung hier eingeben
3. in tsconfig.json Unter "compilerOptions" "typeRoots": ["node_modules/@types", "src/beliebigenNamen.d.ts"]