<script type="importmap">

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

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

¥The importmap value of the type attribute of the <script> element indicates that the body of the element contains an import map.

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

¥An import map is a JSON object that allows developers to control how the browser resolves module specifiers when importing JavaScript modules. It provides a mapping between the text used as the module specifier in an import statement or import() operator, and the corresponding value that will replace the text when resolving the specifier. The JSON object must conform to the Import map JSON representation format.

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

¥An import map is used to resolve module specifiers in static and dynamic imports, and therefore must be declared and processed before any <script> elements that import modules using specifiers declared in the map. Note that the import map applies only to module specifiers in the import statement or import() operator for modules loaded into documents; it does not apply to the path specified in the src attribute of a <script> element or to modules loaded into workers or worklets.

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

¥For more information, see the Importing modules using import maps section in the JavaScript modules guide.

语法

¥Syntax

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

不得指定 srcasyncnomoduledefercrossoriginintegrityreferrerpolicy 属性。

¥The src, async, nomodule, defer, crossorigin, integrity, and referrerpolicy attributes must not be specified.

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

¥Only the first import map in the document with an inline definition is processed; any additional import maps and external import maps are ignored.

例外情况

¥Exceptions

TypeError

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

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

¥Browsers generate console warnings for other cases where the import map JSON does not conform to the import map schema.

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

¥An error event is fired at script elements with type="importmap" that are not processed. This might occur, for example, if module loading has already started when an import map is processed, or if multiple import maps are defined in the page.

描述

¥Description

当导入 JavaScript 模块 时,import 声明import() 运算符 都有一个 "模块说明符",表示要导入的模块。浏览器必须能够将此说明符解析为绝对 URL 才能导入模块。

¥When importing a JavaScript module, both the import statement and import() operator have a "module specifier" that indicates the module to be imported. A browser must be able to resolve this specifier to an absolute URL in order to import the module.

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

¥For example, the following statements import elements from the module specifier "./modules/shapes/square.js", which is a path relative to the base URL of the document, and the module specifier "https://example.com/shapes/circle.js", which is an absolute URL.

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

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

¥Import maps allow developers to specify (almost) any text they want in the module specifier; the map provides a corresponding value that will replace the text when the module specifier is resolved.

裸模块

¥Bare modules

下面的导入映射定义了一个 imports 键,该键具有一个带有属性 squarecircle 的 "模块说明符映射"。

¥The import map below defines an imports key that has a "module specifier map" with properties square and circle.

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

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

¥With this import map we can import the same modules as above, but using "bare modules" in our module specifiers:

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

映射路径前缀

¥Mapping path prefixes

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

¥A module specifier map key can also be used to remap a path prefix in a module specifier. Note that in this case the property and mapped path must both have a trailing forward slash (/).

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

然后我们可以导入一个圆形模块,如图所示。

¥We could then import a circle module as shown.

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

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

¥Paths in the module specifier map key

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

¥Module specifier keys do not have to be single word names ("bare names"). They can also contain or end with path separators, or be absolute URLs, or be relative URL paths that start with /, ./, or ../.

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

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

¥If there are several module specifier keys in a module specifier map that might match, then the most specific key will be selected (i.e. the one with the longer path/value).

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

¥A module specifier of ./foo/../js/app.js would be resolved to ./js/app.js before matching. This means that a module specifier key of ./js/app.js would match the module specifier even though they are not exactly the same.

作用域模块说明符映射

¥Scoped module specifier maps

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

¥You can use the scopes key to provide mappings that are only used if the script importing the module contains a particular URL path. If the URL of the loading script matches the supplied path, the mapping associated with the scope will be used. This allows different versions of the module to be used depending on what code is doing the importing.

例如,如果加载模块具有包含路径的 URL,下面的地图将仅使用作用域地图:"/modules/customshapes/"。

¥For example, the map below will only use the scoped map if the loading module has a URL that includes the path: "/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 键中的模块说明符映射。

¥If multiple scopes match the referrer URL, then the most specific scope path is used (the scope key name with the longest name). The browser falls back to the next most specific scoped path if there is no matching specifier, and so on, eventually falling back to the module specifier map in the imports key.

导入地图 JSON 表示

¥Import map JSON representation

以下是导入映射 JSON 表示形式的 "formal" 定义。

¥The following is a "formal" definition of the import map JSON representation.

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

¥The import map must be a valid JSON object that can define at most two optional keys: imports and scopes. Each key's value must be an object, which may be empty.

imports Optional

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

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

<module specifier map>

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

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

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

范围定义了特定于路径的 模块说明符映射,允许映射的选择取决于导入模块的代码的路径。

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

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

请注意,范围不会改变地址的解析方式;相对地址始终解析为导入映射基 URL。

规范

Specification
HTML Standard
# import-map

¥Specifications

浏览器兼容性

BCD tables only load in the browser

¥Browser compatibility

也可以看看