Derimportmap Wert destype Attributs des<script> Element gibt an, dass der Inhalt des Elements eine Importkarte enthält.

Eine Importkarte ist ein JSON-Objekt, das es Entwicklern ermöglicht, zu steuern, wie der Browser Modulspezifizierer auflöst, wennJavaScript-Module importiert werden. Sie bietet eine Zuordnung zwischen dem Text, der als Modulspezifizierer in einerimport Anweisung oder demimport() Operator verwendet wird, und dem entsprechenden Wert, der den Text beim Auflösen des Spezifizierers ersetzt. Das JSON-Objekt muss demImportkartenschema im JSON-Format entsprechen.

Eine Importkarte wird verwendet, um Modulspezifizierer in statischen und dynamischen Imports aufzulösen, und muss daher deklariert und verarbeitet werden, bevor irgendwelche<script> Elemente Module mit in der Karte deklarierten Spezifizierern importieren. Beachten Sie, dass die Importkarte nur auf Modulspezifizierer in derimport Anweisung oder demimport() Operator für Module, die in Dokumente geladen werden, anwendbar ist; sie gilt nicht für den Pfad, der imsrc Attribut eines<script> Elements angegeben ist oder für Module, die in Worker oder Worklets geladen werden.

Weitere Informationen finden Sie im AbschnittModule mit Importkarten importieren im JavaScript-Module-Leitfaden.

Syntax

<script type="importmap">  // JSON object defining import</script>

Die Attributesrc,async,nomodule,defer,crossorigin,integrity, undreferrerpolicy dürfen nicht angegeben werden.

Ausnahmen

TypeError

Die Definition der Importkarte ist kein JSON-Objekt, derimportmap Schlüssel ist definiert, aber sein Wert ist kein JSON-Objekt, oder derscopes Schlüssel ist definiert, aber sein Wert ist kein JSON-Objekt.

Browser generieren Konsolenwarnungen für andere Fälle, in denen das Importkarte-JSON nicht demImportkartenschema entspricht.

Beschreibung

Beim Importieren einesJavaScript-Moduls haben sowohl dieimport Anweisung als auch derimport() Operator einen "Modulspezifizierer", der angibt, welches Modul importiert werden soll. Ein Browser muss in der Lage sein, diesen Spezifizierer zu einer absoluten URL aufzulösen, um das Modul zu importieren.

Zum Beispiel importieren die folgenden Anweisungen Elemente vom Modulspezifizierer"https://example.com/shapes/circle.js", was eine absolute URL ist, und vom Modulspezifizierer"./modules/shapes/square.js", was ein Pfad relativ zur Basis-URL des Dokuments ist.

import { name as circleName } from "https://example.com/shapes/circle.js";import { name as squareName, draw } from "./modules/shapes/square.js";

Importkarten erlauben es Entwicklern, (fast) jeden gewünschten Text im Modulspezifizierer anzugeben; die Karte liefert einen entsprechenden Wert, der den Text ersetzt, wenn der Modulspezifizierer aufgelöst wird.

Bare modules

Die unten gezeigte Importkarte definiert einenimports Schlüssel, der eine "Modulspezifiziererkarte" mit den Eigenschaftencircle undsquare enthält.

<script type="importmap">  {    "imports": {      "circle": "https://example.com/shapes/circle.js",      "square": "./modules/shapes/square.js"    }  }</script>

Mit dieser Importkarte können wir dieselben Module wie oben importieren, aber in unseren Modulspezifizierern "bare modules" verwenden:

import { name as circleName } from "circle";import { name as squareName, draw } from "square";

Zuordnung von Pfadpräfixen

Ein Schlüssel in der Modulspezifiziererkarte kann auch verwendet werden, um ein Pfadpräfix in einem Modulspezifizierer neu zuzuordnen. Beachten Sie, dass in diesem Fall sowohl die Eigenschaft als auch der zugeordnete Pfad ein abschließendes Schrägstrich (/) haben müssen.

<script type="importmap">  {    "imports": {      "shapes/": "./modules/shapes/",      "other-shapes/": "https://example.com/modules/shapes/"    }  }</script>

Wir könnten dann ein Kreis-Modul wie gezeigt importieren.

import { name as circleName } from "shapes/circle.js";

Pfade im Schlüssel der Modulspezifiziererkarte

Modulspezifiziererschlüssel müssen keine einzelnen Wortnamen ("bare names") sein. Sie können auch Pfadtrennzeichen enthalten oder mit ihnen enden oder absolute URLs sein oder relative URL-Pfade, die mit/,./, oder../ beginnen.

{  "imports": {    "modules/shapes/": "./modules/src/shapes/",    "modules/square": "./modules/src/other/shapes/square.js",    "https://example.com/modules/square.js": "./modules/src/other/shapes/square.js",    "../modules/shapes/": "/modules/shapes/"  }}

Wenn es mehrere Modulspezifiziererschlüssel in einer Modulspezifiziererkarte gibt, die übereinstimmen könnten, wird der spezifischste Schlüssel ausgewählt (d.h. der mit dem längeren Pfad/Wert).

Ein Modulspezifizierer von./foo/../js/app.js würde vor dem Abgleichen zu./js/app.js aufgelöst. Das bedeutet, dass ein Modulspezifiziererschlüssel von./js/app.js dem Modulspezifizierer entsprechen würde, auch wenn sie nicht genau gleich sind.

Gescopte Modulspezifiziererkarten

Sie können denscopes Schlüssel verwenden, um Zuordnungen bereitzustellen, die nur verwendet werden, wenn das Script, das das Modul importiert, einen bestimmten URL-Pfad enthält. Wenn die URL des ladenden Script den angegebenen Pfad erfüllt, wird die mit dem Scope verbundene Zuordnung verwendet. Dies ermöglicht die Verwendung verschiedener Versionen des Moduls, je nachdem, welcher Code den Import durchführt.

Zum Beispiel wird die unten stehende Karte nur die gescopte Karte verwenden, wenn das ladende Modul eine URL hat, die den Pfad: "/modules/custom-shapes/" enthält.

<script type="importmap">  {    "imports": {      "square": "./modules/shapes/square.js"    },    "scopes": {      "/modules/custom-shapes/": {        "square": "https://example.com/modules/shapes/square.js"      }    }  }</script>

Wenn mehrere Scopes mit der Referrer-URL übereinstimmen, wird der spezifischste Scope-Pfad verwendet (der Scopeschlüsselname mit dem längsten Namen). Der Browser wechselt zum nächstspezifischeren Scope-Pfad, wenn kein übereinstimmender Spezifizierer vorhanden ist, und so weiter, falls nötig, bis letztlich auf die Modulspezifiziererkarte imimports Schlüssel zurückgegriffen wird.

Integritätsmetadatenkarte

Sie können denintegrity Schlüssel verwenden, um eine Zuordnung für Modul-Integritätsmetadaten bereitzustellen. Dies ermöglicht es Ihnen, die Integrität von dynamisch oder statisch importierten Modulen sicherzustellen.integrity ermöglicht Ihnen auch, einen Fallback für Top-Level- oder vorgeladene Module bereitzustellen, falls sie nicht bereits einintegrity Attribut enthalten.

Die Kartenschlüssel repräsentieren Modul-URLs, die entweder absolut oder relativ sein können (beginnend mit/,./, oder../). Die Kartenwerte repräsentieren Integritätsmetadaten, identisch mit denen, die inintegrity Attributwerten verwendet werden.

Zum Beispiel definiert die unten stehende Karte Integritätsmetadaten für dassquare.js Modul (direkt) und seinen bare Spezifizierer (transitiv über denimports Schlüssel).

<script type="importmap">  {    "imports": {      "square": "./modules/shapes/square.js"    },    "integrity": {      "./modules/shapes/square.js": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"    }  }</script>

Zusammenführen mehrerer Importkarten

Browser verwalten intern eine einzige globale Importkarten-Darstellung. Wenn mehrere Importkarten in ein Dokument aufgenommen werden, werden deren Inhalte beim Registrieren in die globale Importkarte zusammengeführt.

Zum Beispiel, betrachten Sie die folgenden zwei Importkarten:

<script type="importmap">  {    "imports": {      "/app/": "./original-app/"    }  }</script>

<script type="importmap">  {    "imports": {      "/app/helper": "./helper/index.mjs"    },    "scopes": {      "/js": {        "/app/": "./js-app/"      }    }  }</script>

Diese sind äquivalent zu der folgenden einzigen Importkarte:

<script type="importmap">  {    "imports": {      "/app/": "./original-app/",      "/app/helper": "./helper/index.mjs"    },    "scopes": {      "/js": {        "/app/": "./js-app/"      }    }  }</script>

Modulspezifizierer in jeder registrierten Karte, die bereits vorher aufgelöst wurden, werden ignoriert. Nachfolgende Auflösungen dieser Spezifizierer liefern dieselben Ergebnisse wie ihre vorherigen Auflösungen.

Zum Beispiel, wenn der Modulspezifizierer/app/helper.js bereits aufgelöst wurde, würde die folgende neue Importkarte:

<script type="importmap">  {    "imports": {      "/app/helper.js": "./helper/index.mjs",      "lodash": "/node_modules/lodash-es/lodash.js"    }  }</script>

gleichwertig mit:

<script type="importmap">  {    "imports": {      "lodash": "/node_modules/lodash-es/lodash.js"    }  }</script>

Die/app/helper.js Regel wurde ignoriert und nicht in die Karte aufgenommen.

Ebenso werden Modulspezifizierer in einer registrierten Karte, die bereits zu URLs in der globalen Karte zugeordnet wurden, ignoriert; ihre vorherige Zuordnung bleibt bestehen.

Zum Beispiel die folgenden zwei Importkarten:

<script type="importmap">  {    "imports": {      "/app/helper": "./helper/index.mjs",      "lodash": "/node_modules/lodash-es/lodash.js"    }  }</script>

<script type="importmap">  {    "imports": {      "/app/helper": "./main/helper/index.mjs"    }  }</script>

sind gleichwertig mit der folgenden einzigen Importkarte:

<script type="importmap">  {    "imports": {      "/app/helper": "./helper/index.mjs",      "lodash": "/node_modules/lodash-es/lodash.js"    }  }</script>

Die/app/helper/ Regel wurde aus der zweiten Karte entfernt.

Importkarten-JSON-Darstellung

Das Folgende ist eine "formale" Definition der Importkarten-JSON-Darstellung.

Die Importkarte muss ein gültiges JSON-Objekt sein, das beliebige der optionalen Schlüsselimports,scopes undintegrity definieren kann. Der Wert jedes Schlüssels muss ein Objekt sein, das leer sein darf.

importsOptional

Der Wert ist eineModulspezifiziererkarte, die die Zuordnungen zwischen Modulspezifizierertext, der in einerimport Anweisung oder einemimport() Operator erscheinen könnte, und dem Text bereitstellt, der ihn ersetzt, wenn der Spezifizierer aufgelöst wird.

Dies ist die Fallback-Karte, die nach übereinstimmenden Modulspezifizierern durchsucht wird, wenn keinescopes Pfad-URLs übereinstimmen oder wenn die Modulspezifiziererkarten in übereinstimmendenscopes Pfaden keinen Schlüssel enthalten, der dem Modulspezifizierer entspricht.

<module specifier map>

Eine "Modulspezifiziererkarte" ist ein gültiges JSON-Objekt, in dem dieSchlüssel Texte sind, die im Modulspezifizierer beim Importieren eines Moduls vorkommen können, und die entsprechendenWerte die URLs oder Pfade, die diesen Text ersetzen, wenn der Modulspezifizierer zu einer Adresse aufgelöst wird.

Das JSON-Objekt der Modulspezifiziererkarte hat folgende Anforderungen:

• Keiner der Schlüssel darf leer sein.
• Alle Werte müssen Strings sein, die entweder eine gültige absolute URL oder eine gültige URL darstellen, die mit/,./, oder../ beginnt.
• Wenn ein Schlüssel mit/ endet, dann muss der entsprechende Wert auch mit/ enden.Ein Schlüssel mit einem abschließenden/ kann als Präfix verwendet werden, wenn Moduladressen gemappt (oder neu gemappt) werden.
• Die Reihenfolge der Objekteigenschaften ist irrelevant: Wenn mehrere Schlüssel dem Modulspezifizierer entsprechen können, wird der spezifischste Schlüssel verwendet (in anderen Worten, ein Spezifizierer "olive/branch/" würde vor "olive/" übereinstimmen).

integrityOptional

Definiert ein gültiges JSON-Objekt, in dem dieSchlüssel Strings mit gültigen absoluten oder relativen URLs (beginnend mit/,./, oder../) sind,und die entsprechendenWerte sind gültigeIntegritätsmetadaten.

Wenn die URL eines Scripts, das ein Modul importiert oder vorlädt, einem Schlüssel imintegrity Objekt entspricht, werden die entsprechenden Integritätsmetadaten auf die Fetch-Optionen des Scripts angewendet,sofern sie nicht bereits Integritätsmetadaten enthalten.

scopesOptional

Scopes definieren pfadspezifischeModulspezifiziererkarten, sodass die Auswahl der Karte vom Pfad des den Import ausführenden Codes abhängen kann.

Dasscopes Objekt ist ein gültiges JSON-Objekt, in dem jede Eigenschaft ein<scope key> ist, ein URL-Pfad, mit einem entsprechenden Wert, der eine<module specifier map> ist.

Wenn die URL eines Scripts, das ein Modul importiert, einem<scope key> Pfad entspricht, wird der<module specifier map> Wert, der dem Schlüssel zugeordnet ist, zuerst auf übereinstimmende Spezifizierer geprüft.Wenn es mehrere übereinstimmende Scopeschlüssel gibt, werden die Werte der spezifischsten/verschachtelten Scopepfade zuerst auf übereinstimmende Modulspezifizierer geprüft.Die Fallback-Modulspezifiziererkarte inimports wird verwendet, wenn es keine übereinstimmenden Modulspezifiziererschlüssel in einer der übereinstimmenden gescopten Modulspezifiziererkarten gibt.

Beachten Sie, dass der Scope nicht ändert, wie eine Adresse aufgelöst wird; relative Adressen werden immer zur Importkarten-Basis-URL aufgelöst.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• JavaScript-Module > Module mit Importkarten importieren
• Dastype Attribut von HTML<script> Elementen
• import Anweisung
• import() Operator