<script type="importmap">

Syntaxe

<script type="importmap">
  // Un objet JSON définissant l'import
</script>

Les attributs src, async, nomodule, defer, crossorigin, integrity, et referrerpolicy ne doivent pas être présents sur l'élément <script>.

Exceptions

TypeError

La définition de le tableau associatif d'import n'est pas un objet JSON ou la clé importmap est définie mais n'est pas un objet JSON, ou la clé scopes est définie mais n'est pas un objet JSON.

Les navigateurs génèrent des avertissements dans la console au cas où le tableau associatif d'import JSON ne respecte pas le schéma de représentation des tableaux associatifs d'import.

Description

Lorsqu'on importe un module JavaScript, l'instruction import et l'opérateur import() ont tous les deux un spécificateur de module qui indique le module à importer. Un navigateur devra résoudre ce spécificateur en une URL absolue afin d'importer le module.

Par exemple, si on prend les instructions suivantes, on a un spécificateur de module "./modules/formes/carre.js", qui est un chemin relatif à l'URL du document et un second spécificateur de module "https://example.com/formes/cercle.js", qui est une URL absolue.

import { nom as nomCercle } from "https://example.com/formes/cercle.js";
import { nom as nomCarre, dessiner } from "./modules/formes/carre.js";

Les tableaux associatifs d'import permettent d'indiquer (presque) n'importe quel texte comme spécificateur de module, le tableau fournit une correspondance qui remplacera le texte lors de la résolution du spécificateur.

Noms simples

Le tableau associatif d'import qui suit définit une clé imports doté d'un tableau associatif de correspondance pour les spécificateurs de module qui a les propriétés carre et cercle.

<script type="importmap">
  {
    "imports": {
      "carre": "./module/formes/carre.js",
      "cercle": "https://example.com/formes/cercle.js"
    }
  }
</script>

Grâce à ce tableau associatif d'import, on peut réaliser le même import que précédemment, mais en utilisant des noms simples comme spécificateurs de modules :

import { nom as nomCarre, dessiner } from "carre";
import { nom as nomCercle } from "cercle";

Préfixer les chemins

Une clé d'un spécificateur de module peut aussi être utilisée pour rajouter un préfixe à un spécificateur. Il faut noter que dans ce cas, la propriété et le chemin correspondant doivent tous les deux finir par une barre oblique (/).

<script type="importmap">
  {
    "imports": {
      "formes/": "./module/formes/",
      "autresformes/": "https://example.com/modules/formes/"
    }
  }
</script>

On pourrait alors importer le module cercle de cette façon.

import { nom as nomCercle } from "formes/cercle.js";

Utiliser des chemins dans les clés

Les clés des spécificateurs de module n'ont pas forcément à être des noms simples. Elles peuvent contenir ou finir des séparateurs de chemin, être des URL absolues ou des URL relatives dont le chemin commence par /, ./, ou ../.

{
  "imports": {
    "modules/formes/": "./module/src/formes/",
    "modules/carre": "./module/src/autres/formes/carre.js",
    "https://example.com/modules/carre.js": "./module/src/autres/formes/carre.js",
    "../modules/formes/": "/modules/formes/"
  }
}

Si plusieurs clés de spécificateur d'un tableau associatif peuvent correspondre, c'est la clé la plus spécifique qui est sélectionnée (celle avec la plus longue valeur).

Un spécificateur de module ./toto/../js/app.js sera converti en ./js/app.js avant la recherche de correspondance. Aussi, cela signifie que la clé ./js/app.js correspondrait au spécificateur de module, même si ce ne sont pas exactement les mêmes.

Correspondances à portées limitées

La clé scopes permet de fournir des correspondances qui seront uniquement utilisées si le module qui importe contient un chemin donné. Si l'URL du script qui charge le module correspond au chemin indiqué, c'est la correspondance associée à cette portée qui sera utilisée. Cela permet d'avoir différentes versions du module qui peuvent être utilisées selon le code qui réalise l'import.

Dans l'exemple qui suit, le tableau associatif utilisera uniquement la correspondance de la portée si l'URL du module qui fait le chargement contient le chemin : "/modules/formesspecifiques/".

<script type="importmap">
  {
    "imports": {
      "carre": "./module/formes/carre.js"
    },
    "scopes": {
      "/modules/formesspecifiques/": {
        "carre": "https://example.com/modules/formes/carre.js"
      }
    }
  }
</script>

Si plusieurs portées correspondent à l'URL du module, c'est la portée avec le chemin le plus spécifique qui est utilisée (autrement dit, celle pour laquelle la clé a le nom le plus long). Si cette portée ne contient aucun spécificateur correspondant à l'import, il passe à la prochaine portée la plus spécifique, et ainsi de suite. Le navigateur pourra finir par utiliser la correspondance de la clé imports si le spécificateur n'est présent dans aucune portée.

Tableau associatif des métadonnées d'intégrité

Vous pouvez utiliser la clé integrity pour fournir une correspondance pour les métadonnées d'intégrité des modules. Cela permet de garantir l'intégrité des modules importés dynamiquement ou statiquement. La clé integrity permet aussi de fournir une solution de repli pour les modules principaux ou préchargés, au cas où ils n'incluraient pas déjà un attribut integrity.

Les clés du tableau associatif représentent les URL des modules, qui peuvent être absolues ou relatives (commençant par /, ./ ou ../). Les valeurs du tableau associatif représentent les métadonnées d'intégrité, identiques à celles utilisées dans les valeurs de l'attribut integrity.

Par exemple, le tableau associatif ci-dessous définit des métadonnées d'intégrité pour le module square.js (directement) et pour son spécificateur simple (de façon transitive, via la clé imports).

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

Fusion de plusieurs tableaux associatifs d'import

Les navigateurs prenant en charge cette fonctionnalité peuvent déclarer une ou plusieurs tableaux associatifs d'import n'importe où dans le document, à condition qu'elles soient définies avant tout module qui en dépend (certaines versions de navigateurs n'autorisent qu'une seule déclaration de tableau associatif d'import, qui doit apparaître avant tout module chargé).

En interne, les navigateurs maintiennent une seule représentation globale du tableau associatif d'import. Lorsque plusieurs tableaux associatifs d'import sont incluses dans un document, leur contenu est fusionné dans le tableau associatif d'import global lors de leur enregistrement.

Par exemple, considérons les deux tableaux associatifs d'import suivantes :

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

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

Celles-ci sont équivalentes au tableau associatif d'import unique suivant :

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

Les spécificateurs de module de chaque tableau associatif enregistrée qui étaient déjà résolus auparavant sont ignorés. Les résolutions ultérieures de ces spécificateurs donneront les mêmes résultats que leurs résolutions précédentes.

Par exemple, si le spécificateur de module /app/helper.js a déjà été résolu, le nouveau tableau associatif d'import suivant :

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

Sera équivalente à :

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

La règle /app/helper.js a été ignorée et n'a pas été intégrée au tableau associatif.

De même, les spécificateurs de module d'un tableau associatif enregistré qui étaient déjà associés à des URL dans le tableau associatif global sont ignorés ; leur correspondance précédente prévaut.

Par exemple, les deux tableaux associatifs d'import suivants :

<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>

Sont équivalentes au tableau associatif d'import unique suivant :

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

La règle /app/helper/ a été ignorée dans le second tableau associatif.

Représentation JSON des tableaux associatifs d'import

Ce qui suit est une définition « formelle » de la représentation JSON pour les tableaux associatifs d'import.

Le tableau associatif d'import doit être un objet JSON valide qui définit au plus deux clés optionnelles : imports et scopes. Les valeurs de ces clés doivent être un objet, potentiellement vide.

imports Facultatif

La valeur doit être un tableau associatif de spécificateur de module, qui fournit les correspondances entre les spécificateurs utilisés dans les instructions import ou les opérateurs import(), et le texte qui les remplacera lors de leur résolution.

Il s'agit du tableau associatif de correspondance qui est utilisé par défaut si les spécificateurs de module ne sont pas présents (via leur nom ou via leur chemin) dans les portées décrites via l'attribut scopes.

<module specifier map>

Un tableau associatif de spécificateur de module est un objet JSON valide où les clés correspondent au texte qui peut être présent dans le spécificateur de module lors de l'import et où les valeurs correspondantes sont les URL ou les chemins qui remplaceront ce texte lorsque le spécificateur de module sera résolu en une adresse.

L'objet JSON représentant un tableau associatif de spécificateur de module doit respecter les règles suivantes :

• Aucune des clés ne doit être vide.
• Toutes les valeurs doivent être des chaînes de caractères, qui définissent soit une URL absolue valide, soit une chaîne d'URL valide commençant par /, ./, ou ../.
• Si la clé finit par /, la valeur correspondante doit également finir par /. On pourra utiliser une clé se terminant par / comme préfixe lors de la correspondance entre les adresses de modules.
• L'ordre des propriétés de l'objet n'a pas d'importance, si plusieurs clés peuvent correspondre pour un même spécificateur de module, c'est la clé la plus spécifique qui est utilisée (autrement dit le spécificateur "olive/branche/" correspondrait avant "olive/").

integrity Facultatif

Définit un objet JSON valide dont les clés sont des chaînes de caractères contenant des URL absolues ou relatives valides (commençant par /, ./ ou ../), et dont les valeurs correspondantes sont des métadonnées d'intégrité valides.

Si l'URL d'un script important ou préchargeant un module correspond à une clé de l'objet integrity, les métadonnées d'intégrité correspondantes sont appliquées aux options de récupération du script, sauf si elles possèdent déjà des métadonnées d'intégrité.

scopes Facultatif

Les portées définissent des tableaux associatifs de spécificateur de module pour des chemins spécifiques, permettant de choisir la correspondance à effectuer en fonction du chemin du code qui importe le module.

L'objet scopes est un objet JSON valide où chaque propriété est une clé de portée (représentée par une URL) avec une valeur correspondante qui est un tableau associatif de spécificateur de module.

Si l'URL d'un script important un module correspond au chemin d'une clé d'une portée, c'est le tableau associatif de spécificateur de module correspondant qui est utilisé en première pour vérifier les correspondances de spécificateur. S'il existe plusieurs clés de portées qui correspondent, c'est la valeur associée avec le chemin de portée le plus spécifique qui est utilisée en première pour vérifier les correspondances de spécificateur. Le tableau associatif de spécificateur de module décrit dans imports est utilisé en dernier recours s'il n'y a aucune correspondance pour le spécificateur de module dans les tableaux associatifs des portées correspondantes.

On notera que la portée ne modifie pas la façon dont une adresse est résolue. Les adresses relatives sont toujours résolues par rapport à l'URL de base du tableau associatif d'import.

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des modules JavaScript > Importer des modules avec des tableaux associatifs d'import
• L'attribut type des éléments HTML <script>
• L'instruction import
• L'opérateur import()