<script type="importmap">
的importmap
值type
属性<script>
元素 指示元素的主体包含导入映射。
导入映射是一个 JSON 对象,允许开发者控制浏览器在导入JavaScript 模块时如何解析模块说明符。它提供了在import
语句或import()
运算符中用作模块说明符的文本与在解析说明符时将替换该文本的对应值之间的映射关系。JSON 对象必须符合导入映射 JSON 表示格式。
导入映射用于解析静态和动态导入中的模块说明符,因此必须在任何使用映射中声明的说明符导入模块的<script>
元素之前声明和处理。请注意,导入映射仅适用于import
语句或import()
运算符中加载到文档中的模块的模块说明符;它不适用于<script>
元素的src
属性中指定的路径,也不适用于加载到工作线程或工作线程片段中的模块。
有关更多信息,请参阅 JavaScript 模块指南中的使用导入映射导入模块部分。
语法
<script type="importmap">
// JSON object defining import
</script>
不得指定src
、async
、nomodule
、defer
、crossorigin
、integrity
和referrerpolicy
属性。
仅处理文档中第一个具有内联定义的导入映射;任何其他导入映射和外部导入映射都将被忽略。
异常
描述
在导入JavaScript 模块时,import
语句和import()
运算符都具有指示要导入的模块的“模块说明符”。浏览器必须能够将此说明符解析为绝对 URL,才能导入模块。
例如,以下语句从模块说明符"./modules/shapes/square.js"
(相对于文档的基本 URL 的路径)和模块说明符"https://example.com/shapes/circle.js"
(绝对 URL)导入元素。
import { name as squareName, draw } from "./modules/shapes/square.js";
import { name as circleName } from "https://example.com/shapes/circle.js";
导入映射允许开发人员在模块说明符中指定(几乎)任何他们想要的文本;映射提供了相应的替换文本,该文本将在解析模块说明符时替换该文本。
裸模块
下面的导入映射定义了一个imports
键,该键具有一个“模块说明符映射”,其中包含属性square
和circle
。
<script type="importmap">
{
"imports": {
"square": "./module/shapes/square.js",
"circle": "https://example.com/shapes/circle.js"
}
}
</script>
使用此导入映射,我们可以导入与上面相同的模块,但在模块说明符中使用“裸模块”。
import { name as squareName, draw } from "square";
import { name as circleName } from "circle";
映射路径前缀
模块说明符映射键也可用于重新映射模块说明符中的路径前缀。请注意,在这种情况下,属性和映射路径都必须以尾部正斜杠 (/
) 结尾。
<script type="importmap">
{
"imports": {
"shapes/": "./module/shapes/",
"othershapes/": "https://example.com/modules/shapes/"
}
}
</script>
然后我们可以像所示那样导入圆形模块。
import { name as circleName } from "shapes/circle.js";
模块说明符映射键中的路径
模块说明符键不必是单个单词名称(“裸名称”)。它们还可以包含或以路径分隔符结尾,或为绝对 URL,或为以/
、./
或../
开头的相对 URL 路径。
{
"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/”时才使用作用域映射。
<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
键传递)定义完整性元数据。
<script type="importmap">
{
"imports": {
"square": "./module/shapes/square.js"
},
"integrity": {
"./module/shapes/square.js": "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
}
}
</script>
导入映射 JSON 表示
以下是导入映射 JSON 表示的“正式”定义。
导入映射必须是有效的 JSON 对象,最多可以定义两个可选键:imports
和scopes
。每个键的值必须是一个对象,该对象可以为空。
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 表格仅在浏览器中加载