<script type="importmap"> значение атрибута HTML

Значение importmap атрибута type элемента <script> указывает, что содержимое элемента представляет собой карту импорта.

Карта импорта — это объект JSON, который позволяет разработчикам управлять тем, как браузер разрешает спецификаторы модулей при импорте модулей JavaScript. Она задает соответствие между текстом, используемым в качестве спецификатора модуля в инструкции import или операторе import(), и соответствующим значением, которое заменит этот текст при разрешении спецификатора. Объект JSON должен соответствовать формату представления карты импорта в JSON.

Карта импорта используется для разрешения спецификаторов модулей при статическом и динамическом импорте, поэтому ее необходимо объявить и обработать до любых элементов <script>, импортирующих модули с использованием спецификаторов, объявленных в карте. Обратите внимание: карта импорта применяется только к спецификаторам модулей в инструкции import или операторе import() для модулей, загружаемых в документы; она не применяется к пути, указанному в атрибуте src элемента <script>, или к модулям, загружаемым в рабочие потоки и рабочие области.

Дополнительные сведения см. в разделе «Импорт модулей с помощью карт импорта» руководства по модулям JavaScript.

Синтаксис

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

Атрибуты src, async, nomodule, defer, crossorigin, integrity и referrerpolicy указывать нельзя.

Исключения

TypeError

Определение карты импорта не является объектом JSON, ключ importmap определен, но его значение не является объектом JSON, или ключ scopes определен, но его значение не является объектом JSON.

В других случаях, когда JSON карты импорта не соответствует схеме карты импорта, браузеры выводят предупреждения в консоль.

Описание

При импорте модуля JavaScript и инструкция import, и оператор import() содержат «спецификатор модуля», указывающий на импортируемый модуль. Браузер должен уметь разрешить этот спецификатор в абсолютный URL, чтобы импортировать модуль.

Например, следующие инструкции импортируют элементы из модуля, указанного спецификатором "https://example.com/shapes/circle.js", который является абсолютным URL, и спецификатором "./modules/shapes/square.js", который представляет собой путь относительно базового URL документа.

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

Карты импорта позволяют разработчикам указывать (почти) любой текст в качестве спецификатора модуля; карта предоставляет соответствующее значение, которое заменит этот текст при разрешении спецификатора.

Модули без указания пути

Приведенная ниже карта импорта определяет ключ imports, которому сопоставлена «карта спецификаторов модулей» со свойствами circle и square.

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

С помощью этой карты импорта можно импортировать те же модули, что и выше, но использовать в спецификаторах модулей «модули без указания пути»:

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

Сопоставление префиксов путей

Ключ карты спецификаторов модулей также можно использовать для переназначения префикса пути в спецификаторе модуля. Обратите внимание: в этом случае и свойство, и сопоставленный путь должны оканчиваться косой чертой (/).

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

Тогда можно импортировать модуль с окружностью, как показано ниже.

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

Пути в ключе карты спецификаторов модулей

Ключи спецификаторов модулей не обязательно должны состоять из одного слова («простые имена»). Они также могут содержать или оканчиваться разделителями путей, быть абсолютными URL или относительными URL-путями, начинающимися с /, ./ или ../.

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

Если в карте спецификаторов модулей есть несколько ключей, которые могут совпасть, будет выбран наиболее конкретный ключ (то есть ключ с более длинным путем или значением).

Перед сопоставлением спецификатор модуля ./foo/../js/app.js будет разрешен в ./js/app.js. Это означает, что ключ спецификатора модуля ./js/app.js будет соответствовать спецификатору модуля, хотя они и не совпадают в точности.

Области действия карт спецификаторов модулей

Ключ scopes позволяет задавать соответствия, которые используются только в том случае, если URL-путь скрипта, импортирующего модуль, соответствует заданному пути. Если URL загружающего скрипта совпадает с указанным путем, будет использовано соответствие, связанное с этой областью. Это позволяет использовать разные версии модуля в зависимости от того, какой код его импортирует.

Например, в приведенной ниже карте соответствие в заданной области будет использоваться, только если URL загружаемого модуля содержит путь «/modules/custom-shapes/».

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

Если URL-адресу источника соответствуют несколько областей, используется наиболее конкретный путь области (ключ с самым длинным именем). Если соответствующий спецификатор не найден, браузер переходит к следующему по степени конкретности пути области и так далее, пока в итоге не перейдет к карте спецификаторов модулей в ключе imports.

Карта метаданных целостности

Ключ integrity позволяет задавать соответствия для метаданных целостности модулей. Это позволяет обеспечивать целостность динамически или статически импортируемых модулей. integrity также позволяет задать значение по умолчанию для модулей верхнего уровня или предварительно загруженных модулей на случай, если у них уже нет атрибута integrity.

Ключи карты представляют URL-адреса модулей, которые могут быть абсолютными или относительными (начинающимися с /, ./ или ../). Значения карты представляют метаданные целостности, идентичные тем, что используются в значениях атрибута integrity.

Например, приведенная ниже карта задает метаданные целостности для модуля square.js (непосредственно) и его простого спецификатора (опосредованно, через ключ imports).

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

Объединение нескольких карт импорта

Браузеры с поддержкой этой функции могут объявлять одну или несколько карт импорта в любом месте документа, если они определены до загрузки любых зависящих от них модулей (некоторые версии браузеров допускают объявление только одной карты импорта, которая должна быть указана до загрузки любого модуля).

Внутри браузеры поддерживают единое глобальное представление карты импорта. Когда документ содержит несколько карт импорта, их содержимое объединяется в глобальную карту импорта при регистрации.

Рассмотрим, например, следующие две карты импорта:

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

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

Они эквивалентны следующей единой карте импорта:

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

Спецификаторы модулей в каждой зарегистрированной карте, которые уже были разрешены ранее, отбрасываются. При последующем разрешении этих спецификаторов будут получены те же результаты, что и при предыдущем.

Например, если спецификатор модуля /app/helper.js уже был разрешен, следующая новая карта импорта:

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

Будет эквивалентна следующей:

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

Правило /app/helper.js было проигнорировано и не включено в карту.

Аналогично, спецификаторы модулей в зарегистрированной карте, для которых в глобальной карте уже заданы URL-адреса, отбрасываются; ранее заданные соответствия имеют приоритет.

Например, следующие две карты импорта:

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

Эквивалентны следующей единой карте импорта:

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

Правило /app/helper/ было отброшено из второй карты.

Представление карты импорта в JSON

Ниже приведено «формальное» определение представления карты импорта в JSON.

Карта импорта должна быть допустимым объектом JSON, в котором могут быть определены любые из необязательных ключей imports, scopes и integrity. Значение каждого ключа должно быть объектом, который может быть пустым.

imports Необязательно

Значением является карта спецификаторов модулей, которая задает соответствия между текстом спецификатора модуля, который может встречаться в инструкции import или операторе import(), и текстом, который заменит его при разрешении спецификатора.

Это карта по умолчанию, в которой выполняется поиск подходящих спецификаторов модулей, если URL-пути scopes не совпадают или если карты спецификаторов модулей в соответствующих путях scopes не содержат ключа, совпадающего со спецификатором модуля.

<module specifier map>

«Карта спецификаторов модулей» — это допустимый объект JSON, в котором ключи представляют собой текст, который может присутствовать в спецификаторе модуля при его импорте, а соответствующие значения — URL-адреса или пути, которые заменят этот текст при разрешении спецификатора модуля в адрес.

К объекту JSON карты спецификаторов модулей предъявляются следующие требования:

• Ни один из ключей не может быть пустым.
• Все значения должны быть строками, задающими допустимый абсолютный URL или допустимую строку URL, начинающуюся с /, ./ или ../.
• Если ключ оканчивается на /, соответствующее значение также должно оканчиваться на /. Ключ с конечным / можно использовать как префикс при сопоставлении (или переназначении) адресов модулей.
• Порядок свойств объекта не имеет значения: если спецификатору модуля соответствуют несколько ключей, используется наиболее конкретный (другими словами, спецификатор «olive/branch/» будет соответствовать раньше, чем «olive/»).

integrity Необязательно

Определяет допустимый объект JSON, в котором ключами являются строки с допустимыми абсолютными или относительными URL-адресами (начинающимися с /, ./ или ../), а соответствующие значения — допустимые метаданные целостности.

Если URL скрипта, импортирующего или предварительно загружающего модуль, совпадает с ключом объекта integrity, соответствующие метаданные целостности применяются к параметрам запроса скрипта, если к ним еще не прикреплены метаданные целостности.

scopes Необязательно

Области задают карты спецификаторов модулей для отдельных путей, позволяя выбирать карту в зависимости от пути кода, импортирующего модуль.

Объект областей — это допустимый объект JSON, где каждое свойство является <scope key>, то есть URL-путем, а соответствующее ему значение является <module specifier map>.

Если URL скрипта, импортирующего модуль, совпадает с путем <scope key>, значение <module specifier map>, связанное с этим ключом, сначала проверяется на наличие соответствующих спецификаторов. Если совпадают несколько ключей областей, сначала проверяются значения, связанные с наиболее конкретными/вложенными путями областей. Карта спецификаторов модулей по умолчанию из imports используется, если ни в одной из соответствующих карт спецификаторов модулей для областей не найден подходящий ключ.

Обратите внимание: область не меняет способ разрешения адреса; относительные адреса всегда разрешаются относительно базового URL карты импорта.

Спецификации

Совместимость с браузерами

См. также

• Модули JavaScript > Импорт модулей с помощью карт импорта
• Атрибут type элементов HTML <script>
• Инструкция import
• Оператор import()