<script> элемент HTML script

Элемент <script> HTML используется для встраивания исполняемого кода или данных; обычно он применяется для встраивания или подключения кода JavaScript. Элемент <script> также можно использовать с другими языками, например с языком программирования шейдеров GLSL из WebGL и с JSON.

Атрибуты

Этот элемент включает глобальные атрибуты.

async

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

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

Предупреждение: Для классических скриптов этот атрибут нельзя использовать, если атрибут src отсутствует (то есть для встроенных скриптов): в этом случае он не будет иметь эффекта.

Этот атрибут позволяет устранить блокировку анализа JavaScript-кодом, когда браузеру пришлось бы загружать и выполнять скрипты, прежде чем продолжить разбор документа. В этом случае defer оказывает похожий эффект.

Если атрибут указан вместе с атрибутом defer, элемент будет вести себя так, как если бы был указан только атрибут async.

Это булев атрибут: наличие булева атрибута у элемента означает значение true, а его отсутствие — значение false.

Примечания о поддержке браузерами см. в разделе Совместимость с браузерами. См. также Асинхронные скрипты для asm.js.

attributionsrc

Указывает, что вы хотите, чтобы браузер отправлял заголовок Attribution-Reporting-Eligible вместе с запросом ресурса скрипта. На стороне сервера это используется для отправки в ответе заголовка Attribution-Reporting-Register-Source или Attribution-Reporting-Register-Trigger, чтобы зарегистрировать источник атрибуции на основе JavaScript или триггер атрибуции на основе JavaScript соответственно. Выбор заголовка ответа зависит от значения заголовка Attribution-Reporting-Eligible, вызвавшего регистрацию.

Примечание: Кроме того, источники или триггеры атрибуции на основе JavaScript можно зарегистрировать, отправив запрос fetch() с параметром attributionReporting (заданным непосредственно в вызове fetch() или в объекте Request, переданном в вызов fetch()), либо отправив XMLHttpRequest с вызовом setAttributionReporting() для объекта запроса.

Можно задать одну из двух версий этого атрибута:

• Булево значение, то есть только имя attributionsrc. Указывает, что заголовок Attribution-Reporting-Eligible нужно отправить на тот же сервер, на который указывает атрибут src. Это подходит, если регистрация источника или триггера атрибуции обрабатывается на том же сервере. При регистрации триггера атрибуции это свойство необязательно; если его опустить, будет использоваться пустая строка.

• Значение, содержащее один или несколько URL-адресов, например:

  <script
    src="myscript.js"
    attributionsrc="https://a.example/register-source https://b.example/register-source"></script>
  

  Это полезно, если запрашиваемый ресурс находится на сервере, которым вы не управляете, или если вы хотите обрабатывать регистрацию источника атрибуции на другом сервере. В этом случае в качестве значения attributionsrc можно указать один или несколько URL-адресов. При выполнении запроса ресурса заголовок Attribution-Reporting-Eligible будет отправлен на URL-адреса, указанные в attributionSrc, а также на источник ресурса. Затем эти URL-адреса могут отправить заголовок Attribution-Reporting-Register-Source или Attribution-Reporting-Register-Trigger, чтобы завершить регистрацию.

  Примечание: Указание нескольких URL-адресов означает, что для одной и той же функции можно зарегистрировать несколько источников атрибуции. Например, у вас могут быть разные кампании, успешность которых нужно измерить, создавая для них разные отчёты на основе разных данных.

Дополнительные сведения см. в разделе API отчётов об атрибуции.

blocking

Этот атрибут явно указывает, что некоторые операции следует заблокировать до выполнения скрипта. Операции, которые нужно заблокировать, должны быть указаны в виде разделённого пробелами списка токенов блокировки. В настоящее время существует только один токен:

• render: отображение содержимого на экране блокируется.

Примечание: Блокировать отображение могут только элементы script в <head> документа. По умолчанию скрипты не блокируют отображение; если элемент script не содержит type="module", async или defer, он блокирует разбор, а не отображение. Если такой элемент script добавляется динамически с помощью скрипта, необходимо задать для него blocking = "render", чтобы он блокировал отображение.

crossorigin

Обычные элементы script передают минимум информации в window.onerror для скриптов, не прошедших стандартные проверки CORS. Используйте этот атрибут, чтобы разрешить регистрацию ошибок для сайтов, на которых статические медиафайлы размещены в отдельном домене. Более подробное объяснение допустимых значений см. в разделе Атрибуты настройки CORS.

defer

Этот булев атрибут указывает браузеру, что скрипт следует выполнить после разбора документа, но до срабатывания события DOMContentLoaded.

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

Предупреждение: Этот атрибут нельзя использовать, если атрибут src отсутствует (то есть для встроенных скриптов): в этом случае он не будет иметь эффекта.

Атрибут defer не влияет на модульные скрипты — по умолчанию они выполняются с отсрочкой.

Скрипты с атрибутом defer выполняются в том порядке, в котором они расположены в документе.

Этот атрибут позволяет устранить блокировку анализа JavaScript-кодом, когда браузеру пришлось бы загружать и выполнять скрипты, прежде чем продолжить разбор документа. В этом случае async оказывает похожий эффект.

Если атрибут указан вместе с атрибутом async, элемент будет вести себя так, как если бы был указан только атрибут async.

fetchpriority

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

high

Загрузить внешний скрипт с высоким приоритетом относительно других внешних скриптов.

low

Загрузить внешний скрипт с низким приоритетом относительно других внешних скриптов.

auto

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

integrity

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

nomodule

Этот булев атрибут указывает, что скрипт не следует выполнять в браузерах с поддержкой модулей ES. Таким образом можно предоставлять резервные скрипты для старых браузеров, не поддерживающих модульный код JavaScript.

nonce

Криптографический одноразовый номер (nonce), позволяющий использовать скрипты с директивой script-src в Content-Security-Policy. Сервер должен генерировать уникальное значение nonce при каждой отправке политики. Крайне важно, чтобы значение nonce невозможно было угадать, иначе обойти политику ресурса будет очень просто.

referrerpolicy

Указывает, какой реферер следует отправлять при загрузке скрипта или ресурсов, загружаемых скриптом:

• no-referrer: заголовок Referer не отправляется.
• no-referrer-when-downgrade: заголовок Referer не отправляется источникам без TLS (HTTPS).
• origin: отправляемый реферер ограничивается источником ссылающейся страницы: её схемой, хостом и портом.
• origin-when-cross-origin: реферер, отправляемый другим источникам, ограничивается схемой, хостом и портом. При переходах в пределах одного источника путь по-прежнему включается.
• same-origin: реферер отправляется для того же источника, но в междоменных запросах сведения о реферере отсутствуют.
• strict-origin: в качестве реферера отправляется только источник документа, если уровень безопасности протокола остаётся прежним (HTTPS→HTTPS), но он не отправляется при переходе к менее защищённому ресурсу (HTTPS→HTTP).
• strict-origin-when-cross-origin (по умолчанию): при запросе к тому же источнику отправляется полный URL, если уровень безопасности протокола остаётся прежним (HTTPS→HTTPS) — только источник, а при переходе к менее защищённому ресурсу (HTTPS→HTTP) заголовок не отправляется.
• unsafe-url: реферер включает источник и путь (но не фрагмент, пароль или имя пользователя). Это значение небезопасно, поскольку оно раскрывает источники и пути защищённых TLS-ресурсов незащищённым источникам.

Примечание: Пустая строка ("") является и значением по умолчанию, и резервным значением, если referrerpolicy не поддерживается. Если referrerpolicy явно не задан для элемента <script>, он будет использовать политику реферера более высокого уровня, то есть заданную для всего документа или домена. Если политика более высокого уровня недоступна, пустая строка считается эквивалентной strict-origin-when-cross-origin.

src

Этот атрибут задаёт URI внешнего скрипта; его можно использовать вместо непосредственного встраивания скрипта в документ.

type

Этот атрибут указывает тип представленного скрипта. Его значение может быть одним из следующих:

Атрибут не задан (по умолчанию), задана пустая строка или MIME-тип JavaScript

Указывает, что скрипт является «классическим скриптом» и содержит код JavaScript. Авторам рекомендуется не указывать атрибут, если скрипт содержит код JavaScript, вместо того чтобы задавать MIME-тип. MIME-типы JavaScript перечислены в спецификации типов мультимедиа IANA.

importmap

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

module

Это значение указывает, что код следует обрабатывать как модуль JavaScript. Выполнение содержимого скрипта откладывается. Атрибуты charset и defer не влияют на него. Сведения об использовании module см. в руководстве по модулям JavaScript. В отличие от классических скриптов, для загрузки модульных скриптов из других источников требуется протокол CORS.

speculationrules

Это значение указывает, что тело элемента содержит правила спекулятивной загрузки. Правила спекулятивной загрузки представлены объектом JSON, который определяет, какие ресурсы браузеру следует предварительно загрузить или отобразить. Это часть API правил спекулятивной загрузки.

Любое другое значение

Встроенное содержимое рассматривается как блок данных и не обрабатывается браузером. Для обозначения блоков данных разработчики должны использовать допустимый MIME-тип, отличный от MIME-типа JavaScript. Все остальные атрибуты, включая атрибут src, будут проигнорированы.

Устаревшие атрибуты

charset

Если атрибут присутствует, его значение должно совпадать без учёта регистра с utf-8 в ASCII. Указывать атрибут charset не нужно, поскольку документы должны использовать UTF-8, а элемент script наследует кодировку символов документа.

language

Как и атрибут type, этот атрибут указывает используемый язык скриптов. Однако, в отличие от атрибута type, допустимые значения этого атрибута никогда не были стандартизированы. Вместо него следует использовать атрибут type.

Примечания

Скрипты без атрибутов async, defer или type="module", а также встроенные скрипты без атрибута type="module", загружаются и выполняются немедленно, прежде чем браузер продолжит разбирать страницу.

Скрипт следует отдавать с MIME-типом text/javascript, однако браузеры проявляют снисходительность и блокируют его, только если он отдаётся с типом изображения (image/*), видео (video/*), аудио (audio/*) или text/csv. Если скрипт заблокирован, элементу отправляется событие error; в противном случае отправляется событие load.

Примеры

Основное использование

В этом примере показано, как импортировать внешний скрипт с помощью элемента <script>:

<script src="javascript.js"></script>

В следующем примере показано, как поместить встроенный скрипт в элемент <script>:

<script>
  alert("Hello World!");
</script>

async и defer

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

Скрипты, загруженные с атрибутом defer, загружаются в порядке их расположения на странице. Они не выполняются, пока не загрузится всё содержимое страницы. Это полезно, если скрипты зависят от наличия DOM (например, изменяют один или несколько элементов страницы).

Ниже показано, как разные способы загрузки скриптов влияют на страницу:

Это изображение взято из спецификации HTML, скопировано и обрезано до уменьшенной версии и распространяется на условиях лицензии CC BY 4.0.

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

<script async src="js/vendor/jquery.js"></script>
<script async src="js/script2.js"></script>
<script async src="js/script3.js"></script>

Нельзя полагаться на порядок загрузки скриптов. jquery.js может загрузиться до или после script2.js и script3.js; в этом случае любые функции этих скриптов, зависящие от jquery, вызовут ошибку, поскольку на момент выполнения скрипта jquery ещё не будет определён.

async следует использовать, если нужно загрузить несколько фоновых скриптов как можно скорее. Например, можно загружать файлы данных игры, которые понадобятся при её запуске, но пока продолжать отображать вступление, заголовки и лобби игры, не блокируя их загрузкой скриптов.

Скрипты, загруженные с атрибутом defer (см. ниже), будут запускаться в порядке расположения на странице, как только загрузятся скрипт и содержимое:

<script defer src="js/vendor/jquery.js"></script>
<script defer src="js/script2.js"></script>
<script defer src="js/script3.js"></script>

Во втором примере можно быть уверенным, что jquery.js загрузится до script2.js и script3.js, а script2.js — до script3.js. Они не будут выполняться, пока не загрузится всё содержимое страницы. Это полезно, если скрипты зависят от наличия DOM (например, изменяют один или несколько элементов страницы).

Итак:

• async и defer указывают браузеру загружать скрипты в отдельном потоке, пока загружается остальная часть страницы (DOM и т. д.), поэтому процесс загрузки страницы не блокируется.
• Скрипты с атрибутом async выполняются сразу после завершения загрузки. Это блокирует страницу и не гарантирует определённый порядок выполнения.
• Скрипты с атрибутом defer загружаются в заданном порядке и выполняются только после завершения загрузки всех ресурсов.
• Если скрипты нужно выполнить сразу и у них нет зависимостей, используйте async.
• Если скриптам нужно дождаться завершения разбора документа и они зависят от других скриптов и/или наличия DOM, загружайте их с помощью defer и размещайте соответствующие элементы <script> в том порядке, в котором браузер должен их выполнить.

Резервный вариант для модулей

Браузеры, поддерживающие значение module для атрибута type, игнорируют любые скрипты с атрибутом nomodule. Это позволяет использовать модульные скрипты и одновременно предоставлять резервные скрипты с пометкой nomodule для браузеров, которые их не поддерживают.

<script type="module" src="main.js"></script>
<script nomodule src="fallback.js"></script>

Импорт модулей с помощью importmap

При импорте модулей в скриптах, если не использовать функцию type=importmap, каждый модуль необходимо импортировать с помощью спецификатора, являющегося абсолютным или относительным URL-адресом. В примере ниже первый спецификатор модуля — абсолютный URL-адрес, а второй ("./shapes/square.js") разрешается относительно базового URL-адреса документа.

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

Карта импорта позволяет задать сопоставление, которое при совпадении может заменить текст спецификатора модуля. Приведённая ниже карта импорта определяет ключи circle и square, которые можно использовать как псевдонимы для указанных выше спецификаторов модулей.

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

Это позволяет импортировать модули по именам в спецификаторе модуля, а не по абсолютным или относительным URL-адресам.

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

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

Встраивание данных в HTML

Элемент <script> также можно использовать для встраивания данных в HTML с серверным рендерингом, указав в атрибуте type допустимый MIME-тип, отличный от JavaScript.

<!-- Generated by the server -->
<script id="data" type="application/json">
  {
    "userId": 1234,
    "userName": "Maria Cruz",
    "memberSince": "2000-01-01T00:00:00.000Z"
  }
</script>

<!-- Static -->
<script>
  const userInfo = JSON.parse(document.getElementById("data").text);
  console.log("User information: %o", userInfo);
</script>

Блокировка отображения до загрузки и выполнения скрипта

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

<script blocking="render" async src="async-script.js"></script>

Техническая сводка

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

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

См. также

• document.currentScript
• Статья Флавио Копеса о том, как эффективно загружать JavaScript, и различиях между async и defer
• Руководство по модулям JavaScript