Arbeiten mit JavaScript

Dieses Thema beschreibt einige der erweiterten JavaScript-Funktionen, die von Visual Studio Code unterstützt werden. Unter Verwendung des TypeScript-Sprachdienstes kann VS Code intelligente Vervollständigungen (IntelliSense) sowie eine Typüberprüfung für JavaScript bereitstellen.

IntelliSense

Das JavaScript-IntelliSense von Visual Studio Code bietet intelligente Codevervollständigung, Parameterinformationen, Referenzsuche und viele weitere erweiterte Sprachfunktionen. Unser JavaScript-IntelliSense wird durch den JavaScript-Sprachdienst angetrieben, der vom TypeScript-Team entwickelt wurde. Während IntelliSense für die meisten JavaScript-Projekte ohne jegliche Konfiguration funktionieren sollte, können Sie IntelliSense mit JSDoc oder durch die Konfiguration eines jsconfig.json-Projekts noch nützlicher machen.

Einzelheiten zur Funktionsweise von JavaScript-IntelliSense, einschließlich der Verwendung von Typinferenz, JSDoc-Annotationen, TypeScript-Deklarationen und der Mischung von JavaScript- und TypeScript-Projekten, finden Sie in der Dokumentation zum JavaScript-Sprachdienst.

Wenn die Typinferenz nicht die gewünschten Informationen liefert, können Typinformationen explizit mit JSDoc-Annotationen angegeben werden. Dieses Dokument beschreibt die aktuell unterstützten JSDoc-Annotationen.

Zusätzlich zu Objekten, Methoden und Eigenschaften bietet das JavaScript-IntelliSense-Fenster auch eine grundlegende Wortvervollständigung für die Symbole in Ihrer Datei.

Typings und automatische Typerfassung (Automatic Type Acquisition)

IntelliSense für JavaScript-Bibliotheken und Frameworks basiert auf TypeScript-Typdeklarationsdateien (Typings). Typdeklarationsdateien sind in TypeScript geschrieben, sodass sie die Datentypen von Parametern und Funktionen ausdrücken können, was es VS Code ermöglicht, eine umfassende IntelliSense-Erfahrung auf performante Weise bereitzustellen.

Viele populäre Bibliotheken werden mit Typings-Dateien ausgeliefert, sodass Sie automatisch IntelliSense für diese erhalten. Für Bibliotheken, die keine Typings enthalten, installiert die automatische Typerfassung (Automatic Type Acquisition) von VS Code automatisch von der Community gepflegte Typings-Dateien für Sie.

Die automatische Typerfassung erfordert npmjs, den Node.js-Paketmanager, der in der Node.js-Laufzeitumgebung enthalten ist. In diesem Bild sehen Sie IntelliSense, einschließlich der Methodensignatur, Parameterinformationen und der Methodendokumentation für die populäre lodash-Bibliothek.

Typdeklarationsdateien werden von Visual Studio Code automatisch heruntergeladen und verwaltet für Pakete, die in der package.json Ihres Projekts aufgeführt sind oder die Sie in eine JavaScript-Datei importieren.

{
  "dependencies": {
    "lodash": "^4.17.0"
  }
}

Alternativ können Sie in einer jsconfig.json explizit Pakete auflisten, für die Typdeklarationsdateien erfasst werden sollen.

{
  "typeAcquisition": {
    "include": ["jquery"]
  }
}

Die meisten gängigen JavaScript-Bibliotheken werden mit Deklarationsdateien ausgeliefert oder verfügen über verfügbare Typdeklarationsdateien.

Behebung der Warnung bei nicht installiertem npm für die automatische Typerfassung

Die automatische Typerfassung verwendet npm, den Node.js-Paketmanager, um Typdeklarationsdateien (Typings) zu installieren und zu verwalten. Um sicherzustellen, dass die automatische Typerfassung ordnungsgemäß funktioniert, stellen Sie zunächst sicher, dass npm auf Ihrem Computer installiert ist.

Führen Sie npm --version in einem Terminal oder einer Eingabeaufforderung aus, um schnell zu überprüfen, ob npm installiert und verfügbar ist.

npm wird mit der Node.js-Laufzeitumgebung installiert, die unter Nodejs.org zum Download bereitsteht. Installieren Sie die aktuelle LTS-Version (Long Term Support), und die npm-Executable wird standardmäßig zu Ihrem Systempfad hinzugefügt.

Wenn npm installiert ist, Sie aber dennoch eine Warnmeldung sehen, können Sie VS Code explizit mitteilen, wo npm installiert ist, indem Sie die js/ts.tsserver.npm.path-Einstellung verwenden. Diese sollte auf den vollständigen Pfad der npm-Executable auf Ihrem Computer festgelegt werden. Dies muss nicht mit der Version von npm übereinstimmen, die Sie zum Verwalten von Paketen in Ihrem Arbeitsbereich verwenden. js/ts.tsserver.npm.path erfordert TypeScript 2.3.4+.

Unter Windows würden Sie beispielsweise einen Pfad wie diesen zu Ihrer settings.json-Datei hinzufügen

{
  "js/ts.tsserver.npm.path": "C:\\Program Files\\nodejs\\npm.cmd"
}

JavaScript-Projekte (jsconfig.json)

Das Vorhandensein einer jsconfig.json-Datei in einem Verzeichnis zeigt an, dass das Verzeichnis die Wurzel eines JavaScript-Projekts ist. jsconfig.json spezifiziert die Wurzeldateien und die Optionen für die Sprachfunktionen, die vom JavaScript-Sprachdienst bereitgestellt werden. Für allgemeine Setups ist eine jsconfig.json-Datei nicht erforderlich, es gibt jedoch Situationen, in denen Sie eine jsconfig.json hinzufügen möchten.

• Nicht alle Dateien sollten in Ihrem JavaScript-Projekt enthalten sein (beispielsweise möchten Sie einige Dateien von der IntelliSense-Anzeige ausschließen). Diese Situation ist bei Front-End- und Back-End-Code häufig.
• Ihr Arbeitsbereich enthält mehr als einen Projektkontext. In diesem Fall sollten Sie im Stammordner jedes Projekts eine jsconfig.json-Datei hinzufügen.
• Sie verwenden den TypeScript-Compiler, um JavaScript-Quellcode für ältere Zielumgebungen (down-level) zu kompilieren.

Speicherort von jsconfig.json

Um unseren Code als JavaScript-Projekt zu definieren, erstellen Sie eine jsconfig.json im Stammverzeichnis Ihres JavaScript-Codes, wie unten dargestellt. Ein JavaScript-Projekt besteht aus den Quelldateien des Projekts und sollte keine abgeleiteten oder paketierten Dateien (wie ein dist-Verzeichnis) enthalten.

In komplexeren Projekten können Sie mehr als eine jsconfig.json-Datei innerhalb eines Arbeitsbereichs definiert haben. Dies ist sinnvoll, damit der Quellcode eines Projekts nicht in der IntelliSense eines anderen Projekts erscheint.

Unten dargestellt ist ein Projekt mit einem client- und server-Ordner, das zwei separate JavaScript-Projekte zeigt

Schreiben der jsconfig.json

Unten finden Sie eine einfache Vorlage für eine jsconfig.json-Datei, die das JavaScript-target auf ES6 festlegt und das exclude-Attribut den node_modules-Ordner ausschließt. Sie können diesen Code kopieren und in Ihre jsconfig.json-Datei einfügen.

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES6"
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

Das exclude-Attribut teilt dem Sprachdienst mit, welche Dateien nicht Teil Ihres Quellcodes sind. Wenn IntelliSense langsam ist, fügen Sie Ordner zu Ihrer exclude-Liste hinzu (VS Code fordert Sie dazu auf, wenn langsame Vervollständigungen erkannt werden). Sie sollten Dateien excluden, die durch einen Build-Prozess generiert wurden (z. B. ein dist-Verzeichnis). Diese Dateien führen dazu, dass Vorschläge doppelt angezeigt werden und IntelliSense verlangsamen.

Sie können die Dateien in Ihrem Projekt explizit mit dem include-Attribut festlegen. Wenn kein include-Attribut vorhanden ist, werden standardmäßig alle Dateien im enthaltenden Verzeichnis und dessen Unterverzeichnissen einbezogen. Wenn ein include-Attribut angegeben ist, werden nur diese Dateien einbezogen.

Hier ist ein Beispiel mit einem expliziten include-Attribut

{
  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES6"
  },
  "include": ["src/**/*"]
}

Der bewährte und am wenigsten fehleranfällige Weg ist die Verwendung des include-Attributs mit einem einzelnen src-Ordner. Beachten Sie, dass Dateipfade in exclude und include relativ zum Speicherort der jsconfig.json sind.

Weitere Informationen finden Sie in der vollständigen jsconfig.json-Dokumentation.

Migration zu TypeScript

Es ist möglich, gemischte TypeScript- und JavaScript-Projekte zu haben. Um mit der Migration zu TypeScript zu beginnen, benennen Sie Ihre jsconfig.json-Datei in tsconfig.json um und setzen Sie die allowJs-Eigenschaft auf true. Weitere Informationen finden Sie unter Migration von JavaScript.

Hinweis: jsconfig.json ist identisch mit einer tsconfig.json-Datei, nur dass allowJs auf true gesetzt ist. Weitere verfügbare Optionen finden Sie in der Dokumentation zu tsconfig.json hier.

JavaScript-Typüberprüfung

VS Code ermöglicht es Ihnen, einige der erweiterten Typüberprüfungs- und Fehlerbericht-Funktionen von TypeScript in regulären JavaScript-Dateien zu nutzen. Dies ist eine hervorragende Möglichkeit, häufige Programmierfehler abzufangen. Diese Typüberprüfungen ermöglichen auch einige spannende Schnellkorrekturen (Quick Fixes) für JavaScript, einschließlich Fehlenden Import hinzufügen und Fehlende Eigenschaft hinzufügen.

TypeScript kann Typen in .js-Dateien genauso wie in .ts-Dateien ableiten. Wenn Typen nicht abgeleitet werden können, können sie mithilfe von JSDoc-Kommentaren angegeben werden. Sie können mehr darüber lesen, wie TypeScript JSDoc für die JavaScript-Typüberprüfung verwendet, unter JavaScript-Dateien typüberprüfen.

Die Typüberprüfung von JavaScript ist optional und opt-in. Bestehende JavaScript-Validierungstools wie ESLint können neben der neuen integrierten Typüberprüfungsfunktion verwendet werden.

Sie können je nach Bedarf auf verschiedene Weise mit der Typüberprüfung beginnen.

Pro Datei

Der einfachste Weg, die Typüberprüfung in einer JavaScript-Datei zu aktivieren, ist das Hinzufügen von // @ts-check am Anfang einer Datei.

// @ts-check
let itsAsEasyAs = 'abc';
itsAsEasyAs = 123; // Error: Type '123' is not assignable to type 'string'

Die Verwendung von // @ts-check ist ein guter Ansatz, wenn Sie die Typüberprüfung nur in einigen wenigen Dateien ausprobieren möchten, aber noch nicht für eine gesamte Codebasis aktivieren wollen.

Verwendung einer Einstellung

Um die Typüberprüfung für alle JavaScript-Dateien zu aktivieren, ohne Code zu ändern, fügen Sie einfach "js/ts.implicitProjectConfig.checkJs": true zu Ihren Arbeitsbereichs- oder Benutzereinstellungen hinzu. Dies aktiviert die Typüberprüfung für jede JavaScript-Datei, die nicht Teil eines jsconfig.json- oder tsconfig.json-Projekts ist.

Sie können einzelne Dateien von der Typüberprüfung ausschließen, indem Sie einen // @ts-nocheck-Kommentar am Anfang der Datei einfügen.

// @ts-nocheck
let easy = 'abc';
easy = 123; // no error

Sie können auch einzelne Fehler in einer JavaScript-Datei deaktivieren, indem Sie einen // @ts-ignore-Kommentar in der Zeile vor dem Fehler verwenden.

let easy = 'abc';
// @ts-ignore
easy = 123; // no error

Verwendung von jsconfig oder tsconfig

Um die Typüberprüfung für JavaScript-Dateien zu aktivieren, die Teil einer jsconfig.json oder tsconfig.json sind, fügen Sie "checkJs": true zu den Compiler-Optionen des Projekts hinzu.

jsconfig.json:

{
  "compilerOptions": {
    "checkJs": true
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  },
  "exclude": ["node_modules", "**/node_modules/*"]
}

Dies aktiviert die Typüberprüfung für alle JavaScript-Dateien im Projekt. Sie können // @ts-nocheck verwenden, um die Typüberprüfung pro Datei zu deaktivieren.

Die JavaScript-Typüberprüfung erfordert TypeScript 2.3. Wenn Sie nicht sicher sind, welche Version von TypeScript derzeit in Ihrem Arbeitsbereich aktiv ist, führen Sie den Befehl TypeScript: TypeScript-Version auswählen aus. Sie müssen eine .js/.ts-Datei im Editor geöffnet haben, um diesen Befehl ausführen zu können. Wenn Sie eine TypeScript-Datei öffnen, wird die Version in der unteren rechten Ecke angezeigt.

Globale Variablen und Typüberprüfung

Nehmen wir an, Sie arbeiten in Legacy-JavaScript-Code, der globale Variablen oder nicht-standardisierte DOM-APIs verwendet.

window.onload = function() {
  if (window.webkitNotifications.requestPermission() === CAN_NOTIFY) {
    window.webkitNotifications.createNotification(null, 'Woof!', '🐶').show();
  } else {
    alert('Could not notify');
  }
};

Wenn Sie versuchen, // @ts-check mit dem obigen Code zu verwenden, sehen Sie eine Reihe von Fehlern bezüglich der Verwendung globaler Variablen.

1. Zeile 2 - Eigenschaft 'webkitNotifications' existiert nicht auf dem Typ 'Window'.
2. Zeile 2 - Name 'CAN_NOTIFY' kann nicht gefunden werden.
3. Zeile 3 - Eigenschaft 'webkitNotifications' existiert nicht auf dem Typ 'Window'.

Wenn Sie // @ts-check weiterhin verwenden möchten, aber sicher sind, dass dies keine tatsächlichen Probleme mit Ihrer Anwendung sind, müssen Sie TypeScript über diese globalen Variablen informieren.

Erstellen Sie zunächst eine jsconfig.json im Stammverzeichnis Ihres Projekts.

{
  "compilerOptions": {},
  "exclude": ["node_modules", "**/node_modules/*"]
}

Laden Sie dann VS Code neu, um sicherzustellen, dass die Änderung übernommen wird. Das Vorhandensein einer jsconfig.json teilt TypeScript mit, dass Ihre Javascript-Dateien Teil eines größeren Projekts sind.

Erstellen Sie nun eine globals.d.ts-Datei an einer beliebigen Stelle in Ihrem Arbeitsbereich.

interface Window {
  webkitNotifications: any;
}

declare var CAN_NOTIFY: number;

d.ts-Dateien sind Typdeklarationen. In diesem Fall teilt globals.d.ts TypeScript mit, dass eine globale CAN_NOTIFY existiert und dass eine webkitNotifications-Eigenschaft auf window existiert. Sie können mehr über das Schreiben von d.ts in der TypeScript-Dokumentation lesen. d.ts-Dateien ändern nicht, wie JavaScript ausgewertet wird; sie dienen nur dazu, eine bessere JavaScript-Sprachunterstützung bereitzustellen.

Verwendung von Tasks

Verwendung des TypeScript-Compilers

Eines der Hauptmerkmale von TypeScript ist die Möglichkeit, neueste JavaScript-Sprachfunktionen zu verwenden und Code zu generieren, der in JavaScript-Laufzeitumgebungen ausgeführt werden kann, die diese neueren Funktionen noch nicht verstehen. Da JavaScript denselben Sprachdienst verwendet, kann es nun ebenfalls von dieser Funktion profitieren.

Der TypeScript-Compiler tsc kann JavaScript-Dateien von ES6 auf eine andere Sprachebene "down-level" kompilieren. Konfigurieren Sie die jsconfig.json mit den gewünschten Optionen und verwenden Sie dann das -p-Argument, damit tsc Ihre jsconfig.json-Datei verwendet, z. B. tsc -p jsconfig.json zum Down-Level-Kompilieren.

Lesen Sie mehr über die Compiler-Optionen für die Down-Level-Kompilierung in der jsconfig-Dokumentation.

Babel ausführen

Der Babel-Transpiler wandelt ES6-Dateien in lesbares ES5-JavaScript mit Source Maps um. Sie können Babel einfach in Ihren Workflow integrieren, indem Sie die unten stehende Konfiguration zu Ihrer tasks.json-Datei (im .vscode-Ordner des Arbeitsbereichs) hinzufügen. Die group-Einstellung macht diesen Task zur Standardgeste für Task: Build-Task ausführen. isBackground teilt VS Code mit, diesen Task im Hintergrund weiter auszuführen. Um mehr zu erfahren, gehen Sie zu Tasks.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "watch",
      "command": "${workspaceFolder}/node_modules/.bin/babel",
      "args": ["src", "--out-dir", "lib", "-w", "--source-maps"],
      "type": "shell",
      "group": { "kind": "build", "isDefault": true },
      "isBackground": true
    }
  ]
}

Sobald Sie dies hinzugefügt haben, können Sie Babel mit dem Befehl ⇧⌘B (Windows, Linux Ctrl+Shift+B) (Build-Task ausführen) starten, und er kompiliert alle Dateien aus dem src-Verzeichnis in das lib-Verzeichnis.

Tipp: Hilfe zum Babel CLI finden Sie in den Anweisungen unter Verwendung von Babel. Das obige Beispiel verwendet die CLI-Option.

JavaScript-Unterstützung deaktivieren

Wenn Sie lieber JavaScript-Sprachfunktionen verwenden möchten, die von anderen JavaScript-Sprachtools wie Flow unterstützt werden, können Sie die integrierte JavaScript-Unterstützung von VS Code deaktivieren. Dies tun Sie, indem Sie die integrierte TypeScript-Spracherweiterung TypeScript and JavaScript Language Features (vscode.typescript-language-features) deaktivieren, die auch die JavaScript-Sprachunterstützung bereitstellt.

Um die JavaScript/TypeScript-Unterstützung zu deaktivieren, gehen Sie zur Erweiterungsansicht (⇧⌘X (Windows, Linux Ctrl+Shift+X)) und filtern Sie nach integrierten Erweiterungen (Integrierte Erweiterungen anzeigen im ... Weitere Aktionen-Dropdown), und geben Sie dann 'typescript' ein. Wählen Sie die Erweiterung TypeScript and JavaScript Language Features und drücken Sie die Schaltfläche Deaktivieren. Integrierte VS Code-Erweiterungen können nicht deinstalliert, sondern nur deaktiviert werden und können jederzeit wieder aktiviert werden.

Partieller IntelliSense-Modus

VS Code versucht, projektweites IntelliSense für JavaScript und TypeScript bereitzustellen, was Funktionen wie Auto-Importe und Gehe zu Definition erst möglich macht. Es gibt jedoch einige Fälle, in denen VS Code darauf beschränkt ist, nur mit Ihren aktuell geöffneten Dateien zu arbeiten, und nicht in der Lage ist, die anderen Dateien zu laden, die Ihr JavaScript- oder TypeScript-Projekt ausmachen.

Dies kann in einigen Fällen vorkommen:

• Sie arbeiten mit JavaScript- oder TypeScript-Code auf vscode.dev oder github.dev und VS Code läuft im Browser.
• Sie öffnen eine Datei aus einem virtuellen Dateisystem (wie bei der Verwendung der GitHub Repositories-Erweiterung).
• Das Projekt wird derzeit geladen. Sobald der Ladevorgang abgeschlossen ist, erhalten Sie projektweites IntelliSense dafür.

In diesen Fällen arbeitet das IntelliSense von VS Code im partiellen Modus. Der partielle Modus versucht sein Bestes, IntelliSense für alle von Ihnen geöffneten JavaScript- oder TypeScript-Dateien bereitzustellen, ist aber eingeschränkt und kann keine dateiübergreifenden IntelliSense-Funktionen anbieten.

Welche Funktionen sind betroffen?

Hier ist eine unvollständige Liste von Funktionen, die im partiellen Modus entweder deaktiviert sind oder eine eingeschränktere Funktionalität aufweisen:

• Alle geöffneten Dateien werden als Teil eines einzelnen Projekts behandelt.
• Konfigurationsoptionen aus Ihrer jsconfig oder tsconfig (wie target) werden nicht berücksichtigt.
• Es werden nur Syntaxfehler gemeldet. Semantische Fehler — wie der Zugriff auf eine unbekannte Eigenschaft oder die Übergabe des falschen Typs an eine Funktion — werden nicht gemeldet.
• Schnellkorrekturen für semantische Fehler sind deaktiviert.
• Symbole können nur innerhalb der aktuellen Datei aufgelöst werden. Alle aus anderen Dateien importierten Symbole werden so behandelt, als hätten sie den Typ any.
• Befehle wie Gehe zu Definition und Alle Referenzen finden funktionieren nur für geöffnete Dateien statt für das gesamte Projekt. Dies bedeutet auch, dass Symbole aus Paketen, die Sie unter node_modules installiert haben, nicht aufgelöst werden.
• Die Arbeitsbereichs-Symbolsuche umfasst nur Symbole aus derzeit geöffneten Dateien.
• Auto-Importe sind deaktiviert.
• Umbenennen ist deaktiviert.
• Viele Refactorings sind deaktiviert.

Einige zusätzliche Funktionen sind auf vscode.dev und github.dev deaktiviert:

• Automatische Typerfassung wird derzeit nicht unterstützt.

Überprüfung, ob Sie sich im partiellen Modus befinden

Um zu überprüfen, ob die aktuelle Datei den partiellen IntelliSense-Modus anstelle des projektweiten IntelliSense verwendet, fahren Sie mit der Maus über das JavaScript- oder TypeScript-Sprachstatus-Element in der Statusleiste.

Das Statuselement zeigt Partieller Modus an, wenn sich die aktuelle Datei im partiellen Modus befindet.