Атрибуты импорта

Атрибуты импорта сообщают среде выполнения, как должен загружаться модуль, включая поведение разрешения, получения, парсинга и оценки модуля. Они поддерживаются в объявлениях import, export...from и динамических import().

Атрибуты могут быть прикреплены к любому типу оператора import/export from, включая импорт по умолчанию, импорт пространства имен и т. д. Они следуют строке спецификатора модуля и начинаются с ключевого слова with. При использовании с import() атрибуты указываются в параметре options как свойство with.

Синтаксис

import { names } from "module-name" with {};
import { names } from "module-name" with { key: "data" };
import { names } from "module-name" with { key: "data", key2: "data2" };
import { names } from "module-name" with { key: "data", key2: "data2", /* …, */ keyN: "dataN" };

export { names } from "module-name" with {};
export { names } from "module-name" with { key: "data" };
export { names } from "module-name" with { key: "data", key2: "data2" };
export { names } from "module-name" with { key: "data", key2: "data2", /* …, */ keyN: "dataN" };

Параметры

keyN

Ключ атрибута. Может быть идентификатором или строковым литералом. Все ключи должны быть уникальными и должны быть известны среде выполнения.

"dataN"

Значение атрибута. Должен быть строковым литералом.

Исключения

SyntaxError

Неподдерживаемый key был указан в статическом импорте.

TypeError

Неподдерживаемый key был указан в динамическом импорте.

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

Описание

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

Основной сценарий использования — загрузка не-JS модулей, таких как JSON-модули и CSS-модули. Рассмотрим следующее выражение:

import data from "https://example.com/data.json";

В Интернете каждое выражение импорта приводит к HTTP-запросу. Ответ затем подготавливается в значение JavaScript и предоставляется программе средой выполнения. Например, ответ может выглядеть так:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...
{"name":"Maria"}

Модули идентифицируются и парсятся только в соответствии с их типом MIME — расширение файла в URL не может использоваться для идентификации типа файла. В этом случае тип MIME — application/json, что указывает браузеру, что файл является JSON и должен быть разобран как JSON. Если по какой-то причине (например, сервер был взломан или предоставлены некорректные данные) тип MIME в ответе сервера установлен на text/javascript (для исходного кода JavaScript), то файл будет разобран и выполнен как код. Если файл "JSON" фактически содержит вредоносный код, объявление import непреднамеренно выполнит внешний код, представляя серьезную угрозу безопасности.

Атрибуты импорта решают эту проблему, позволяя автору явно указывать, как должен проверяться модуль. В частности, атрибут type позволяет вам проверить, что файл предоставлен с определенным типом MIME, и импорт завершится ошибкой, если используется другой тип MIME.

Например, приведенный выше код может быть написан так, чтобы указать, что ожидаемый тип — "json", и импорт завершится ошибкой, если он будет предоставлен с типом text/javascript (или любым типом MIME, кроме application/json):

import data from "https://example.com/data.json" with { type: "json" };

Атрибут type позволяет указать, что модули предоставляются как JSON, CSS или простой текст (и, по умолчанию, как JavaScript).

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

Стандартные атрибуты

Доступные атрибуты зависят от языка и среды выполнения. Стандарт ECMAScript определяет атрибут type со значениями "json" и "text".

Спецификация HTML также определяет атрибут type со значениями "json", "text" и "css" — это атрибуты, которые поддерживаются в браузерных средах.

JSON-модули ({ type: "json" })

Тип json указывает, что импортируемый файл должен содержать JSON. Вы можете загрузить JSON из файла в объект data с помощью следующего кода:

import data from "https://example.com/data.json" with { type: "json" };

Если файл предоставляется с любым типом MIME, кроме "application/json", импорт завершится ошибкой.

Атрибут type изменяет способ получения модуля (браузер отправляет запрос с заголовком Accept: application/json), но не изменяет способ парсинга или оценки модуля. Среда выполнения уже знает, как разобрать модуль как JSON, учитывая MIME-тип ответа. Он использует атрибут только для последующей проверки того, что модуль data.json фактически является JSON-модулем. Например, если заголовок ответа изменяется на Content-Type: text/javascript, программа завершится с ошибкой, аналогичной приведенной выше.

Спецификация явно указывает type: "json" для поддержки — если модуль заявлен как type: "json", и среда выполнения не отклоняет этот импорт, то он должен быть разобран как JSON.

Однако других требований к поведению нет: для импортов без атрибута type: "json" среда выполнения все равно может разобрать его как JSON, если безопасность в данной среде не является проблемой.

Браузеры, с другой стороны, неявно предполагают, что модуль является JavaScript, если type не указан, и завершают работу с ошибкой, если модуль не является JavaScript (например, JSON). Это гарантирует, что типы модулей всегда строго проверяются и предотвращает любые риски безопасности. Среды выполнения, не являющиеся браузерными, такие как Node и Deno, соответствуют семантике браузеров и применяют type для JSON-модулей.

Другими словами, если вы опустите type и попытаетесь импортировать файл как "application/json", вы обычно получите ошибку, подобную следующей:

Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "application/json". Strict MIME type checking is enforced for module scripts per HTML spec.

CSS-модули ({ type: "css" })

Спецификация HTML определяет тип css, который импортирует таблицу стилей в скрипт как объект CSSStyleSheet.

Ниже приведен код, показывающий, как вы можете импортировать стиль и добавить его в свой документ. Импорт вызовет исключение, если example_styles.css предоставляется с любым типом MIME, кроме "text/css".

import exampleStyles from "https://example.com/example_styles.css" with { type: "css" };

document.adoptedStyleSheets.push(exampleStyles);

Обратите внимание, что импорт CSS-модулей в рабочие процессы обычно не поддерживается, поскольку спецификация CSSOM предоставляет CSSStyleSheet только в контексте окна.

Текстовые модули ({ type: "text" })

Тип text позволяет импортировать исходный код модуля как строковое значение. Вы можете загрузить текст из файла в строку text с помощью следующего кода:

import text from "https://example.com/file.txt" with { type: "text" };

Файл будет запрошен с заголовком Accept: text/plain, но значение заголовка Content-Type ответа игнорируется, и все файлы парсятся как UTF-8. Он может содержать любые текстовые данные, даже JavaScript-код (который рассматривается как обычный текст).

Если возможно, предпочтите import source для получения скомпилированного модуля для последующей инстанцировки или import defer для отсрочки синхронной оценки модуля. Использование with { type: "text" } означает, что модуль не может повторно использовать кэш, если он был импортирован где-то еще, и пользовательская оценка строковых источников может быть несовместима со строгими настройками CSP.

Предполагаемая семантика для атрибутов импорта

Атрибут может изменять поведение среды выполнения на каждом этапе процесса загрузки модуля:

• Разрешение: атрибут является частью спецификатора модуля (строка в предложении from). Следовательно, при одной и той же строковой пути различные атрибуты могут приводить к загрузке совершенно разных модулей. Например, TypeScript поддерживает атрибут resolution-mode.

  import type { TypeFromRequire } from "pkg" with {
    "resolution-mode": "require",
  };
  

• Получение: например, CSS-модули получаются с destination, установленным в "style", JSON-модули получаются с destination: "json", а текстовые модули — с destination: "text". Это означает, что при одинаковом URL назначения сервер все равно может вернуть разное содержимое.
• Парсинг и оценка: среда выполнения может использовать атрибут для определения того, как парсить и оценивать модуль.

Примеры

Импорт JSON-модулей с атрибутом type

В data.json:

{
  "name": "Shilpa"
}

В index.html:

<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <script type="module">
      import data from "./data.json" with { type: "json" };

      const p = document.createElement("p");
      p.textContent = `name: ${data.name}`;
      document.body.appendChild(p);
    </script>
  </head>
  <body></body>
</html>

Запустите локальный HTTP-сервер (см. устранение неполадок) и перейдите на страницу index.html. Вы должны увидеть Shilpa на странице.

Использование атрибутов импорта с динамическим импортом

Атрибуты импорта также принимаются как второй параметр синтаксиса import().

const data = await import("./data.json", {
  with: { type: "json" },
});

Обратите внимание, что, как и статические импорты, динамические импорты кэшируются на время жизни среды (например, страницы или рабочего процесса). Если вы ожидаете, что эти данные изменятся (например, последние новости или баланс пользователя), вместо этого используйте Fetch API.

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

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

См. также

• import
• export
• import()
• Предложение по атрибутам импорта
• Предложение по JSON-модулям
• Предложение по импорту текста