<script> – елемент сценарію

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

Атрибути

Цей елемент приймає глобальні атрибути.

async

Для класичних сценаріїв, коли присутній атрибут async, то такий класичний скрипт отримується паралельно до розбору сторінки, і виконується відразу, коли стає доступним.

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

[!WARNING] Цей атрибут не повинен вживатися, якщо атрибут src відсутній (тобто для вбудованих сценаріїв) для класичних сценаріїв – у цьому разі він не має жодного впливу.

Цей атрибут дає змогу усунути проблему JavaScript, що блокує розбір сторінки: браузеру не потрібно завантажувати й виконувати сценарії до продовження розбору. defer в цьому випадку має подібну дію.

Якщо цей атрибут заданий вкупі з атрибутом defer, елемент діє так, ніби задано лише атрибут async.

Це булів атрибут: присутність булевого атрибута відповідає значенню істинності, а його відсутність – значенню хибності.

Дивіться Сумісність із браузерами для отримання приміток щодо підтримки браузерами. Дивіться також Асинхронні сценарії для asm.js.

attributionsrc

Задає те, що ви хочете, аби браузер надіслав заголовок Attribution-Reporting-Eligible вкупі з запитом на ресурс сценарію. На серверному боці такий заголовок використовується для запуску надсилання у відповіді заголовка Attribution-Reporting-Register-Source або Attribution-Reporting-Register-Trigger, щоб зареєструвати засноване на JavaScript джерело атрибуції або пускача атрибуції відповідно. Те, який заголовок відповіді слід надсилати у відповідь, залежить від значення заголовка Attribution-Reporting-Eligible, що спричинив реєстрацію.

[!NOTE] Інший варіант: на основі 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>
  

  Це корисно в тих випадках, коли запитаний ресурс не перебуває на сервері під вашим контролем або просто хочеться обробляти реєстрацію джерела атрибуції на іншому сервері. Тоді можна задати одну або більше адрес URL як значення attributionsrc. Коли відбувається запит на ресурс, заголовок Attribution-Reporting-Eligible надсилається на адреси URL, задані в attributionSrc, а не лише за походженням ресурсу. Ці адреси URL потім можуть відповісти заголовком Attribution-Reporting-Register-Source або Attribution-Reporting-Register-Trigger відповідно для завершення реєстрації.

  [!NOTE] Задання кількох адрес URL означає те, що на один елемент можна зареєструвати кілька джерел атрибуції. Можна, наприклад, мати різні кампанії, для вимірювання успішності яких потрібно генерувати різні звіти щодо різних даних. Дивіться подробиці в API звітування атрибуції.

blocking

Цей атрибут явно вказує, що певні операції повинні бути заблоковані отриманням такого сценарію. Операції до блокування повинні бути розділеним пробілами списком лексем блокування, перелічених нижче.

• render: Візуалізація вмісту на екрані – заблокована.

crossorigin

Звичайні елементи script передають window.onerror украй обмежену інформацію щодо сценаріїв, що не проходять стандартних перевірок CORS. Щоб дозволити логування помилок для сайтів, котрі використовують окремий домен для статичних мультимедійних файлів, слід використовувати цей атрибут. Дивіться Атрибути налаштувань CORS для отримання більш докладного пояснення його дійсних аргументів.

defer

Цей булів атрибут встановлюється, аби вказати браузерові, що сценарій треба виконувати після розбору сторінки, але до викидання події DOMContentLoaded.

Сценарії, що мають атрибут defer, затримуватимуть викидання події DOMContentLoaded, поки не будуть завантажені й не завершать виконання.

[!WARNING] Цей атрибут не повинен застосовуватися, якщо атрибут src – відсутній (наприклад, у вбудованих сценаріїв); в такому випадку він не матиме дії.

Атрибут defer не має дії на модульних сценаріях: вони відкладаються усталено.

Сценарії з атрибутом defer будуть виконуватися в тому порядку, в якому вони зустрічаються в документі.

Цей атрибут дає змогу усунути проблему JavaScript, що блокує розбір сторінки: браузеру не потрібно завантажувати й виконувати сценарії до продовження розбору. async в цьому випадку має подібну дію.

Якщо цей атрибут заданий вкупі з атрибутом async, елемент діє так, ніби задано лише атрибут async.

fetchpriority

Надає підказку щодо відносного пріоритету при отриманні зовнішнього сценарію. Дозволені значення:

high

Отримує зовнішній сценарій із високим пріоритетом відносно інших зовнішніх сценаріїв.

low

Отримує зовнішній сценарій із низьким пріоритетом відносно інших зовнішніх сценаріїв.

auto

Не задає налаштування пріоритету отримання. Це усталене значення. Воно вживається, якщо значення не задано або задане значення – невалідне.

Докладніше в HTMLScriptElement.fetchPriority.

integrity

Цей атрибут містить супутні метадані, котрі користувацький агент може використати для перевірки того, що отриманий ресурс був доставлений без неочікуваних втручань. Він не повинен задаватися, коли не задано атрибут src. Дивіться Цілісність підресурсу.

nomodule

Цей булів атрибут встановлюється, аби вказати, що сценарій не повинен виконуватися в браузерах, що підтримують модулі ES; може використовуватися для надання запасних сценаріїв старішим браузерам, що не підтримують модульний код JavaScript.

nonce

Криптографічне одноразове значення, що дозволяє сценарії в script-src політики безпеки вмісту. Сервер мусить породити унікальне значення 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 ресурсів до незахищених походжень.

[!NOTE] Значення порожнього рядка ("") є водночас і усталеним значенням, і запасним значенням, коли 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

Коли цей атрибут присутній, його значення мусить бути нечутливим до регістру ASCII-відповідником до utf-8. Немає потреби вказувати атрибут 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("Привіт, світе!");
</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. У прикладі нижче перший модульний специфікатор ("./shapes/square.js") розв'язується відносно базового URL документа, а другий – є абсолютним URL.

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

Карта імпортування дає змогу надати відображення, котре, якщо дає збіг, може замінити текст у модульному специфікаторі. Карта імпортування нижче визначає ключі square та circle, котрі можуть бути застосовані як псевдоніми для модульних специфікаторів, показаних вище.

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

Це дає змогу імпортувати модулі за допомогою імен (а не абсолютних чи відносних URL).

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

Більше прикладів того, що можна робити з картами імпортування, дивіться в розділі Імпорт модулів за допомогою карт імпортування посібника з модулів JavaScript.

Вбудовування даних в HTML

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

<!-- Породжено сервером -->
<script id="data" type="application/json">
  {
    "userId": 1234,
    "userName": "Марія Карімназарова",
    "memberSince": "2000-01-01T00:00:00.000Z"
  }
</script>

<!-- Статичне -->
<script>
  const userInfo = JSON.parse(document.getElementById("data").text);
  console.log("Інформація про користувача: %o", userInfo);
</script>

Блокування візуалізації до отримання й виконання сценарію

Лексему render можна включити в атрибут blocking; тоді візуалізація сторінки буде заблокована, поки сценарій не буде отриманий та виконаний. У прикладі нижче візуалізація блокується асинхронним сценарієм, щоб сценарій не блокував розбору коду, але гарантовано виконався до початку візуалізації.

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

Технічний підсумок

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

Сумісність із браузерами

Дивіться також

• document.currentScript
• Стаття Флавіо Коупса про ефективне завантаження JavaScript та пояснення відмінностей між async і defer
• Посібник Модулі JavaScript