<script type="speculationrules">

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

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

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 содержит один или несколько полей верхнего уровня, каждое из которых представляет собой действие для определения правил спекуляций. В настоящее время поддерживаются следующие действия:

"prefetch" Необязательно Экспериментально

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

"prerender" Необязательно Экспериментально

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

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

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

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

<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", которое представляет собой объект, содержащий критерии, определяющие, какие ссылки в документе соответствуют правилу. По сути, объект "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>

Для наборов правил, которые извлекаются внешним образом (т. е. через заголовок ответа 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" }
    ]
  }
}

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

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.

Рассмотрим случай главной страницы каталога пользователей, /users, которая имеет параметр 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 указывает браузеру, что нет необходимости отменять текущую предварительную загрузку, поскольку все /users URL с значениями параметра id URL фактически указывают на одну и ту же страницу в этом контексте (и для целей кэширования).

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

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

Здесь мы даём подсказку о том, что:

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

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