<script type="importmap"> — HTML element uitgelegd

Syntaxis

HTML

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

De attributen src, async, nomodule, defer, crossorigin, integrity en referrerpolicy mogen niet worden opgegeven.

Uitzonderingen

`TypeError`	De definitie van de import map is geen JSON-object, de sleutel `importmap` is gedefinieerd maar de waarde ervan is geen JSON-object, of de sleutel `scopes` is gedefinieerd maar de waarde ervan is geen JSON-object.

Browsers genereren waarschuwingen in de console voor andere gevallen waarin de JSON van de import map niet voldoet aan het import map-schema.

Beschrijving

Bij het importeren van een JavaScript-module hebben zowel het import-statement als de import()-operator een "modulespecificatie" die aangeeft welke module moet worden geïmporteerd. Een browser moet deze specificatie kunnen omzetten naar een absolute URL om de module te kunnen importeren.

De volgende statements importeren bijvoorbeeld elementen uit de modulespecificatie "https://example.com/shapes/circle.js", wat een absolute URL is, en de modulespecificatie "./modules/shapes/square.js", wat een pad is relatief aan de basis-URL van het document.

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

Met import maps kunnen ontwikkelaars (bijna) elke gewenste tekst opgeven in de modulespecificatie; de map levert een bijbehorende waarde die de tekst vervangt wanneer de modulespecificatie wordt omgezet.

Kale modules ("bare modules")

De onderstaande import map definieert een sleutel imports met een "modulespecificatiemap" met de eigenschappen circle en square.

HTML

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

Met deze import map kunnen we dezelfde modules als hierboven importeren, maar dan met "kale modules" in onze modulespecificaties:

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

Padvoorvoegsels koppelen

Een sleutel in de modulespecificatiemap kan ook worden gebruikt om een padvoorvoegsel in een modulespecificatie opnieuw te koppelen. Merk op dat in dit geval zowel de eigenschap als het gekoppelde pad een afsluitende schuine streep (/) moeten hebben.

HTML

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

We zouden dan een circle-module kunnen importeren zoals getoond.

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

Paden in de sleutel van de modulespecificatiemap

Sleutels van een modulespecificatie hoeven geen namen van één woord ("kale namen") te zijn. Ze kunnen ook padscheidingstekens bevatten of ermee eindigen, absolute URL's zijn, of relatieve URL-paden zijn die beginnen met /, ./ of ../.

JSON

{
  "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/"
  }
}

Als er meerdere sleutels van een modulespecificatiemap zijn die mogelijk overeenkomen, wordt de meest specifieke sleutel geselecteerd (dat wil zeggen, de sleutel met het langste pad/waarde).

Een modulespecificatie van ./foo/../js/app.js wordt vóór de matching omgezet naar ./js/app.js. Dit betekent dat een sleutel ./js/app.js overeenkomt met de modulespecificatie, ook al zijn ze niet exact hetzelfde.

Modulespecificatiemaps met bereik ("scopes")

U kunt de sleutel scopes gebruiken om koppelingen op te geven die alleen worden gebruikt als het script dat de module importeert een bepaald URL-pad bevat. Als de URL van het ladende script overeenkomt met het opgegeven pad, wordt de aan dat bereik gekoppelde mapping gebruikt. Hierdoor kunnen verschillende versies van de module worden gebruikt, afhankelijk van welke code de import uitvoert.

De onderstaande map gebruikt bijvoorbeeld alleen de map met bereik als de ladende module een URL heeft die het pad "/modules/custom-shapes/" bevat.

HTML

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

Als meerdere bereiken overeenkomen met de verwijzende URL, wordt het meest specifieke bereikpad gebruikt (de sleutelnaam van het bereik met de langste naam). De browser valt terug op het eerstvolgende meest specifieke bereikpad als er geen overeenkomende specificatie is, enzovoort, totdat uiteindelijk wordt teruggevallen op de modulespecificatiemap in de sleutel imports.

Integriteitsmetadatamap

U kunt de sleutel integrity gebruiken om een mapping op te geven voor de integriteitsmetadata van modules. Hiermee kunt u de integriteit van dynamisch of statisch geïmporteerde modules waarborgen. Met integrity kunt u ook een terugvaloptie bieden voor top-level of vooraf geladen (preloaded) modules, voor het geval deze nog geen integrity-attribuut hebben.

De sleutels van de map vertegenwoordigen module-URL's, die absoluut of relatief kunnen zijn (beginnend met /, ./ of ../). De waarden van de map vertegenwoordigen integriteitsmetadata, identiek aan die gebruikt in integrity-attribuutwaarden.

De onderstaande map definieert bijvoorbeeld integriteitsmetadata voor de module square.js (direct) en de bijbehorende kale specificatie (indirect, via de sleutel imports).

HTML

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

Meerdere import maps samenvoegen

Browsers die dit ondersteunen, kunnen één of meer import maps ergens in het document declareren, mits ze zijn gedefinieerd voordat een module die ervan afhankelijk is, wordt geladen (sommige browserversies staan slechts één declaratie van een import map toe, die vóór het laden van een module moet verschijnen).

Intern houden browsers één globale representatie van de import map bij. Wanneer meerdere import maps in een document zijn opgenomen, wordt hun inhoud samengevoegd in de globale import map op het moment dat ze worden geregistreerd.

Beschouw bijvoorbeeld de volgende twee import maps:

HTML

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

HTML

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

Deze zijn equivalent aan de volgende enkele import map:

HTML

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

Modulespecificaties in elke geregistreerde map die al vooraf waren opgelost, worden weggelaten. Latere resoluties van deze specificaties leveren dezelfde resultaten op als hun eerdere resoluties.

Als bijvoorbeeld de modulespecificatie /app/helper.js al was opgelost, dan is de volgende nieuwe import map:

HTML

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

equivalent aan:

HTML

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

De regel voor /app/helper.js werd genegeerd en niet in de map opgenomen.

Evenzo worden modulespecificaties in een geregistreerde map die al waren gekoppeld aan URL's in de globale map, weggelaten; hun eerdere koppeling blijft gelden.

De volgende twee import maps bijvoorbeeld:

HTML

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

HTML

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

zijn equivalent aan de volgende enkele import map:

HTML

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

De regel /app/helper/ uit de tweede map werd genegeerd.

Opmerking

In browsers die dit niet ondersteunen (raadpleeg de compatibiliteitsgegevens), kan een polyfill worden gebruikt om problemen met module-resolutie te voorkomen.

JSON-representatie van een import map

Hieronder volgt een "formele" definitie van de JSON-representatie van een import map.

De import map moet een geldig JSON-object zijn dat een van de optionele sleutels imports, scopes en integrity kan definiëren. De waarde van elke sleutel moet een object zijn, dat leeg mag zijn.

`imports` Optioneel	De waarde is een modulespecificatiemap die de koppelingen biedt tussen de modulespecificatietekst die kan voorkomen in een `import`-statement of `import()`-operator, en de tekst die deze vervangt wanneer de specificatie wordt opgelost. Dit is de terugvalmap die wordt doorzocht op overeenkomende modulespecificaties als er geen padUR's van `scopes` overeenkomen, of als de modulespecificatiemaps in overeenkomende `scopes`-paden geen sleutel bevatten die overeenkomt met de modulespecificatie. `<module specifier map>` : Een "modulespecificatiemap" is een geldig JSON-object waarbij de sleutels tekst zijn die aanwezig kan zijn in de modulespecificatie bij het importeren van een module, en de bijbehorende waarden de URL's of paden zijn die deze tekst vervangen wanneer de modulespecificatie wordt omgezet naar een adres. Het JSON-object van de modulespecificatiemap moet aan de volgende vereisten voldoen: Geen van de sleutels mag leeg zijn. Alle waarden moeten strings zijn die ofwel een geldige absolute URL definiëren, ofwel een geldige URL-string die begint met `/`, `./` of `../`. Als een sleutel eindigt op `/`, dan moet de bijbehorende waarde ook eindigen op `/`. Een sleutel met een afsluitende `/` kan worden gebruikt als voorvoegsel bij het koppelen (of opnieuw koppelen) van moduleadressen. De volgorde van de objecteigenschappen is niet relevant: als meerdere sleutels overeen kunnen komen met de modulespecificatie, wordt de meest specifieke sleutel gebruikt (met andere woorden, een specificatie "olive/branch/" komt eerder overeen dan "olive/").
`integrity` Optioneel	Definieert een geldig JSON-object waarin de sleutels strings zijn die geldige absolute of relatieve URL's bevatten (beginnend met `/`, `./` of `../`), en de bijbehorende waarden geldige integriteitsmetadata zijn. Als de URL van een script dat een module importeert of vooraf laadt (preload), overeenkomt met een sleutel in het `integrity`-object, wordt de bijbehorende integriteitsmetadata toegepast op de fetch-opties van het script, tenzij daar al integriteitsmetadata aan is gekoppeld.
`scopes` Optioneel	Bereiken ("scopes") definiëren padspecifieke modulespecificatiemaps, waardoor de keuze van de map afhankelijk kan zijn van het pad van de code die de module importeert. Het scopes-object is een geldig JSON-object waarbij elke eigenschap een `<scope key>` is, wat een URL-pad is, met een bijbehorende waarde die een `<module specifier map>` is. Als de URL van een script dat een module importeert overeenkomt met een pad van een `<scope key>`, wordt eerst de bijbehorende `<module specifier map>`-waarde gecontroleerd op overeenkomende specificaties. Als er meerdere overeenkomende scope-sleutels zijn, wordt de waarde die is gekoppeld aan de meest specifieke/geneste bereikpaden eerst gecontroleerd op overeenkomende modulespecificaties. De terugvalmap voor modulespecificaties in `imports` wordt gebruikt als er geen overeenkomende sleutels voor modulespecificaties zijn in een van de overeenkomende modulespecificatiemaps met bereik. Merk op dat het bereik niets verandert aan de manier waarop een adres wordt opgelost; relatieve adressen worden altijd opgelost ten opzichte van de basis-URL van de import map.

imports Optioneel

De waarde is een modulespecificatiemap die de koppelingen biedt tussen de modulespecificatietekst die kan voorkomen in een import-statement of import()-operator, en de tekst die deze vervangt wanneer de specificatie wordt opgelost.

Dit is de terugvalmap die wordt doorzocht op overeenkomende modulespecificaties als er geen padUR's van scopes overeenkomen, of als de modulespecificatiemaps in overeenkomende scopes-paden geen sleutel bevatten die overeenkomt met de modulespecificatie.

<module specifier map>
- : Een "modulespecificatiemap" is een geldig JSON-object waarbij de sleutels tekst zijn die aanwezig kan zijn in de modulespecificatie bij het importeren van een module, en de bijbehorende waarden de URL's of paden zijn die deze tekst vervangen wanneer de modulespecificatie wordt omgezet naar een adres.
  
  Het JSON-object van de modulespecificatiemap moet aan de volgende vereisten voldoen:
  - Geen van de sleutels mag leeg zijn.
  - Alle waarden moeten strings zijn die ofwel een geldige absolute URL definiëren, ofwel een geldige URL-string die begint met /, ./ of ../.
  - Als een sleutel eindigt op /, dan moet de bijbehorende waarde ook eindigen op /. Een sleutel met een afsluitende / kan worden gebruikt als voorvoegsel bij het koppelen (of opnieuw koppelen) van moduleadressen.
  - De volgorde van de objecteigenschappen is niet relevant: als meerdere sleutels overeen kunnen komen met de modulespecificatie, wordt de meest specifieke sleutel gebruikt (met andere woorden, een specificatie "olive/branch/" komt eerder overeen dan "olive/").

integrity Optioneel

Definieert een geldig JSON-object waarin de sleutels strings zijn die geldige absolute of relatieve URL's bevatten (beginnend met /, ./ of ../), en de bijbehorende waarden geldige integriteitsmetadata zijn.

Als de URL van een script dat een module importeert of vooraf laadt (preload), overeenkomt met een sleutel in het integrity-object, wordt de bijbehorende integriteitsmetadata toegepast op de fetch-opties van het script, tenzij daar al integriteitsmetadata aan is gekoppeld.

scopes Optioneel

Bereiken ("scopes") definiëren padspecifieke modulespecificatiemaps, waardoor de keuze van de map afhankelijk kan zijn van het pad van de code die de module importeert.

Het scopes-object is een geldig JSON-object waarbij elke eigenschap een <scope key> is, wat een URL-pad is, met een bijbehorende waarde die een <module specifier map> is.

Als de URL van een script dat een module importeert overeenkomt met een pad van een <scope key>, wordt eerst de bijbehorende <module specifier map>-waarde gecontroleerd op overeenkomende specificaties. Als er meerdere overeenkomende scope-sleutels zijn, wordt de waarde die is gekoppeld aan de meest specifieke/geneste bereikpaden eerst gecontroleerd op overeenkomende modulespecificaties. De terugvalmap voor modulespecificaties in imports wordt gebruikt als er geen overeenkomende sleutels voor modulespecificaties zijn in een van de overeenkomende modulespecificatiemaps met bereik.

Merk op dat het bereik niets verandert aan de manier waarop een adres wordt opgelost; relatieve adressen worden altijd opgelost ten opzichte van de basis-URL van de import map.

Zie ook

Het type-attribuut van HTML-<script>-elementen

Het element `<script type="importmap">`

Syntaxis

Uitzonderingen

Beschrijving

Kale modules ("bare modules")

Padvoorvoegsels koppelen

Paden in de sleutel van de modulespecificatiemap

Modulespecificatiemaps met bereik ("scopes")

Integriteitsmetadatamap

Meerdere import maps samenvoegen

JSON-representatie van een import map

Zie ook

Verwante elementen

Het element <script type="importmap">

Syntaxis

Uitzonderingen

Beschrijving

Kale modules ("bare modules")

Padvoorvoegsels koppelen

Paden in de sleutel van de modulespecificatiemap

Modulespecificatiemaps met bereik ("scopes")

Integriteitsmetadatamap

Meerdere import maps samenvoegen

JSON-representatie van een import map

Zie ook

Verwante elementen

Het element `<script type="importmap">`