import()

Syntax

import(moduleName)
import(moduleName, options)

Der import()-Aufruf ist eine Syntax, die einem Funktionsaufruf hnelt, jedoch ist import ein Schlsselwort und keine Funktion. Sie knnen es nicht umbenennen, wie const myImport = import, da dies einen SyntaxError auslsen wrde.

Nachgestellte Kommata sind nur erlaubt, wenn die Laufzeit auch options untersttzt. berprfen Sie die Browser-Kompatibilitt.

Parameter

moduleName

Das Modul, von dem importiert werden soll. Die Auswertung des Bezeichners wird hostspezifisch festgelegt, folgt jedoch immer demselben Algorithmus wie bei statischen Import-Deklarationen.

options

Ein Objekt, das Importoptionen enthlt. Der folgende Schlssel wird erkannt:

with

Die Importeigenschaften.

Rckgabewert

Gibt ein Promise zurck, das:

• Wenn das referenzierte Modul erfolgreich geladen und ausgewertet wird, wird es zu einem Modul-Namensraum-Objekt erfllt: einem Objekt, das alle Exporte von moduleName enthlt.
• Wenn die Typumwandlung zu String von moduleName einen Fehler wirft, lehnt es mit dem geworfenen Fehler ab.
• Wenn das Abrufen und Laden des Moduls aus irgendeinem Grund fehlschlgt, lehnt es mit einem implementierungsdefinierten Fehler ab (Node verwendet einen generischen Error, whrend alle Browser TypeError verwenden). Hufige Ursachen knnen sein:
  • In einem dateisystembasierten Modulsystem (z. B. Node.js), wenn der Zugriff auf das Dateisystem fehlschlgt (Berechtigung verweigert, Datei nicht gefunden usw.).
  • In einem webbasierten Modulsystem (z. B. Browser), wenn die Netzwerkabfrage fehlschlgt (keine Verbindung zum Internet, CORS-Problem usw.) oder ein HTTP-Fehler auftritt (404, 500 usw.).
• Wenn die Auswertung des referenzierten Moduls fehlschlgt, lehnt es mit dem geworfenen Fehler ab.

Beschreibung

Die Import-Deklarationssyntax (import something from "somewhere") ist statisch und fhrt immer dazu, dass das importierte Modul zur Ladezeit ausgewertet wird. Dynamische Importe ermglichen es, die syntaktische Starrheit von Importdeklarationen zu umgehen und ein Modul bedingt oder auf Abruf zu laden. Die folgenden Grnde knnten zu einer Verwendung des dynamischen Imports fhren:

• Wenn das statische Importieren das Laden Ihres Codes erheblich verlangsamt oder den Speicherbedarf Ihres Programms erhht und die Wahrscheinlichkeit gering ist, dass Sie den Code, den Sie importieren, bentigen oder diesen erst zu einem spteren Zeitpunkt bentigen.
• Wenn das Modul, das Sie importieren mchten, zur Ladezeit nicht existiert.
• Wenn der Import-Bezeichner-String dynamisch konstruiert werden muss. (Statischer Import untersttzt nur statische Bezeichner.)
• Wenn das importierte Modul Nebeneffekte hat und Sie diese Nebeneffekte nur mchten, wenn eine gewisse Bedingung wahr ist. (Es wird empfohlen, keine Nebeneffekte in einem Modul zu haben, aber manchmal knnen Sie dies in Ihren Modulabhngigkeiten nicht kontrollieren.)
• Wenn Sie sich in einer nicht-modularen Umgebung befinden (zum Beispiel eval oder eine Skriptdatei).

Verwenden Sie den dynamischen Import nur, wenn es erforderlich ist. Die statische Form ist vorzuziehen, um anfngliche Abhngigkeiten zu laden, und kann mehr von statischen Analysetools und Tree Shaking profitieren.

Wenn Ihre Datei nicht als Modul ausgefhrt wird (wenn sie in einer HTML-Datei referenziert wird, muss das Skript-Tag type="module" haben), knnen Sie statische Import-Deklarationen nicht verwenden. Andererseits ist die asynchrone dynamische Import-Syntax immer verfgbar, sodass Sie Module in Nicht-Modulumgebungen importieren knnen.

Der options-Parameter erlaubt verschiedene Arten von Importoptionen. Zum Beispiel Importeigenschaften:

import("./data.json", { with: { type: "json" } });

Dynamischer Modulimport ist nicht in allen Ausfhrungskontexten erlaubt. Zum Beispiel kann import() im Hauptthread, einem Shared Worker oder einem dedizierten Worker verwendet werden, lst jedoch einen Fehler aus, wenn es in einem Service Worker oder einem Worklet aufgerufen wird.

Modul-Namensraum-Objekt

Ein Modul-Namensraum-Objekt ist ein Objekt, das alle Exporte eines Moduls beschreibt. Es ist ein statisches Objekt, das erstellt wird, wenn das Modul ausgewertet wird. Es gibt zwei Mglichkeiten, auf das Modul-Namensraum-Objekt eines Moduls zuzugreifen: ber einen Namensraum-Import (import * as name from moduleName), oder ber den Erfllungswert eines dynamischen Imports.

Das Modul-Namensraum-Objekt ist ein versiegeltes Objekt mit null-Prototyp. Das bedeutet, dass alle String-Schlssel des Objekts den Exporten des Moduls entsprechen und es niemals zustzliche Schlssel gibt. Alle Schlssel sind enumerierbar in lexikografischer Reihenfolge (d.h. das Standardverhalten von Array.prototype.sort()), wobei der Standardexport als Schlssel default verfgbar ist. Zustzlich hat das Modul-Namensraum-Objekt eine [Symbol.toStringTag]-Eigenschaft mit dem Wert "Module", die in Object.prototype.toString() verwendet wird.

Die String-Eigenschaften sind nicht konfigurierbar und schreibbar, wenn Sie Object.getOwnPropertyDescriptors() verwenden, um deren Deskriptoren zu erhalten. Sie sind jedoch faktisch schreibgeschtzt, da Sie einer Eigenschaft keinen neuen Wert zuweisen knnen. Dieses Verhalten spiegelt wider, dass statische Importe "dynamische Bindungen" erstellen die Werte knnen vom Modul, das sie exportiert, neu zugewiesen werden, aber nicht vom Modul, das sie importiert. Die Schreibbarkeit der Eigenschaften spiegelt die Mglichkeit wider, dass sich die Werte ndern, weil nicht konfigurierbare und nicht schreibbare Eigenschaften konstant sein mssen. Zum Beispiel knnen Sie den exportierten Wert einer Variablen neu zuweisen, und der neue Wert kann im Modul-Namensraum-Objekt beobachtet werden.

Jeder (normalisierte) Modulbezeichner entspricht einem einzigartigen Modul-Namensraum-Objekt, sodass das Folgende im Allgemeinen zutrifft:

import * as mod from "/my-module.js";

import("/my-module.js").then((mod2) => {
  console.log(mod === mod2); // true
});

Auer in einem kuriosen Fall: Weil ein Promise niemals zu einem thenable fhrt, wird die Funktion, die then() heit und von my-module.js exportiert wird, automatisch aufgerufen, wenn das Promise des dynamischen Imports erfllt wird, als Teil des Auflsungsprozesses von Promises.

// my-module.js
export function then(resolve) {
  console.log("then() called");
  resolve(1);
}

// main.js
import * as mod from "/my-module.js";

import("/my-module.js").then((mod2) => {
  // Logs "then() called"
  console.log(mod === mod2); // false
});

Dieses aggressive Caching stellt sicher, dass ein Stck JavaScript-Code niemals mehr als einmal ausgefhrt wird, selbst wenn es mehrfach importiert wird. Zuknftige Importe lsen nicht einmal HTTP-Anfragen oder Dateizugriffe aus. Wenn Sie ein Modul erneut importieren und auswerten mssen, ohne die gesamte JavaScript-Umgebung neu zu starten, ist ein mglicher Trick, einen einzigartigen Query-Parameter im Modul-Bezeichner zu verwenden. Dies funktioniert auch in Nicht-Browser-Laufzeiten, die URL-Bezeichner untersttzen.

import(`/my-module.js?t=${Date.now()}`);

Beachten Sie, dass dies in einer lang laufenden Anwendung zu Speicherlecks fhren kann, da die Engine keine Modul-Namensraum-Objekte sicher als Mll abfhren kann. Derzeit gibt es keine Mglichkeit, den Cache von Modul-Namensraum-Objekten manuell zu leeren.

Sie knnen auch die Fetch API verwenden, um den Modulquellcode als Text abzurufen und das Modul dann abhngig vom Modultyp manuell auszuwerten:

• Fr JavaScript-Module knnen Sie den Quellcode dynamisch als blob: URL in Browsern importieren oder vm.Module verwenden, um es in Node.js auszuwerten.
• Fr JSON-Module knnen Sie den Quellcode mit JSON.parse() parsen.
• Fr CSS-Module knnen Sie ein neues CSSStyleSheet-Objekt erstellen und dessen replace()-Methode verwenden, um es mit dem Quellcode zu befllen.

Dies ist jedoch semantisch nicht dasselbe wie der dynamische Import, da Einstellungen des Benutzeragenten wie fetch destination, CSP oder Modulauflsung mglicherweise nicht korrekt angewendet werden.

Das Caching von Modul-Namensraum-Objekten gilt nur fr Module, die erfolgreich geladen und verlinkt sind. Ein Modul wird in drei Schritten importiert: Laden (Abrufen des Moduls), Verlinken (hauptschlich, Parsen des Moduls) und Auswerten (Ausfhren des geparsten Codes). Nur Auswertungsfehler werden zwischengespeichert; wenn das Laden oder Verlinken eines Moduls fehlschlgt, kann der nchste Import versuchen, das Modul erneut zu laden und zu verlinken. Der Browser kann das Ergebnis der Abrufoperation mglicherweise zwischenspeichern oder auch nicht, aber er sollte den typischen HTTP-Semantiken folgen, sodass die Behandlung solcher Netzwerkfehler sich nicht von der Behandlung von fetch()-Fehlern unterscheiden sollte.

Beispiele

Importieren eines Moduls nur fr seine Nebeneffekte

(async () => {
  if (somethingIsTrue) {
    // import module for side effects
    await import("/modules/my-module.js");
  }
})();

Wenn Ihr Projekt Pakete verwendet, die ESM exportieren, knnen Sie diese auch nur fr Nebeneffekte importieren. Dies wird den Code in der Einstiegspunkt-Datei des Pakets (und allen Dateien, die es importiert) nur ausfhren.

Import von Standards

Wenn Sie das importierte Modul-Namensraum-Objekt destrukturieren, mssen Sie den default-Schlssel umbenennen, da default ein reserviertes Wort ist.

(async () => {
  if (somethingIsTrue) {
    const {
      default: myDefault,
      foo,
      bar,
    } = await import("/modules/my-module.js");
  }
})();

Importieren auf Abruf als Reaktion auf eine Benutzeraktion

Dieses Beispiel zeigt, wie man Funktionalitt auf eine Seite je nach Benutzeraktion, in diesem Fall einem Knopfdruck, ldt und dann eine Funktion innerhalb dieses Moduls aufruft. Dies ist nicht die einzige Mglichkeit, diese Funktionalitt zu implementieren. Die import()-Funktion untersttzt auch await.

const main = document.querySelector("main");
for (const link of document.querySelectorAll("nav > a")) {
  link.addEventListener("click", (e) => {
    e.preventDefault();

    import("/modules/my-module.js")
      .then((module) => {
        module.loadPageInto(main);
      })
      .catch((err) => {
        main.textContent = err.message;
      });
  });
}

Importieren verschiedener Module basierend auf der Umgebung

In Prozessen wie serverseitigem Rendering mssen Sie mglicherweise verschiedene Logik auf dem Server oder im Browser laden, da sie mit unterschiedlichen globalen Objekten oder Modulen interagieren (zum Beispiel hat Browsercode Zugriff auf Web-APIs wie document und navigator, whrend Servercode Zugriff auf das Dateisystem des Servers hat). Dies knnen Sie ber einen bedingten dynamischen Import tun.

let myModule;

if (typeof window === "undefined") {
  myModule = await import("module-used-on-server");
} else {
  myModule = await import("module-used-in-browser");
}

Importieren von Modulen mit einem nicht-literalen Bezeichner

Dynamische Importe erlauben jeden Ausdruck als Modulbezeichner, nicht notwendigerweise String-Literale.

Hier laden wir 10 Module, /modules/module-0.js, /modules/module-1.js usw., gleichzeitig und rufen die load-Funktionen auf, die jedes davon exportiert.

Promise.all(
  Array.from({ length: 10 }).map(
    (_, index) => import(`/modules/module-${index}.js`),
  ),
).then((modules) => modules.forEach((module) => module.load()));

Verwenden von Importeigenschaften mit dynamischem Import

Importeigenschaften werden als zweiter Parameter der import()-Syntax akzeptiert.

const data = await import("./data.json", {
  with: { type: "json" },
});

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• import