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

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

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

Синтаксис

<script type="speculationrules">
  // JSON object defining rules
</script>

Исключения

TypeError

Определение правил спекулятивной загрузки не является допустимым объектом JSON.

Описание

Элемент <script type="speculationrules"> должен содержать допустимую структуру JSON, определяющую правила спекулятивной загрузки. В следующих примерах показаны отдельные правила предварительной загрузки и предварительного отображения:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "urls": ["next.html", "next2.html"],
        "requires": ["anonymous-client-ip-when-cross-origin"],
        "referrer_policy": "no-referrer"
      }
    ]
  }
</script>

<script type="speculationrules">
  {
    "prerender": [
      {
        "where": { "href_matches": "/next" },
        "eagerness": "eager"
      }
    ]
  }
</script>

Представление правил спекулятивной загрузки в формате JSON

Структура JSON содержит одно или несколько полей верхнего уровня, каждое из которых представляет действие, для которого определяются правила спекулятивной загрузки. На данный момент поддерживаются следующие действия:

"prefetch" Необязательно

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

"prerender" Необязательно

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

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

Каждый объект может содержать следующие свойства:

"source"

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

Возможны следующие значения:

"document"

Указывает, что URL-адреса будут сопоставляться со ссылками навигации в соответствующем документе (определяемыми элементами <a> и <area>) на основании условий, описанных ключом "where". Обратите внимание, что наличие ключа "where" подразумевает "source": "document", поэтому он необязателен.

"list"

Указывает, что URL-адреса будут взяты из списка, заданного ключом "urls". Обратите внимание, что наличие ключа "urls" подразумевает "source": "list", поэтому он необязателен.

"urls"

Массив строк, представляющих список URL-адресов, к которым применяется правило. Это могут быть абсолютные или относительные URL-адреса. Относительные URL-адреса будут анализироваться относительно базового URL-адреса документа (если правило встроено в документ) или относительно URL-адреса внешнего ресурса (если он загружен извне). В одном правиле нельзя одновременно указывать "urls" и "where".

"where"

Объект, представляющий условия, по которым правило сопоставляет URL-адреса, содержащиеся в соответствующем документе. Фактически объект "where" представляет собой проверку, выполняемую для каждой ссылки на странице, чтобы определить, применяется ли к ней правило спекулятивной загрузки. В одном правиле нельзя одновременно указывать "where" и "urls".

Этот объект может содержать ровно одно из следующих свойств:

"href_matches"

Строка с шаблоном URL-адреса или массив со строками нескольких шаблонов URL-адресов, соответствующих стандартному синтаксису API шаблонов URL-адресов. Для ссылок в документе, URL-адреса которых соответствуют шаблону или шаблонам, будет применено правило.

"relative_to"

Для условия "href_matches" это свойство задаёт, относительно чего следует проверять соответствие условию. Оно работает точно так же, как ключ "relative_to" на уровне правила, но влияет только на одно условие "href_matches" внутри ключа "where".

"selector_matches"

Строка с селектором CSS или массив с несколькими селекторами CSS. К ссылкам в документе, соответствующим этим селекторам, будет применено правило.

"and"

Массив, содержащий один или несколько объектов с условиями ("href_matches", "selector_matches", "and", "not" или "or"). Для применения правила к ссылкам должны выполняться все условия.

"not"

Объект, содержащий одно условие ("href_matches", "selector_matches", "and", "not" или "or"). Если условие выполняется, правило к ссылке не применяется. Правило применяется ко всем ссылкам, которые не соответствуют условию.

"or"

Массив, содержащий один или несколько объектов с условиями ("href_matches", "selector_matches", "and", "not" или "or"). Для применения правила к ссылкам достаточно выполнения любого из условий.

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

"eagerness"

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

"immediate"

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

"eager"

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

"moderate"

Автор стремится найти баланс между eager и conservative. Предварительную загрузку или отображение следует начинать, когда есть веские основания полагать, что пользователь скоро перейдёт по ссылке. Например, пользователь может прокрутить страницу так, чтобы ссылка попала в область просмотра, и некоторое время наводить на неё курсор или устанавливать на ней фокус.

"conservative"

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

Если "eagerness" не задано явно, для правил со списком ("urls") по умолчанию используется immediate, а для правил документа ("where") — conservative. Браузер учитывает эту подсказку наряду с собственными эвристиками, поэтому может выбрать ссылку, для которой автор указал меньшую активность, если такой вариант сочтёт предпочтительнее.

"expects_no_vary_search"

Строка, подсказывающая браузеру, какое значение заголовка No-Vary-Search будет указано в ответах для документов, запросы на предварительную загрузку или отображение которых он отправляет. Браузер может использовать это значение, чтобы заранее определить, целесообразнее ли дождаться завершения уже выполняющейся предварительной загрузки или отображения либо начать новый запрос на загрузку при совпадении с правилом спекулятивной загрузки. Дополнительные пояснения приведены в примере "expects_no_vary_search".

"referrer_policy"

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

Примечание: Для межсайтовой предварительной загрузки требуется политика реферера не менее строгая, чем значение по умолчанию "strict-origin-when-cross-origin", то есть "strict-origin-when-cross-origin", "same-origin", "strict-origin" или "no-referrer". Менее строгая политика, заданная в правилах спекулятивной загрузки, переопределит более строгую политику ссылающейся страницы, если она всё ещё достаточно строга для межсайтового случая.

Примечание: Для правил документа будет использоваться политика реферера, заданная для соответствующей ссылки (например, с помощью атрибута referrerpolicy), если только правило не задаёт переопределяющую её политику.

"relative_to"

Строка, указывающая, относительно чего следует сопоставлять ссылки по URL-адресу. Возможны следующие значения:

document

URL-адреса следует сопоставлять относительно документа, для которого задаются правила спекулятивной загрузки.

ruleset

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

Этот ключ имеет значение только для правил, заданных во внешнем файле (с помощью заголовка Speculation-Rules). Если правила указаны непосредственно в том же документе, для которого они задаются (то есть во встроенном элементе <script>), разницы нет.

"requires"

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

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

Возможны следующие значения:

"anonymous-client-ip-when-cross-origin"

(только для предварительной загрузки) Указывает, что правило применяется, только если пользовательский агент может скрыть IP-адрес клиента от исходного сервера при отправке межсайтового запроса на предварительную загрузку. Точный принцип работы зависит от особенностей реализации в браузере. Например:

• В реализации Chrome IP-адрес скрывается с помощью прокси-сервера Google, поэтому по умолчанию функция работает только для источников перехода, контролируемых Google (поскольку в этом случае передача URL-адресов назначения Google не создаёт дополнительной утечки конфиденциальных данных). На сайте, не принадлежащем Google, правила с этим значением будут применяться только к пользователям, включившим «Расширенную предварительную загрузку» в chrome://settings/preloading.
• Другим браузерам на базе Chromium потребуется предоставить собственные решения. Рекомендуется тщательно протестировать функцию во всех целевых браузерах.
• В будущей реализации Safari, возможно, будет использоваться нечто похожее на iCloud Private Relay.
• В будущей реализации Firefox может использоваться решение на основе продукта Mozilla VPN.

"tag"

Строка, используемая для идентификации правила или набора правил. Она будет включена в заголовок запроса Sec-Speculation-Tags для всех спекулятивных загрузок, охватываемых этим правилом.

"target_hint"

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

"target_hint": "_blank"

Открыть повторно отображённое содержимое на новой странице.

"target_hint": "_self"

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

Примеры

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

В основных примерах из раздела «Описание» были показаны отдельные правила спекулятивной загрузки для предварительной загрузки и предварительного отображения. Их можно определить в одном наборе правил:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "urls": ["next.html", "next2.html"],
        "requires": ["anonymous-client-ip-when-cross-origin"],
        "referrer_policy": "no-referrer"
      }
    ],
    "prerender": [
      {
        "where": { "selector_matches": ".product-link" },
        "eagerness": "eager"
      }
    ]
  }
</script>

Несколько наборов правил

Также можно включить несколько наборов правил в один HTML-файл:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "urls": ["next.html", "next2.html"],
        "requires": ["anonymous-client-ip-when-cross-origin"],
        "referrer_policy": "no-referrer"
      }
    ]
  }
</script>
<script type="speculationrules">
  {
    "prerender": [
      {
        "where": { "selector_matches": ".product-link" },
        "eagerness": "eager"
      }
    ]
  }
</script>

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

<script type="speculationrules">
  {
    "prerender": [
      {
        "urls": ["one.html"]
      },
      {
        "urls": ["two.html"]
      }
    ]
  }
</script>

Динамическое добавление правил

Ниже приведён пример, который проверяет поддержку правил спекулятивной загрузки и, если она имеется, динамически добавляет правило спекулятивного предварительного отображения с помощью JavaScript:

if (
  HTMLScriptElement.supports &&
  HTMLScriptElement.supports("speculationrules")
) {
  const specScript = document.createElement("script");
  specScript.type = "speculationrules";
  const specRules = {
    prerender: [
      {
        urls: ["/next.html"],
      },
    ],
  };
  specScript.textContent = JSON.stringify(specRules);
  console.log("added speculation rules to: next.html");
  document.body.append(specScript);
}

Примеры синтаксиса where

Правило с источником document содержит свойство "where" — объект с критериями, определяющими, какие ссылки в документе подходят под правило. Фактически объект "where" представляет собой проверку, выполняемую для каждой ссылки на странице, чтобы определить, применяется ли к ней правило спекулятивной загрузки.

В самом простом случае будет сопоставлен один шаблон URL-адреса или селектор CSS:

{ "where": { "href_matches": "/next" } }

{ "where": { "selector_matches": ".important-link" } }

Для "href_matches" и "selector_matches" также можно задать массив значений, чтобы одновременно сопоставить несколько шаблонов URL-адресов или селекторов CSS:

{ "where": { "href_matches": ["/next", "/profile"] } }

{ "where": { "selector_matches": [".important-link", "#unique-link"] } }

Шаблоны URL-адресов и селекторы также могут содержать подстановочные символы (*), позволяющие одному значению соответствовать нескольким URL-адресам. Например, приведённый ниже объект может соответствовать user/, user/settings, user/stats и т. д.

{ "where": { "href_matches": "/user/*" } }

В href_matches можно также указывать параметры поиска (или строки запроса). Например, приведённый ниже объект может соответствовать всем URL-адресам того же источника, содержащим параметр поиска category (первый или последующий параметр):

{ "where": { "href_matches": "/*\\?*(^|&)category=*" } }

Любое условие можно инвертировать, поместив его внутрь условия "not". Это означает, что при совпадении условие не позволит применить к ссылке правило спекулятивной загрузки, а при отсутствии совпадения позволит. В следующем примере правило будет применено ко всем ссылкам, которые не соответствуют шаблону URL-адреса /logout, но не к ссылкам, соответствующим /logout:

{ "where": { "not": { "href_matches": "/logout" } } }

Объединение нескольких условий "where" с помощью "and" или "or"

Несколько условий можно объединить внутри условий "and" или "or". Они принимают массивы с несколькими условиями, все или любое из которых (соответственно) должны выполняться, чтобы применить правила спекулятивной загрузки к ссылке. Используя "and" или "or", условия можно вкладывать на несколько уровней — ограничений на глубину вложенности нет.

Полезно рассматривать объект "where" как эквивалент инструкции if. Таким образом,

{ and: [A, B, { or: [C, { not: D }] }] }

эквивалентно

if (A && B && (C || !D)) {
  apply speculation rule
}

В следующем полном примере правила спекулятивной загрузки все страницы того же источника помечаются для предварительной загрузки, кроме тех, которые заведомо вызывают проблемы: страницы /logout и любых ссылок с классом .no-prerender:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "where": {
          "and": [
            { "href_matches": "/*" },
            { "not": { "href_matches": "/logout" } },
            { "not": { "selector_matches": ".no-prerender" } }
          ]
        }
      }
    ]
  }
</script>

Пример "relative_to"

Для наборов правил, загружаемых извне (например, через заголовок ответа Speculation-Rules), URL-адреса в правилах со списком и шаблоны URL-адресов в правилах документа по умолчанию анализируются относительно URL-адреса внешнего текстового файла, содержащего эти правила. Чтобы анализировать URL-адреса в правиле со списком относительно базового URL-адреса документа, используется "relative_to", например:

{
  "urls": ["/home", "/about"],
  "relative_to": "document"
}

В правилах документа "relative_to" можно непосредственно сочетать с "href_matches", и тогда базовый URL-адрес документа будет использоваться только для шаблонов в этом конкретном условии:

{
  "where": {
    "or": [
      { "href_matches": "/home", "relative_to": "document" },
      { "href_matches": "/about" }
    ]
  }
}

В приведённом выше примере относительно базового URL-адреса документа будет сопоставляться только первый "href_matches".

relative_to имеет значение главным образом в том случае, если файл JSON с правилами спекулятивной загрузки находится в источнике, отличном от источника документа, к которому эти правила применяются:

1. Если документ расположен по адресу https://example.com/some/subpage.html, а правила — по адресу https://example.com/resources/rules.json, то /home всегда соответствует https://example.com/home, независимо от того, установлено ли для relative_to значение document или ruleset.

2. Однако если документ расположен по адресу https://example.com/some/subpage.html, а правила — по адресу https://other.example/resources/rules.json (например, в стороннем источнике или источнике ресурсов без файлов cookie), то:

   • "relative_to": "document" приведёт к тому, что /home будет соответствовать https://example.com/home.
   • "relative_to": "ruleset" приведёт к тому, что /home будет соответствовать https://other.example/home.

   Это типичный сценарий использования "relative_to".

3. Ещё один возможный (но менее распространённый) сценарий — когда URL-адреса указаны в форме home, а не /home. Если документ расположен по адресу https://example.com/some/subpage.html, а правила — по адресу https://example.com/resources/rules.json, то:

   • "relative_to": "document" приведёт к тому, что home будет соответствовать https://example.com/some/home.
   • "relative_to": "ruleset" приведёт к тому, что home будет соответствовать https://example.com/resources/home.

Пример "expects_no_vary_search"

Рассмотрим главную страницу каталога пользователей /users, к URL-адресу которой добавляется параметр id для отображения информации о конкретном пользователе, например /users?id=345. Нужно ли считать этот URL-адрес идентичным для целей кэширования, зависит от поведения приложения:

1. Если этот параметр приводит к загрузке совершенно новой страницы с информацией об указанном пользователе, URL-адрес следует кэшировать отдельно.
2. Если этот параметр выделяет указанного пользователя на той же странице и, возможно, открывает выдвижную панель с его данными, то для целей кэширования URL-адреса следует считать одинаковыми. Это может повысить производительность при загрузке страниц пользователей; такого результата можно добиться с помощью заголовка No-Vary-Search со значением params=("id").

Как это влияет на правила спекулятивной загрузки? Рассмотрим следующий код:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "urls": ["/users"]
      }
    ]
  }
</script>
<a href="/users?id=345">User Bob</a>

Что произойдёт в этом случае, если пользователь начнёт переход по адресу /users?id=345 до получения заголовков для предварительной загрузки /users? На этом этапе браузер ещё не знает, каким будет значение No-Vary-Search, если оно вообще будет указано. Если значение No-Vary-Search не задано, а поведение приложения соответствует описанному выше варианту 1, предварительная загрузка окажется напрасной и браузеру придётся с нуля загружать отдельную страницу /users?id=345.

Это можно решить, сообщив браузеру, какое значение No-Vary-Search ожидает автор страницы. Правило спекулятивной загрузки может содержать поле "expects_no_vary_search", в котором строкой представлено ожидаемое значение заголовка:

<script type="speculationrules">
  {
    "prefetch": [
      {
        "urls": ["/users"],
        "expects_no_vary_search": "params=(\"id\")"
      }
    ]
  }
</script>
<a href="/users?id=345">User Bob</a>

Это указывает, что сервер, как ожидается, будет работать согласно описанному выше варианту 2. Если переход начинается во время предварительной загрузки /users, браузер получит указание дождаться её завершения, вместо того чтобы сразу начинать ещё один запрос на загрузку /users?id=345.

Правила документа также можно использовать вместе с "expects_no_vary_search" в зависимости от используемого шаблона. Например, в следующем случае:

<script type="speculationrules">
  {
    "prefetch": [
      {
        { "where": { "href_matches": "/users?id=*" } },
        "expects_no_vary_search": "params=(\"id\")"
      }
    ]
  }
</script>
<a href="/users?id=012">User Bill</a>
<a href="/users?id=345">User Bob</a>
<a href="/users?id=678">User Ben</a>

При наведении курсора на ссылку браузер начнёт предварительно загружать именно эту страницу.

Если пользователь наведёт курсор на другую ссылку до завершения предварительной загрузки, шаблон expects_no_vary_search сообщит браузеру, что отменять текущую предварительную загрузку не нужно: все URL-адреса /users со значениями параметра URL id фактически указывают на одну и ту же страницу в этом контексте (и для целей кэширования).

Можно указать несколько параметров в массиве, разделённом пробелами:

<script type="speculationrules">
  {
    "prefetch": [
      {
        { "where": { "href_matches": "/users?id=*" } },
        "expects_no_vary_search": "params=(\"id\" \"order\" \"lang\")"
      }
    ]
  }
</script>

Пример eagerness

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

<script type="speculationrules">
  {
    "prerender": [
      {
        "where": { "href_matches": "/*" },
        "eagerness": "conservative"
      },
      {
        "where": { "selector_matches": ".product-link" },
        "eagerness": "eager"
      }
    ]
  }
</script>

В этом примере мы указываем, что:

• Все ссылки на том же сайте, содержащиеся в документе, следует предварительно отображать консервативно (то есть когда пользователь начинает переход по ним).
• Все ссылки на товары (в данном случае — ссылки со значением .product-link у class), содержащиеся в документе, следует предварительно отображать активно (то есть при любом действии пользователя, указывающем на намерение перейти по ним).

Пример tag

На верхнем уровне можно указать tag, чтобы идентифицировать весь набор правил:

<script type="speculationrules">
  {
    "tag": "my-rules",
    "prerender": [
      {
        "where": { "href_matches": "/*" },
        "eagerness": "conservative"
      }
    ]
  }
</script>

Или идентифицировать отдельные правила:

<script type="speculationrules">
  {
    "prefetch": [
      "tag": "my-prefetch-rule",
      "urls": ["next.html"]
    ],
    "prerender": [
      "tag": "my-prerender-rule",
      "urls": ["next2.html"]
    ],
  }
</script>

Дополнительные примеры см. в разделе Sec-Speculation-Tags.

target_hint пример

Можно указать target_hint, чтобы задать целевое окно, в котором будут открываться соответствующие предположения о пререндеринге:

<script type="speculationrules">
  {
    "tag": "my-rules",
    "prerender": [
      {
        "eagerness": "eager",
        "target_hint": "_blank",
        "urls": ["page2.html"]
      }
    ]
  }
</script>

Приведённые выше правила позволяют корректно выполнять пререндеринг следующих ссылок в соответствующих целевых окнах:

<a href="page1.html">Open link in this window</a>
<a target="_blank" href="page2.html">Open link in new window</a>

target_hint требуется только для правил списков, в которых используется urls. Для правил документа (в которых используется where) это не нужно, поскольку в них целевое окно можно определить по атрибуту target элемента ссылки <a>.

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

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

См. также

• Пререндеринг страниц в Chrome для мгновенной навигации на developer.chrome.com
• Спекулятивная загрузка
• API правил спекулятивной загрузки