<script type="speculationrules">

¥Syntax

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

注意：不得指定 src、async、nomodule、defer、crossorigin、integrity 和 referrerpolicy 属性。

¥Note: The src, async, nomodule, defer, crossorigin, integrity, and referrerpolicy attributes must not be specified.

¥Exceptions

TypeError

推测规则定义不是有效的 JSON 对象。

¥Description

<script type="speculationrules"> 元素必须包含定义推测规则的有效 JSON 结构。以下示例显示了单独的预取和预渲染规则：

¥A <script type="speculationrules"> element must contain a valid JSON structure that defines speculation rules. The following examples show separate prefetch and prerender rules:

<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>

¥Speculation rules JSON representation

JSON 结构在顶层包含一个或多个字段，每个字段代表一个为其定义推测规则的操作。目前支持的操作有：

¥The JSON structure contains one or more fields at the top level, each one representing an action to define speculation rules for. At present the supported actions are:

"prefetch" Optional Experimental

未来潜在导航的规则应下载其关联的文档响应正文，从而在导航到这些文档时显着提高性能。请注意，不会下载页面引用的任何子资源。

"prerender" Optional Experimental

未来潜在导航的规则，应将其关联文档完全下载、呈现并加载到不可见的选项卡中。这包括加载所有子资源、运行所有 JavaScript，甚至加载子资源并执行由 JavaScript 启动的数据获取。当导航到这些文档时，导航将是即时的，从而显着提高性能。

注意：有关如何有效使用预取和预渲染的完整详细信息，请参阅 推测规则 API 主页。

¥Note: Consult the Speculation Rules API main page for full details on how to use prefetch and prerender effectively.

每个操作字段都包含一个数组，该数组又包含一个或多个对象。每个对象都包含一个定义一组 URL 和相关参数的规则。

¥Each action field contains an array, which in turn contains one or more objects. Each object contains a single rule defining a set of URLs and related parameters.

每个对象可以包含以下属性：

¥Each object can contain the following properties:

"source"

指示应用规则的 URL 来源的字符串。这是可选的，因为该值始终可以从其他属性推断出来。

这可以是以下之一：

"document"

指定将根据 "where" 键描述的条件，从关联文档中的导航链接（如 <a> 和 <area> 元素中定义）匹配 URL。请注意，"where" 密钥的存在意味着 "source": "document"，因此它是可选的。

"list"

指定 URL 将来自 "urls" 键中指定的列表。请注意，"urls" 密钥的存在意味着 "source": "list"，因此它是可选的。

"urls" Experimental

表示要应用规则的 URL 列表的字符串数组。这些可以是绝对或相对 URL。相对 URL 将相对于文档基本 URL（如果内联在文档中）或相对于外部资源 URL（如果从外部获取）进行解析。"urls" 和 "where" 不能在同一规则中同时设置。

"where" Experimental

表示规则匹配关联文档中包含的 URL 的条件的对象。实际上，"where" 对象表示对页面上的每个链接执行的测试，以查看推测规则是否适用于它。"where" 和 "urls" 不能在同一规则中同时设置。

该对象可以恰好包含以下属性之一：

"href_matches"

包含 URL 模式的字符串，或包含多个 URL 模式字符串的数组，遵循标准 URL 模式 API 语法。文档中 URL 与模式匹配的链接将应用该规则。

"relative_to"

对于 "href_matches" 条件，这可以指定你希望该条件相对于何处进行匹配。其工作方式与 规则级别 "relative_to" 密钥 完全相同，只是它仅影响 "where" 键内的单个 "href_matches" 条件。

"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" 条件可以嵌套多个级别以创建复杂的条件，或者你可以选择将它们拆分为单独的规则以保持简单。请参阅 哪里有例子 了解更多说明和多个使用示例。

"eagerness" Experimental

向浏览器提供提示的字符串，提示浏览器应多快地预取/预渲染链接目标，以便在性能优势与资源开销之间取得平衡。可能的值为：

"immediate"

作者认为该链接很可能被点击，和/或该文档可能需要大量时间才能获取。预取/预渲染应尽快开始，仅考虑用户首选项和资源限制等因素。

"eager"

作者希望尽早预取/预渲染大量导航。预取/预渲染应该从任何可能跟踪链接的轻微建议开始。例如，用户可以将鼠标光标移向链接，将其悬停/聚焦一会儿，或者在显着位置暂停滚动链接。

"moderate"

作者正在寻找 eager 和 conservative 之间的平衡。当有合理的建议表明用户将在不久的将来点击链接时，应开始预取/预渲染。例如，用户可以将链接滚动到视口中并将其悬停/聚焦一段时间。

"conservative"

作者希望通过相当小的资源权衡从投机加载中获得一些好处。仅当用户开始单击链接（例如 mousedown 或 pointerdown）时才应启动预取/预呈现。

如果未明确指定 "eagerness"，则列表 ("urls") 规则默认为 immediate，文档 ("where") 规则默认为 conservative。浏览器会将此提示与其自身的启发法一起考虑在内，因此，如果较不急切的候选者被认为是更好的选择，那么它可能会选择作者暗示的不如另一个急切的链接。

"expects_no_vary_search" Experimental

一个字符串，向浏览器提供关于将在其接收预取/预呈现请求的文档的响应上设置什么 No-Vary-Search 标头值的提示。浏览器可以使用它来提前确定等待现有预取/预呈现完成或在推测规则匹配时启动新的获取请求是否更有用。有关如何使用此功能的更多说明，请参阅 "expects_no_vary_search" 示例。

"referrer_policy" Experimental

表示请求规则中指定的 URL 时要使用的特定引用策略字符串的字符串 - 请参阅 Referrer-Policy 了解可能的值。这样做的目的是允许引用页面专门针对推测请求设置比页面已设置的策略更严格的策略（默认情况下或使用 Referrer-Policy）。

注意：跨站点预取需要至少与默认 "strict-origin-when-cross-origin" 值一样严格的引用策略 - 即 "strict-origin-when-cross-origin"、"same-origin"、"strict-origin" 或 "no-referrer"。只要对于跨站点情况仍然足够严格，推测规则中设置的较宽松的策略将覆盖引用页面上设置的较严格的策略。

¥Note: A cross-site prefetch requires a referrer policy that is at least as strict as the default "strict-origin-when-cross-origin" value — so "strict-origin-when-cross-origin", "same-origin", "strict-origin", or "no-referrer". A laxer policy set in the speculation rules will override a stricter policy set on the referring page as long as it is still sufficiently strict for the cross-site case.

注意：对于文档规则，将使用匹配链接指定的引用策略（例如使用 referrerpolicy 属性），除非该规则指定了覆盖它的策略。

¥Note: In the case of document rules, the matched link's specified referrer policy (e.g. using the referrerpolicy attribute) will be used, unless the rule specifies a policy that overrides it.

"relative_to" Experimental

一个字符串，指定你希望 URL 匹配的链接相对于何处进行匹配。该值可以是以下之一：

document

URL 应与正在设置推测规则的文档相匹配。

ruleset

URL 应相对于指定规则的文件进行匹配。这是默认值。

此键设置仅与外部文件中定义的规则相关（使用 Speculation-Rules 标头设置）。当规则在同一文档中指定时（即在内联 <script> 元素中），没有区别。

"requires" Experimental

表示浏览器解析规则的能力的字符串数组，如果要将规则应用于指定的 URL，则该字符串必须可用。

警告：在无法满足指定要求的浏览器中，预取将自动失败，即使它们支持 推测规则 API。

¥Warning: Prefetches will automatically fail in browsers that cannot meet a specified requirement, even if they support the Speculation Rules API.

可能的值为：

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

（仅预取）指定仅当发出跨源预取请求时用户代理可以阻止客户端 IP 地址对源服务器可见时，规则才匹配。具体如何工作取决于浏览器的实现细节。例如：

• Chrome 的实现使用 Google 拥有的代理隐藏 IP 地址，因此默认情况下它仅适用于 Google 控制的引荐来源网址（因为在这种情况下，将目标 URL 发送给 Google 并不是额外的隐私泄露）。在非 Google 所有网站上使用时，包含此内容的规则将仅匹配在 chrome://settings/preloading 中启用 "增强预载" 的用户。
• 其他基于 Chromium 的浏览器将不得不提供自己的解决方案。建议在所有目标浏览器中进行彻底测试。
• 未来的 Safari 实现可能会使用类似于 iCloud 私有中继 的东西。
• 未来的 Firefox 实现可能会使用基于 Mozilla VPN 产品的东西。

注意：由于推测规则使用 <script> 元素，因此如果站点包含 Content-Security-Policy script-src 指令，则需要在 Content-Security-Policy script-src 指令中明确允许它们。这是通过将 "inline-speculation-rules" 值与哈希源或随机数源相加来完成的。

¥Note: As speculation rules use a <script> element, they need to be explicitly allowed in the Content-Security-Policy script-src directive if the site includes it. This is done by adding the "inline-speculation-rules" value along with a hash- or nonce-source.

¥Examples

¥Prefetch and prerender in the same set of rules

描述部分中显示的基本示例包括为预取和预渲染定义的单独推测规则。可以在一组规则中定义两者：

¥The basic examples shown in the description section included separate speculation rules defined for prefetch and prerender. It is possible to define both in a single set of rules:

<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>

注意：此代码片段提供了列表 ("urls") 规则和文档 ("where") 规则示例。

¥Note: This code snippet provides a list ("urls") rule and a document ("where") rule example.

¥Multiple rule sets

还允许在单个 HTML 文件中包含多组规则：

¥It is also allowable to include multiple sets of rules in a single HTML file:

<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>

以及单个结果集中的多个规则：

¥And multiple rules in a single result set:

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

¥Dynamic rule insertion

下面是一个示例，该功能检测推测规则，如果支持，则通过 JavaScript 动态添加预渲染推测规则：

¥Below is an example that feature detects speculation rules and, if supported, dynamically adds a prerender speculation rule via 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);
}

你可以在此 预渲染演示 页面中看到此操作的实际效果。

¥You can see this in action in this prerender demos page.

¥where syntax examples

源自文档的规则包含 "where" 属性，该属性是一个对象，其中包含定义匹配文档中的哪些链接的条件。实际上，"where" 对象表示对页面上的每个链接执行的测试，以查看推测规则是否适用于它。

¥A document-sourced rule contains a "where" property, which is an object containing criteria that define which links in the document are matched. Effectively, the "where" object represents a test that is performed on every link on the page to see whether the speculation rule is applied to it.

最基本的版本将匹配单个 URL 模式或 CSS 选择器：

¥The most basic version will match a single URL pattern or CSS selector:

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

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

"href_matches" 和 "selector_matches" 也可以设置为值数组，因此可以同时匹配多个 URL 模式或 CSS 选择器：

¥"href_matches" and "selector_matches" can also be set to an array of values, so multiple URL patterns or CSS selectors can be matched simultaneously:

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

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

URL 模式和选择器还可以包含通配符 (*) 字符，允许单个值匹配多个 URL。例如，下面的对象可以匹配 user/、user/settings、user/stats 等。

¥URL patterns and selectors can also contain wildcard (*) characters, allowing a single value to match multiple URLs. For example, the object below could match user/, user/settings, user/stats, etc.

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

任何条件都可以通过将其放入 "not" 条件来否定 - 这意味着，当匹配时，链接不会应用推测规则，但当不匹配时，则会应用推测规则。以下示例将导致与 URL 模式 /logout 不匹配的所有链接应用该规则，但与 /logout 匹配的链接不会应用该规则：

¥Any condition can be negated by placing it inside a "not" condition — this means that, when matched, a link won't have the speculation rule applied to it, but when not matched, it will. The following example will cause all links that don't match the URL pattern /logout to have the rule applied to them, but not links that match /logout:

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

将多个 "where" 条件与 "and" 或 "or" 组合

¥Combining multiple "where" conditions with "and" or "or"

多个条件可以在 "and" 或 "or" 条件内组合 - 这些条件采用包含多个条件的数组的值，所有或任何条件（分别）必须匹配推测规则才能应用于链接。使用 "and" 或 "or"，条件可以嵌套多个级别 - 对允许的嵌套级别没有指定限制。

¥Multiple conditions can be combined inside "and" or "or" conditions — these take the value of arrays containing multiple conditions, all or any of which (respectively) have to match for the speculation rules to apply to a link. Using "and" or "or", conditions can be nested multiple levels deep — there is no specified limit on allowed nesting levels.

将 "where" 对象视为等效于 if 语句是很有用的。所以

¥It is useful to think of the "where" object as being equivalent to an if statement. So

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

相当于

¥is equivalent to

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

在以下完整的推测规则示例中，所有同源页面都被标记为预取，除了那些已知有问题的页面 - /logout 页面以及标记有 .no-prerender 类的任何链接：

¥In the following complete speculation rule example, all same-origin pages are marked for prefetching except those known to be problematic — the /logout page, and any links marked up with a class of .no-prerender:

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

注意：上面的 where 模式不包括跨站点链接，支持预取（前提是用户没有为目标站点设置 cookie，以防止跟踪），但不支持预呈现。

¥Note: The where pattern above does not include cross-site links, which are supported for prefetching (provided the user has no cookies set for the destination site, to protect against tracking) but not for prerendering.

¥"relative_to" example

对于从外部获取（即通过 Speculation-Rules）响应标头的规则集，默认情况下，列表规则中的 URL 和文档规则中的 URL 模式是相对于包含的外部文本文件的 URL 进行解析的。要解析列表规则中相对于文档基本 URL 的 URL，请使用 "relative_to"，如下所示：

¥For rule sets that are externally fetched (i.e. via the Speculation-Rules) response header, URLs in list rules and URL patterns in document rules are parsed relative to the containing external text file's URL by default. To parse URLs in a list rule relative to the document's base URL, "relative_to" is used like this:

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

对于文档规则，"relative_to" 可以直接与 "href_matches" 配对，并且文档的基本 URL 将仅用于该特定条件下的模式：

¥For document rules, "relative_to" can be paired directly with "href_matches" and the document's base URL would only be used for patterns in that particular condition:

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

在上面的示例中，只有第一个 "href_matches" 会相对于文档的基本 URL 进行匹配。

¥In the above example, only the first "href_matches" will be matched relative to the document's base URL.

如果推测规则 JSON 文件与你希望应用它们的文档位于不同的来源，则 relative_to 主要相关：

¥relative_to is mainly relevant if the speculation rules JSON file is on a different origin to the document you wish to apply them to:

1. 如果文档位于 https://example.com/some/subpage.html，规则位于 https://example.com/resources/rules.json，则无论 relative_to 设置为 document 还是 ruleset，/home 始终等于 https://example.com/home。
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" example

考虑用户目录登陆页面 /users 的情况，其中添加了 id 参数以显示有关特定用户的信息，例如 /users?id=345。出于缓存目的，此 URL 是否应被视为相同取决于应用的行为：

¥Consider the case of a user directory landing page, /users, which has an id parameter added to bring up information on a specific user, for example /users?id=345. Whether this URL should be considered identical for caching purposes depends on the behavior of the application:

1. 如果此参数具有加载包含指定用户信息的全新页面的效果，则应单独缓存 URL。
2. 如果此参数具有在同一页面上高亮指定用户的效果，并且可能会显示显示其数据的拉出面板，则出于缓存目的，应将 URL 视为相同。这可能会导致用户页面加载方面的性能改进，并且可以通过值为 params=("id") 的 No-Vary-Search 来实现。

这对投机规则有何影响？考虑以下代码：

¥How does this affect speculation rules? Consider the following code:

<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 页面。

¥What would happen in this case when the user starts a navigation to /users?id=345 when the headers for the prefetch of /users have not been received yet? At this point, the browser doesn't know what the No-Vary-Search value will be, if anything. If there was no No-Vary-Search value set, and the application behavior was more like Option 1 above, the prefetch would be wasted and the browser would need to go and fetch the separate /users?id=345 page from scratch.

为了解决这个问题，我们可以提供有关页面作者期望 No-Vary-Search 值的提示。推测规则可以有一个 "expects_no_vary_search" 字段，其中包含预期标头值的字符串表示形式：

¥To solve this, we can provide a hint as to what the page author expects the No-Vary-Search value to be. A speculation rule can have an "expects_no_vary_search" field, which contains a string representation of the the expected header value:

<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 的获取。

¥This indicates that Option 2 described above is what the server is expected to produce. If a navigation starts while there is an ongoing prefetch of /users, this informs the browser that it is appropriate to wait for the prefetch, instead of immediately starting another fetch for /users?id=345.

文档规则也可以与 "expects_no_vary_search" 结合使用，具体取决于所使用的模式。例如，在以下情况：

¥Document rules can also be used in conjunction with "expects_no_vary_search", depending on the pattern used. For example, in the case of:

<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>

如果将鼠标悬停在链接上，浏览器将开始预取该特定链接。

¥If a link is hovered over, the browser will start prefetching that specific link.

如果用户在预取完成之前将鼠标悬停在另一个链接上，则 expects_no_vary_search 模式会告诉浏览器无需取消当前预取，因为具有 id URL 参数值的所有 /users URL 实际上都指向此上下文的同一页面（对于 缓存目的）。

¥If the user hovers over another link before the prefetch completes, the expects_no_vary_search pattern tells the browser that there is no need to cancel the current prefetch, because all /users URLs with id URL parameter values effectively point to the same page for this context (and for caching purposes).

¥eagerness example

以下一组文档规则显示了如何使用 eagerness 来暗示浏览器应预呈现每个匹配的链接集的渴望程度。

¥The following set of document rules shows how eagerness can be used to hint at the eagerness with which the browser should prerender each matching set of links.

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

在此，我们提示一下：

¥Here we are hinting that:

• 文档中包含的所有同站点链接都应保守地预渲染（即当用户开始激活它们时）。
• 文档中的任何产品链接（在本例中为 class 或 .product-link 的链接）都应立即预呈现（即，如果用户做出任何类型的导航到它们的操作）。

注意：渴望设置的效果对于列表规则不太有用。默认情况下，一旦解析了规则，就会立即预取/预渲染列表规则 URL，这正是你所期望的 — 它们旨在显式列出你希望尽快提供的高优先级 URL。因此，在当前的实现中，eager 与 immediate 具有相同的效果。较低的急切度设置用于与链接交互时的预取/预渲染，对于这些，你更有可能使用文档规则在页面上查找它们。

¥Note: The effects of eagerness settings are less useful for list rules. By default, list rule URLs are prefetched/prerendered immediately as soon as the rules are parsed, which is what you'd expect — they are intended for explicit listing of high-priority URLs that you want to make available as soon as possible. For this reason, eager has the same effect as immediate in current implementations. Lower eagerness settings are for prefetching/prerendering when links are interacted with, and for these you are more likely to use document rules to find them on the page.

¥See also

• developer.chrome.com 上的 在 Chrome 中预渲染页面以实现即时页面导航 (2023)
• 投机加载
• 推测规则 API