<script type="importmap">

¥Syntax

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

不得指定 src、async、nomodule、defer、crossorigin、integrity 和 referrerpolicy 属性。

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

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 键，该键具有一个带有属性 square 和 circle 的 "模块说明符映射"。

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

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

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 (/).

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

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

¥We could then import a circle module as shown.

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

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

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

¥Integrity metadata map

你可以使用 integrity 键为模块 完整性元数据 提供映射。这使你能够确保动态或静态导入模块的完整性。integrity 还使你能够为顶层或预加载的模块提供后备，以防它们尚未包含 integrity 属性。

¥You can use the integrity key to provide mapping for module integrity metadata. This enables you to ensure the integrity of dynamically or statically imported modules. integrity also enables you to provide a fallback for top-level or preloaded modules, in case they don't already include an integrity attribute.

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

¥The map keys represent module URLs, which can be absolute or relative (starting with /, ./, or ../). The map values represent integrity metadata, identical to that used in integrity attribute values.

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

¥For example, the map below defines integrity metadata for the square.js module (directly) and its bare specifier (transitively, via the imports key).

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

¥Import map JSON representation

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

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

导入映射必须是有效的 JSON 对象，最多可以定义两个可选键：imports 和 scopes。每个键的值必须是一个对象，可以为空。

¥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/" 之前匹配）。

integrity Optional

定义一个有效的 JSON 对象，其中键是包含有效绝对或相对 URL 的字符串（以 /、./ 或 ../ 开头），相应的值是有效的 完整性元数据。

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

scopes Optional

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

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

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

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

¥See also

• JavaScript 模块 > 使用导入映射导入模块
• HTML <script> 元素的 type 属性
• import 声明
• import() 运算符