<script type="importmap">

基线 2023

新可用

2023 年 3 月起,此功能可在最新的设备和浏览器版本中使用。此功能可能在较旧的设备或浏览器中不起作用。

importmaptype 属性<script> 元素 指示元素的主体包含导入映射。

导入映射是一个 JSON 对象,允许开发者控制浏览器在导入JavaScript 模块时如何解析模块说明符。它提供了在import 语句import() 运算符中用作模块说明符的文本与在解析说明符时将替换该文本的对应值之间的映射关系。JSON 对象必须符合导入映射 JSON 表示格式

导入映射用于解析静态和动态导入中的模块说明符,因此必须在任何使用映射中声明的说明符导入模块的<script>元素之前声明和处理。请注意,导入映射仅适用于import 语句import() 运算符中加载到文档中的模块的模块说明符;它不适用于<script>元素的src属性中指定的路径,也不适用于加载到工作线程或工作线程片段中的模块。

有关更多信息,请参阅 JavaScript 模块指南中的使用导入映射导入模块部分。

语法

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

不得指定srcasyncnomoduledefercrossoriginintegrityreferrerpolicy属性。

仅处理文档中第一个具有内联定义的导入映射;任何其他导入映射和外部导入映射都将被忽略。

异常

TypeError

导入映射定义不是 JSON 对象,importmap键已定义但其值不是 JSON 对象,或者scopes键已定义但其值不是 JSON 对象。

对于导入映射 JSON 不符合导入映射架构的其他情况,浏览器会生成控制台警告。

在未处理的type="importmap"的脚本元素上触发error 事件。例如,如果在处理导入映射时模块加载已开始,或者如果页面中定义了多个导入映射,则可能会发生这种情况。

描述

在导入JavaScript 模块时,import 语句import() 运算符都具有指示要导入的模块的“模块说明符”。浏览器必须能够将此说明符解析为绝对 URL,才能导入模块。

例如,以下语句从模块说明符"./modules/shapes/square.js"(相对于文档的基本 URL 的路径)和模块说明符"https://example.com/shapes/circle.js"(绝对 URL)导入元素。

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

导入映射允许开发人员在模块说明符中指定(几乎)任何他们想要的文本;映射提供了相应的替换文本,该文本将在解析模块说明符时替换该文本。

裸模块

下面的导入映射定义了一个imports键,该键具有一个“模块说明符映射”,其中包含属性squarecircle

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

使用此导入映射,我们可以导入与上面相同的模块,但在模块说明符中使用“裸模块”。

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

映射路径前缀

模块说明符映射键也可用于重新映射模块说明符中的路径前缀。请注意,在这种情况下,属性和映射路径都必须以尾部正斜杠 (/) 结尾。

html
<script type="importmap">
  {
    "imports": {
      "shapes/": "./module/shapes/",
      "othershapes/": "https://example.com/modules/shapes/"
    }
  }
</script>

然后我们可以像所示那样导入圆形模块。

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

模块说明符映射键中的路径

模块说明符键不必是单个单词名称(“裸名称”)。它们还可以包含或以路径分隔符结尾,或为绝对 URL,或为以/./../开头的相对 URL 路径。

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

如果模块说明符映射中有多个可能匹配的模块说明符键,则将选择最具体的键(即路径/值最长的键)。

模块说明符./foo/../js/app.js将在匹配之前解析为./js/app.js。这意味着即使模块说明符键和模块说明符不完全相同,模块说明符键./js/app.js也会匹配模块说明符。

作用域模块说明符映射

您可以使用scopes键提供仅在导入模块的脚本包含特定 URL 路径时才使用的映射。如果加载脚本的 URL 与提供的路径匹配,则将使用与作用域关联的映射。这允许根据执行导入操作的代码使用模块的不同版本。

例如,下面的映射仅在加载模块的 URL 包含路径:“/modules/customshapes/”时才使用作用域映射。

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

如果多个作用域与引用 URL 匹配,则使用最具体的作用域路径(名称最长的作用域键名称)。如果不存在匹配的说明符,则浏览器将回退到下一个最具体的作用域路径,依此类推,最终回退到imports键中的模块说明符映射。

完整性元数据映射

您可以使用integrity键为模块完整性元数据提供映射。这使您可以确保动态或静态导入模块的完整性。integrity还使您可以为顶级模块或预加载模块提供回退,以防它们尚未包含integrity属性。

映射键表示模块 URL,可以是绝对 URL 或相对 URL(以/./../开头)。映射值表示完整性元数据,与integrity属性值中使用的元数据相同。

例如,下面的映射为square.js模块(直接)及其裸说明符(通过imports键传递)定义完整性元数据。

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

导入映射 JSON 表示

以下是导入映射 JSON 表示的“正式”定义。

导入映射必须是有效的 JSON 对象,最多可以定义两个可选键:importsscopes。每个键的值必须是一个对象,该对象可以为空。

imports 可选

该值是一个模块说明符映射,它提供了可能出现在import语句或import()运算符中的模块说明符文本与在解析说明符时将替换该文本的文本之间的映射关系。

如果没有任何scopes路径 URL 匹配,或者匹配的scopes路径中的模块说明符映射不包含与模块说明符匹配的键,则这是搜索匹配模块说明符的回退映射。

<module specifier map>

“模块说明符映射”是一个有效的 JSON 对象,其中是导入模块时模块说明符中可能存在的文本,相应的是解析模块说明符为地址时将替换此文本的 URL 或路径。

模块说明符映射 JSON 对象具有以下要求

  • 所有键都不能为空。
  • 所有值都必须是字符串,定义有效的绝对 URL 或以/./../开头的有效 URL 字符串。
  • 如果键以/结尾,则相应的键值也必须以/结尾。以尾部/结尾的键可用作映射(或重新映射)模块地址时的前缀。
  • 对象属性的顺序无关紧要:如果多个键可以匹配模块说明符,则使用最具体的键(换句话说,说明符“olive/branch/”将在“olive/”之前匹配)。
integrity 可选

定义一个有效的 JSON 对象,其中是包含有效绝对或相对 URL(以/./../开头)的字符串,相应的是有效的完整性元数据

如果导入或预加载模块的脚本的 URL 与integrity对象中的键匹配,则相应的完整性元数据将应用于脚本的获取选项,除非它们已经附加了完整性元数据。

scopes 可选

作用域定义路径特定的模块说明符映射,允许根据导入模块的代码的路径选择映射。

scopes 对象是一个有效的 JSON 对象,其中每个属性都是一个<scope key>(一个 URL 路径),其对应值为一个<module specifier map>

如果导入模块的脚本的 URL 与<scope key>路径匹配,则首先检查与键关联的<module specifier map>值以查找匹配的说明符。如果有多个匹配的作用域键,则首先检查与最具体/嵌套的作用域路径关联的值以查找匹配的模块说明符。如果在任何匹配的作用域模块说明符映射中都没有匹配的模块说明符键,则使用imports中的回退模块说明符映射。

请注意,作用域不会更改地址的解析方式;相对地址始终解析为导入映射基本 URL。

规范

规范
HTML 标准
# import-map

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅