URL 片段文本指令

1. 基础结构

本规范依赖于 Infra 标准。[INFRA]

2. 简介

2.1. 使用场景

2.1.1. 网页文本引用

2.1.2. 用户分享

2.2. 链接生命周期

本规范力图最大化文本指令链接的有效期，例如，使用实际文本内容作为 URL 载荷，并允许使用元素 id 片段作为备用。然而，网页经常会更新和变更其内容。因此，此类链接可能会“失效”，即它们指向的文本内容在目标页面上不再存在。

尽管有这个问题，文本指令链接依然有用。在用户分享场景中，这类链接通常是临时的，仅用于发送后的短时间内。对于更长期的引用和网页链接等用例，文本指令依然有价值，因为它们能优雅降级为普通链接。此外，过期文本指令的存在也可以为用户展现有用的信息，以帮助用户理解原作者的用意，并提示页面内容自链接创建以来可能已发生更改。

关于如何创建健壮的文本指令链接，请参见§ 4 生成文本片段指令中的最佳实践。

3. 描述

3.1. 指示

本规范有意不定义用户代理如何“指示”文本匹配。有多种不同的体验和权衡，用户代理可以做出。可能的操作示例包括：

• 对文本段落进行视觉强调或高亮显示

• 在页面导航时自动滚动该段落至可见范围

• 在该段文字上激活用户代理的页面内查找功能

• 提供“点击以滚动至文本段落”的通知

• 当未在页面中找到文本段落时提供通知

3.2. 语法

文本指令在片段指令中指定（见§ 3.3 片段指令），格式如下：

#:~:text=[prefix-,]start[,end][,-suffix]
          context  |--match--|  context

（方括号表示可选参数）

文本参数在匹配前会进行百分号解码。连字符（-）、和号（&）以及逗号（,）等字符在文本参数中会被百分号转义，以避免被解析为文本指令语法的一部分。

唯一必选的参数是start。如果只指定了start，则以该精确字符串首次出现处为目标文本。

如果还指定了end参数，则文本指令指向页面中的一段文本范围。目标文本范围是从首次出现的start开始，到其后首次出现的end为止。这等价于在start参数中指定完整的文本范围，但可避免因过长的文本指令导致URL膨胀。

3.2.1. 上下文术语

另外两个可选参数即为上下文术语。它们由连字符（-）连接在前缀和后缀处，以区别于start和end参数，可任意组合指定。

上下文术语用于消歧目标文本片段。上下文术语可分别指定文本片段之前（前缀）和之后（后缀）紧邻的文本内容，允许存在空白字符。

上下文术语不是目标文本片段的一部分，也不会被视觉指示。

3.2.2. 双向文本注意事项

由于 URL 字符串为 ASCII 编码，其本身不支持双向文本。但我们想要在页面上定位的内容可能是 LTR（从左到右）、RTL（从右到左）或双向文本。本节直观描述了规范中进一步章节隐含的行为。

文本片段中每个术语的字符都处于逻辑顺序，即母语读者阅读的顺序（也是内存中字符的存储顺序）。

同样，prefix与start表示另一个术语前的内容，suffix与end表示后续内容，均为逻辑顺序。

注意：用户代理可将 URL 以更符合本地读者习惯的方式呈现，比如显示为 Unicode。但 URL 的字符串表达始终是纯 ASCII 字符。

3.3. 片段指令

为避免与现有 URL 片段的使用发生兼容性问题，本规范引入了片段指令的概念。它是 URL 片段中位于片段指令分隔符之后的部分，也可能为 null（如果片段中未出现分隔符）。

片段指令分隔符为字符串 ":~:"，即连续三个码点 U+003A (:)、U+007E (~)、U+003A (:)。

片段指令会被解析并处理为单个指令，即指示用户代理执行某项操作的指令。片段指令中可出现多个指令。

为防止影响页面运行，片段指令会从脚本可访问的 API 中剥离，防止与作者脚本交互。这也确保将来可安全添加更多指令，而不会有 web 兼容性风险。

3.3.1. 提取片段指令

本节描述了如何将片段指令从脚本中隐藏，以及它如何适配 HTML § 7.4 导航和会话历史。

在 HTML § 7.4.1 会话历史中，定义 指令状态：

猴补丁 HTML § 7.4.1 会话历史：

指令状态 保存会创建会话历史条目时的片段指令值，并用于每次遍历此条目时执行指令（如文本高亮）。其结构为：

• 值，片段指令ASCII 字符串或 null，初值为 null。

同一 指令状态可被多个会话历史条目共享。

片段指令在 URL 设置到会话历史条目前会被移除，而存储于指令状态对象。这避免片段指令暴露给脚本 API，使其可独立指定、不干扰页面业务。

指令状态是对象而非原始字符串，因为多个连续历史条目可共用同一状态。仅当遍历导致指令状态从一条切换到另一条时，指令（如查找/高亮）才会被处理。

在 会话历史条目 的定义处补充：

猴补丁 HTML § 7.4.1.1 会话历史条目：

会话历史条目是如下成员的结构体：

• ...

• 持久化用户状态，实现细节定义，初值为 null

• 指令状态，一种指令状态， 初值为一个新的指令状态

增加一个帮助算法，可从URL中移除并返回片段指令字符串：

猴补丁 [HTML]：

本算法让 URL 片段以片段指令分隔符 处截断。返回的片段指令包含分隔符后的所有字符（不含分隔符本身）。

TODO: 若 URL 片段以 ':~:' 结尾（即空指令），此时会返回 null，等同于未显式指定指令（且不会覆盖已有指令）。但或许此时应该返回空字符串？这样页面即可通过导航/pushState 到 '#:~:' 来显式清除指令/高亮。

要从URL url中移除片段指令，执行：

1. 令raw fragment为url的fragment。

2. 令fragment directive为 null。

3. 如raw fragment非空且包含片段指令分隔符：

   1. 令position为字符串中首次出现片段指令分隔符第一个码点的位置变量；若无，则为尾部。

   2. 令new fragment为raw fragment从头至position之间的字符串。

   3. position增加分隔符码点长度。

   4. 如果position未越界：

      1. 设fragment directive为raw fragment自position起至末尾的子串。

   5. 设url的fragment为new fragment。

4. 返回fragment directive。

https://example.org/#test:~:text=foo 会被解析为 fragment="test"，片段指令="text=foo"。

下述四个猴补丁修改了会话历史条目的创建。当 URL 可能包含片段指令时，将其移除并存于指令状态。

在navigate定义中：

猴补丁 HTML § 7.4.2.2 开始导航：

导航 navigable 至 URL url...：

1. ...

14. 将 navigable 的 ongoing navigation 设为 navigationId。

15. 若 url 的 scheme 为 "javascript"，则...

16. 并行执行以下步骤：

    1. ...

    5. 若 url 为 about:blank，则将 documentState 的 origin 设为 documentState 的 initiator origin。

    6. 否则，如 url 为 about:srcdoc，则 documentState 的 origin 设为 navigable 的父文档 origin。

    7. Let historyEntry be a new session history entry, with its URL set to url and its document state set to documentState.
    7. 令fragment directive为对url执行移除片段指令结果。

    8. 令directive state为新的指令状态，其值设为fragment directive。

    9. 创建会话历史条目 historyEntry，URL 设为url，文档状态设为 documentState，指令状态设为directive state。

    10. 设 navigationParams 为 null。

    11. ...

在navigate to a fragment定义中：

猴补丁 HTML § 7.4.2.3.3 片段导航：

导航至片段 navigable navigable，...：

1. 令directive state为 navigable 当前活动会话历史条目的指令状态。

2. 令fragment directive为执行移除片段指令于url的结果。

3. 如fragment directive非空：

   否则，仅片段变化且未指定指令则重用活动条目的指令状态，可防止片段变化后高亮丢失。

   1. 令directive state为新的指令状态，值为fragment directive。

4. 创建会话历史条目 historyEntry：

   • URL url

   • 文档状态为 navigable 当前活动会话历史条目的文档状态

   • 滚动恢复模式为 navigable 当前活动会话历史条目的滚动恢复模式

   • 指令状态为directive state

5. 如 historyHandling 为"replace"，则 entryToReplace 为 navigable 当前活动会话历史条目，否则为 null。

6. ...

在URL 和 历史更新步骤定义中：

猴补丁 HTML § 7.4.4 非片段同步“导航”：

“URL 和历史更新步骤”，入参 Document document，...：

1. 令navigable为document的 node navigable。

2. 令activeEntry为navigable当前活动会话历史条目。

3. 令fragment directive为对newUrl执行移除片段指令得到的结果。

4. 新建会话历史条目historyEntry，其中

   • URL newUrl

   • ...

   • 指令状态 取自activeEntry的指令状态

5. 如 document 的 is initial about:blank 为 true，设 historyHandling 为"replace"。

6. 如 historyHandling 为"push"，则：

   1. 历史对象 index 加一。

   2. 历史对象长度设置为 index+1。

   3. 如newUrl不等于activeEntry的（排除 fragment 后）URL，或fragment directive非空，则：

      否则仅片段变更且未指定指令，则重用激活条目的指令状态，防止片段变更后高亮丢失。

      1. 将historyEntry的指令状态设为新的指令状态， 其值设为fragment directive。

7. 否则如fragment directive非空，将historyEntry的指令状态的值设为fragment directive。

8. 如 serializedData 不为空，则恢复给定 document 和 newEntry 的历史对象状态。

在 create navigation params by fetching定义中：

猴补丁 HTML § 7.4.5 填充会话历史条目：

“通过获取创建导航参数”，入参会话历史条目entry，...：

1. 断言：此步骤在并行执行。

2. ...

17. 令 currentURL 为请求的当前 URL。

18. 令 commitEarlyHints 为 null。

19. 循环：

    1. 如请求的 reserved client 非空且 currentURL 的源与 reserved client 的创建 URL 源不同，则：

    2. ...

    21. 将 currentURL 设为 locationURL。

    22. 令fragment directive为对locationURL执行移除片段指令的结果。

    23. 将 entry 的 URL 设为 currentURL。

    24. 将 entry 的 URL 设为 locationURL。

    25. 将 entry 的指令状态的值设为fragment directive。

    26. 如 locationURL 的 scheme 不是 fetch scheme，则返回新的非 fetch scheme 导航参数，initiator origin 为请求的 current URL 源

    27. ...

window.location = "https://example.com#page1:~:hello";
console.log(window.location.href); // 'https://example.com#page1'
console.log(window.location.hash); // '#page1'

location.hash = "page2";
console.log(location.href); // 'https://example.com#page2'

onhashchange = () => console.assert(false, "hashchange doesn’t fire.");
location.hash = "page2:~:world";
console.log(location.href); // 'https://example.com#page2'
onhashchange = null;

history.pushState("", "", "page3");
console.log(location.href); // 'https://example.com/page3'

let url = new URL('https://example.com#foo:~:bar');
console.log(url.href); // 'https://example.com#foo:~:bar'
console.log(url.hash); // '#foo:~:bar'

document.url = url;
console.log(document.url.href); // 'https://example.com#foo:~:bar'
console.log(document.url.hash); // '#foo:~:bar'

<a id='anchor' href="https://example.com#foo:~:bar">Anchor</a>
<script>
  console.log(anchor.href); // 'https://example.com#foo:~:bar'
  console.log(anchor.hash); // '#foo:~:bar'
</script>

3.3.2. 将指令应用于文档

上节介绍了如何将片段指令从URL中分离出来，并存储在会话历史条目中。

本节定义了导航和遍历时，历史条目中的指令状态如何及何时被用来将会话历史条目关联的指令应用到文档上。

猴补丁 DOM § 4.5 文档接口：

每个文档都有一个相关的待处理文本指令，它要么为null，要么为列表 （包含文本指令）。初始为null。

在历史步骤应用时更新文档的定义中：

猴补丁 HTML § 7.4.6.2 更新文档：

更新历史步骤应用时的文档，参数为 Document document，会话历史条目 entry，...

1. ...

4. 将document的历史对象 length 设为 scriptHistoryLength

5. 如果documentsEntryChanged为真，则：

   1. 令oldURL为document的最新条目的URL。

   2. 若document的最新条目的指令状态与entry的指令状态不同，则：

      1. 令fragment directive为entry的指令状态的值。

      2. 将document的待处理文本指令设为解析fragment directive的结果。

6. 将document的最新条目设为entry

7. ...

3.3.3. 片段指令语法

注：本节为非规范性内容。

注：本语法仅供参考，解析的规则和步骤将在§ 3.4 文本指令节以命令方式给出。若实际行为与本语法描述有出入，应以那一节具体步骤为准。

FragmentDirective 可包含多个由 “&” 字符分隔的指令。目前允许页面存在多个文本指令以同时标示多段字符串，也为将来添加组合其它指令类型做扩展准备。为保持扩展性，遇到未知指令时不会导致整个解析失败。

若一个字符串匹配下述EBNF（扩展巴科斯范式）产生式，则为合法片段指令：

FragmentDirective ::=

(TextDirective | UnknownDirective) ("&" FragmentDirective)?

TextDirective ::=

"text="CharacterString

UnknownDirective ::=

CharacterString - TextDirective

CharacterString ::=

(ExplicitChar | PercentEncodedByte)*

ExplicitChar ::=

[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~" | "," | "-"

ExplicitChar 可为任何URL 码点，除了“&”。

若一个TextDirective匹配下述产生式，则为合法：

ValidTextDirective ::=

"text=" TextDirectiveParameters

TextDirectiveParameters ::=

(TextDirectivePrefix ",")? TextDirectiveString ("," TextDirectiveString)? ("," TextDirectiveSuffix)?

TextDirectivePrefix ::=

TextDirectiveString"-"

TextDirectiveSuffix ::=

"-"TextDirectiveString

TextDirectiveString ::=

(TextDirectiveExplicitChar | PercentEncodedByte)+

TextDirectiveExplicitChar ::=

[a-zA-Z0-9] | "!" | "$" | "'" | "(" | ")" | "*" | "+" | "." | "/" | ":" | ";" | "=" | "?" | "@" | "_" | "~"

TextDirectiveExplicitChar 为任何未在FragmentDirective或ValidTextDirective语法中显式用到的 URL 码点，即“&”“-”“,”。文档中涉及“&”“-”“,”时需百分号编码。

PercentEncodedByte ::=

"%" [a-zA-Z0-9][a-zA-Z0-9]

3.4. 文本指令

文本指令是一种指令，用于代表要向用户指示的文本范围。它是一个包含四个字符串的结构体：start、end、prefix、 suffix。start要求非null。其余三项可为null，表示未提供。空字符串在这四项中都是无效值。

各部分含义和用法见§ 3.2 语法。

3.4.1. 调用文本指令

本节描述如何处理和调用文档待处理文本指令，以指示相关的文本段落。

在 指示部分中，允许片段指示范围。做如下修改：

猴补丁 HTML § 7.4.6.3 滚动到片段：

对于HTML文档document，必须遵循如下处理模型，以确定其指示部分：

1. 令text directives为文档的待处理文本指令。

2. 如text directives非null：

   1. 令ranges为对text directives及文档执行调用文本指令步骤所得的列表。

   2. 如ranges非空：

      1. 令firstRange为ranges的首项。

      2. 以range方式，对ranges内每个范围进行实现自定义的视觉指示。该指示不得从作者脚本中观察到。见§ 3.7 指示文本匹配。

         ranges中的第一个范围会滚动至可视区，但所有范围都应高亮指示给用户。

      3. 将firstRange设为document的指示部分并返回。

3. 令fragment为文档URL的片段。

4. 如fragment为空字符串，则返回特殊值“文档顶端”。

5. 令potentialIndicatedElement为给定文档和片段查找可能的指示元素结果。

6. ...

在滚动到片段中，处理指示部分为范围的情形，并在启用强制顶部加载策略时阻止片段滚动。做如下修改：

猴补丁 HTML § 7.4.6.3 滚动到片段：

1. 若document的指示部分为null，则将document的目标元素设为null。

2. 否则，如document的指示部分为文档顶端，则：

   1. 将document的目标元素设为null。

   2. 将文档滚动至开头。

   3. 返回。

3. 否则：

   1. 断言：document的指示部分为元素或范围。

   2. 令scrollTarget为document的指示部分。

   3. 令target为scrollTarget。

   4. 如target为范围：

      1. 设target为该范围的首个公共祖先，即target的起始节点与结束节点的祖先。

      2. 当target非null且不是元素时，循环将target设为其父节点。

         若处于shadow tree内部目标应如何设？#190

   5. 断言：target为元素。

   6. 将document的目标元素设为target。

   7. 对target运行祖先详情揭示算法。

   8. 对target运行祖先hidden-until-found揭示算法。

      这些揭示算法目前可能效果不好，因为target可能是祖先甚至根节点。#89 建议只匹配 contain:style layout 区块即可解决该问题。

   9. 如scrollTarget为范围，blockPosition设为"center"，否则为"start"。

      滚动到文本指令时，在区块方向居中显示。
   10. 将target滚动到视图，行为设为"auto"，block设为"start"，inline设为"nearest"。
   10. 滚动目标到视图， 参数target为scrollTarget，behavior为"auto"，block为blockPosition，inline为"nearest"。

       实现 MAY（可选）避免对由文本指令产生的目标滚动。

   11. 为target运行聚焦步骤，文档视口作为后备目标。

       实现注：Blink当前不会为文本片段设置焦点，应当补充？TODO：提交crbug。

   12. 将顺序焦点导航起点移至target。

接下来两个猴补丁确保用户代理在片段查找完成时清理待处理文本指令。如因解析停止而结束文本指令查找，则再次尝试非文本片段。

在尝试滚动到片段定义中：

猴补丁 HTML § 7.4.6.3 滚动到片段：

要为文档document尝试滚动到片段，并行执行如下步骤：

1. 等待一段实现自定义时间（用于优化用户体验和性能）。

2. 在导航和遍历任务源上为document的相关全局对象排队全局任务，执行如下步骤：

   1. 如document没有解析器，或其解析器已停止解析，或用户代理认为用户不再关注片段滚动，则终止这些步骤。
   1. 如用户代理认为用户不再关注片段滚动，则：

      1. 将待处理文本指令设为null。

      2. 终止这些步骤。

   2. 如文档没有解析器或解析器已停止解析，则：

      1. 如待处理文本指令非null，则：

         1. 将待处理文本指令设为null。

         2. 滚动到片段，参数为document。

      2. 终止这些步骤。

   3. 滚动到片段，参数为document。

   4. 如document的指示部分仍为null，则为document再次尝试滚动到片段。否则，将待处理文本指令设为null。

在导航到片段定义中：

猴补丁 HTML § 7.4.2.3.3 片段导航：

导航到片段，入参navigable navigable，...：

1. ...

8. 以navigable的活动文档、historyEntry、true、scriptHistoryIndex和scriptHistoryLength调用“历史步骤应用时更新文档”。

9. 为navigable的活动文档滚动到片段。

10. 将navigable的活动文档的待处理文本指令设为null。

11. 令traversable为navigable的可遍历navigable。

12. ...

滚动到指示部分只是“滚动到片段”中的众多操作之一。需重命名该及相关定义：

猴补丁 HTML § 7.4.2.3.3 片段导航：

将HTML § 7.4.2.3.3 片段导航及相关步骤重命名为“指示片段”，以反映其更广泛的效果。

3.5. 安全与隐私

3.5.1. 动机

实现文本指令时必须确保无法被用于跨源窃取信息。脚本可以导航到带有文本指令的跨源URL。如果恶意行为者能判断导航导致目标页面上的文本片段被成功找到，则可推断出页面内容。

下述各子节给出的处理模型限制了该功能，缓解了已知的攻击向量。简而言之，文本指令限制如下：

• 仅适用于顶级可导航（即不用于iframe）。

  • 这并非绝对，Chrome允许相同源发起的此用法。规范需进一步明确。[Issue #WICG/scroll-to-text-fragment#240]

• 由用户操作触发的导航

• 若导航为跨源发起，则目标页面要求 opener 隔离（即其它文档不可持有其全局对象引用）

3.5.2. 导航触发滚动

UA可以选择在匹配文本片段后自动滚动到可见区域。这对用户便捷，但也带来一些实现风险。

已知（或潜在未知）的方式可分辨导航触发滚动和用户自然滚动。

所有已知情景依赖于目标页的具体情况，因而并不普适。进一步对文本片段的调用条件加以限制，可进一步约束攻击者能力。但不同 UA 可根据自身判断风险是否可接受，确定是否在导航到文本片段时自动滚动。

符合规范的UA可选择导航时不自动滚动。此时可提供“点击滚动”等UI，或完全不滚动。此时 UA 应向用户提示有片段存在于页面下方。

上述例子展示在特殊情况下，攻击者可获取目标页面内容的1比特信息。但应防止可利用此途径持续攻击以获取任意内容。因此，基于用户激活与浏览上下文隔离的约束至关重要，必须严格实现。

如UA选择自动滚动，必须确保文档在后台时（如处于非激活tab）不进行滚动，以防止攻击者在后台偷偷进行自动化搜索，确保恶意行为可见。

如UA选择不自动滚动，则必须无条件滚动后备元素id到可视区（如有），不论文本片段是否匹配。否则可用是否滚动该元素来判断文本片段是否成功匹配。

3.5.3. 查找时机

文本搜索算法的天真实现，可能因匹配与否导致运行时长差异，继而泄漏信息。攻击者如可同步导航到文本指令URL，即可通过导航耗时推断文本片段是否存在。

因此，实现必须确保§ 3.6 导航到文本片段步骤无论匹配与否运行时长无差异。

本规范不规定 UA 如何实现。可选做法如：即使已找到匹配，仍继续遍历树（见从文本指令查找范围）；也可调度异步任务查找并设定文档的指示部分。

3.5.4. 限制文本片段

补充请求和文档 的定义，加入新的布尔值text directive user activation字段：

猴补丁 [FETCH]：

一个请求关联一个布尔值text directive user activation， 初始为 false。

猴补丁 [HTML]：

每个文档有text directive user activation，为布尔型，初始为 false。

text directive user activation 提供了允许单次激活文本片段所需的用户手势信号。仅在导航因用户激活发生且跨客户端重定向时，于文档加载期间设为 true。

若文档的text directive user activation未用于激活文本片段，则其用于将新导航请求的text directive user activation设为 true。因此，text directive user activation 可跨导航在文档间传递。

文档的text directive user activation和请求的text directive user activation在被使用时总归为 false，因此一次用户激活不能多次激活文本片段。

补充 create navigation params by fetching 步骤，将 活动文档 的 text directive user activation 赋值给 request 的 text directive user activation.

猴补丁 [HTML]：

1. 断言：本步骤在并发执行。

2. 令 documentResource 为 entry 的 document state 的 resource。

3. 新建 request，其属性包括：

   url

   entry 的 URL

   ...

   ...

   referrer policy

   entry 的 document state 的 request referrer policy

   text directive user activation

   navigable 的 活动文档 的 text directive user activation

4. 将 navigable 的 活动文档 的 text directive user activation 设为 false。

5. 如 documentResource 为 POST 资源，则：

   1. ...

补充 navigation params，增加新字段：

猴补丁 [HTML]：

user involvement

一个 用户导航介入 值。

所有创建 navigation params 的地方均初始化 user involvement 值。具体如 create navigation params by fetching 情况下初始化为 true：

猴补丁 [HTML]：

要 create navigation params by fetching，参数：session history entry entry，navigable，source snapshot params sourceSnapshotParams，target snapshot params targetSnapshotParams，string cspNavigationType，navigation ID-or-null navigationId，NavigationTimingType navTimingType，和 user navigation involvement user involvement，步骤如下。它们返回 navigation params、non-fetch scheme navigation params 或 null。

1. 断言：本步骤并发执行。

2. ...

23. 令 resultPolicyContainer 为 determine navigation params policy container 结果，其参数为 response 的 URL、entry 的 document state 的 history policy container、sourceSnapshotParams 的 source policy container、null 和 responsePolicyContainer。

24. 如 navigable 的 container 为 iframe，且 response 的 timing allow passed 标志置位，则将 container 的 pending resource-timing start time 设为 null。

25. 返回新 navigation params，属性为：

    id

    navigationId

    ...

    ...

    about base URL

    entry 的 document state 的 about base URL

    user involvement

    user involvement

补充 create and initialize a Document object 步骤，计算并存储 text directive user activation 标志：

猴补丁 [HTML]：

18. 调用 process link headers。

19. 若满足下列任一条件，则设 document 的 text directive user activation 为 true，否则为 false：

    • navigationParams 的 user involvement 是 "activation"；

    • navigationParams 的 user involvement 是 "browser UI"；或

    • navigationParams 的 request 属性中 text directive user activation 为 true。

      text directive user activation 不可被复制，仅有一次用户激活的文本片段可被激活。

20. 返回 document。

一个text directive allowing MIME type 是 MIME 类型，其本质 为 "text/html" 或 "text/plain"。

注：如滚动到片段所述， 片段处理由各 MIME 类型单独定义。因此滚动到片段中滚动文本指令只应应用于 text/html 类型的媒体。然而，实际上浏览器会对 text/plain 等其它类型应用 HTML 片段处理（如为 text/plain 文档加 id 后导航片段能滚动）。因此在 text/plain 文档启用文本指令有用。其余类型显式禁止，防止对敏感应用数据（如 text/css、application/json、application/javascript 等）发起 XS-Search 攻击。

这段内容是否适合写入 HTML 规范？

补充（已在§ 3.4.1 调用文本指令饱和修改）滚动到片段，新增布尔参数 allow text directive scroll：

猴补丁 HTML § 7.4.6.3 滚动到片段：

要滚动到给定文档 document 和布尔变量 allow text directive scroll 的片段：

1. 若 document 的指示部分为 null，则目标元素设为 null。

2. ...

3. 否则：

   1. 断言：document 的指示部分是元素或范围。

   2. ...

   4. 如 target 为范围，则：

      1. 如 allow text directive scroll 为 false，返回。

      2. 将 target 设为target的第一个共同祖先。

      3. ...

补充try to scroll to the fragment，新增布尔标志 allow text directive scroll，替换第2步任务内容：

猴补丁 [HTML]：

要为文档 document （及布尔变量 allow text directive scroll）尝试滚动到片段，并行执行如下步骤：

1. 等待一段实现自定义时间。

2. 在 navigation and traversal task source 上为 document 的关联全局对象排队全局任务，执行如下：

   1. 如 document 无解析器、解析器已停止、或 UA 认为用户已不关心滚动，则中止步骤。

   2. 按 document 和allow text directive scroll滚动到片段。

   3. 如 document 的指示部分依然为 null，再次用同参数 try to scroll to the fragment。

补充update document for history step application，新增布尔 allow text directive scroll，滚动时用之：

猴补丁 [HTML]：

To update document for history step application given a Document document, a session history entry entry, a boolean doNotReactivate, integers scriptHistoryLength and scriptHistoryIndex, an optional list of session history entries entriesForNavigationAPI, and a boolean allow text directive scroll:

1. Let documentIsNew be true if document’s latest entry is null; otherwise false.

2. ...

5. If documentsEntryChanged is true, then:

   1. Let oldURL be document’s latest entry’s URL.

   2. ...

6. If documentIsNew is true, then:

   1. Try to scroll to the fragment with document and allow text directive scroll.

补充apply the history step 算法，传递 allow text directive scroll 调用 update document for history step application ：

猴补丁 [HTML]：

apply the history step，参数：step、traversable、checkForCancelation、sourceSnapshotParams、initiatorToCheck、userInvolvementForNavigateEvents，和 allow text directive scroll（默认 false），步骤如下，返回 "initiator-disallowed"、"canceled-by-beforeunload"、"canceled-by-navigate" 或 "applied"。

14. While completedChangeJobs does not equal totalChangeJobs:

    1. ...

    11. Queue a global task on navigation and traversal task source，入参：navigable 的 active window，执行如下步骤：

        1. 如 changingNavigableContinuation 的 update-only 为 false：

           1. ...

           2. 为 navigable 激活历史条目 targetEntry。

        2. 定义 updateDocument：执 targetEntry 的 document、targetEntry、changingNavigableContinuation 的 update-only、scriptHistoryLength、scriptHistoryIndex、entriesForNavigationAPI、allow text directive scroll

        3. 如 targetEntry 的 document 等于 displayedDocument，执 updateDocument。

15. Let totalNonchangingJobs be the size of nonchangingNavigablesThatStillNeedUpdates.

补充apply the push/replace history step，传递 allow text directive scrolling 至 apply the history step：

猴补丁 [HTML]：

apply the push/replace history step，参数：step、traversable，和布尔 allow text directive scroll（默认false）：

返回 apply the history step(stap, traversable, false, null, null, null, allow text directive scroll).

注：allow text directive scroll 在遍历和重载时故意不设置。这样可避免大量传递和发起源、用户参与、历史滚动状态等检查。此时文本指令仍可作为文档指示部分（高亮可恢复）。

补充 finalize a cross-document navigation，增加user involvement参数并计算及传递 allow text directive scrolling：

猴补丁 [HTML]：

finalize a cross-document navigation，参数：navigable、historyHandling、historyEntry、user navigation involvement user involvement（默认 "none"）：

1. 断言：执行于 navigable 的 traversable navigable 的会话历史遍历队列。

2. ...

10. 令allow text directive scroll为检查文本指令是否可被滚动的结果，参数为 historyEntry 的document、historyEntry 的document state 的initiator origin、user involvement

11. apply the push/replace history step，参数 targetStep、traversable，allow text directive scroll。

补充navigate算法，传递 user involvement 至 finalize a cross-document navigation：

猴补丁 [HTML]：

1. ...

20. . 并发执行如下步骤：

    1. ...

    9. . 努力用下述参数填充历史条目的文档：navigable、"navigate"、sourceSnapshotParams、targetSnapshotParams、navigationId、navigationParams、cspNavigationType，并在步骤完成后执行：

       1. 为 navigable 的 traversable 附加会话历史遍历步骤，调用 finalize a cross-document navigation，参数：navigable、historyHandling、historyEntry、userInvolvement。

补充navigate to a fragment 算法，添加 initiator origin 参数，且滚动时传递 allow text directive scroll：

猴补丁 [HTML]：

navigate to a fragment，参数：navigable、url、historyHandling、userInvolvement、navigationAPIState、navigationId，origin initiator origin：

1. 令 navigation 为 navigable 的 active window 的 navigation API。

2. ...

14. 用 navigable 的 active document、historyEntry、true、scriptHistoryIndex、scriptHistoryLength 调用 update document for history step application。

15. 用 navigation、historyEntry、historyHandling，更新 navigation API 的 same-document navigation 条目。

16. 令allow text directive scroll为调用检查文本指令是否可被滚动，参数为navigable 的活动文档、initiator origin、userInvolvement。

17. 用 navigable 的活动文档，allow text directive scroll，滚动到片段。

补充navigate算法，导航到片段时传递 initiator origin：

猴补丁 [HTML]：

10. 如导航须替换，historyHandling 设为 "replace"。

11. 如下列全为真：

    • documentResource 为 null；

    • response 为 null；

    • url 等于 navigable 活动会话历史条目（排除 fragment 版本）；

    • url 的 fragment 非 null,

    则：

    1. 使用参数 navigable、url、historyHandling、userInvolvement、navigationAPIState、navigationId、initiatorOriginSnapshot调用 navigate to a fragment。

    2. 令 navigation 为 navigable 的活动 window 的 navigation API。

3.5.5. 限制加载时滚动

本节定义如何使用 force-load-at-top 策略来阻止在加载新文档时发生所有类型的滚动，包括但不限于文本指令。

需要决定 force-load-at-top 与 Navigation API 的交互方式。[Issue #WICG/scroll-to-text-fragment#242]

修订 restore persisted state 步骤，增加能抑制滚动恢复的新布尔参数：

猴补丁 [HTML]：

要 restore persisted state from a session history entry entry , and boolean suppressScrolling 执行：

1. 如果 entry 的 scroll restoration mode 为 "auto"，suppressScrolling 为 false，且 entry 的 document 的相关全局对象的导航 API 的 suppress normal scroll restoration during ongoing navigation 为 false，则根据 entry 恢复滚动位置信息。

2. ...

修订 update document for history step application 步骤，检查 force-load-at-top 策略，若被设置则避免在新文档中滚动。

猴补丁 [HTML]：

1. ...

4. 将 document 的历史对象长度设为 scriptHistoryLength。

5. 令 scrollingBlockedInNewDocument 为对 document 获取 force-load-at-top 策略值的结果。

6. 如果 documentsEntryChanged 为 true，则：

   1. 设 oldURL 为 document 的最新 entry 的 URL。

   2. ...

   5. 如果 documentIsNew 为 false，则：

      1. 为同文档导航用 navigation、entry 和 "traverse" 更新导航 API 条目。

      2. 派发名为 popstate 的事件...

      3. 用 entry 和 suppressScrolling 设为 false恢复持久化状态。

      4. 如果 oldURL 的 fragment 不等于...

   6. 否则，

      1. 断言：entriesForNavigationAPI 被传入。

      2. 用 entry 和 scrollingBlockedInNewDocument恢复持久化状态。

      3. 用 navigation、entriesForNavigationAPI 和 entry 初始化新文档的导航 API 条目。

7. 如果 documentIsNew 为 true，则：

   1. 如 scrollingBlockedInNewDocument 为 false，为 document 尝试滚动到片段。

   2. 此时可为新建文档运行脚本。

8. 否则，如果 documentsEntryChanged 为 false 且 doNotReactivate 为 false，则：

   1. ...

3.6. 导航到文本片段

3.6.1. 在文档中查找范围

text=prefix-,foo&unknown&text=bar,baz

text=prefix-,foo
text=bar,baz

:~:text=The quick,lazy dog

<div>The<div> </div>quick brown fox</div>
<div>jumped over the lazy dog</div>

<div>The quick brown fox</div>
<div>jumped over the lazy dog</div>

<div>
  a<em>b</em>c<div>d</div>e
</div>

如果一个节点是元素，属于HTML 命名空间，并且满足下列任一条件，则该节点为搜索不可见。

1. 其 样式计算值 的 display 属性为 none。

2. 该节点序列化后为空元素。

3. 类型为下列之一： HTMLIFrameElement， HTMLImageElement， HTMLMeterElement， HTMLObjectElement， HTMLProgressElement， HTMLStyleElement， HTMLScriptElement， HTMLVideoElement， HTMLAudioElement

4. 是 select 元素，且其 multiple 属性不存在。

如果节点本身或其任一包含shadow的祖先 是搜索不可见，则为 不可搜索子树。

如果节点是 Text 节点，其父元素的样式计算值的 visibility 属性为 visible，且节点正在被渲染，则为 可见文本节点。

如果节点是 element，且其 样式计算值的 display 属性为下述任意值： block、table、flow-root、grid、flex、list-item，则有 块级显示。

3.6.2. 词边界

词边界 在 [UAX29] 的 Unicode 文本分割 § Word_Boundaries 中定义。Unicode 文本分割 § 默认词边界 定义了默认的词边界集合，但如规范所述，应根据区域设置使用更复杂的算法。

基于词典的词界定在没有单词分隔字符的语言区域设置中应特别注意。例如在英语中，单词由空格字符（' '）分隔；然而在日语中没有将单词彼此分隔的字符。在此类情况中，且当字母表字符少于 100 个时，词典中被视为有效的一字词不得超过字母表的 20%。

区域设置 是一个字符串，包含一个有效的 [BCP47] 语言标签，或为空字符串。空字符串表示主要语言未知。

在给定 区域设置 startLocale 和 endLocale 的情况下，子字符串在 字符串 text 中被称为 词界定，当且仅当其首字符的位置在给定 startLocale 下 处于词边界，并且其末字符之后的位置在给定 endLocale 下 处于词边界。

一个数字 position 在给定 区域设置 locale 的情况下，若在 字符串 text 中，按照 locale 的规则，要么在第 position 个代码单元之前立即存在一个 词边界，要么 text 的长度大于 0 且 position 等于 0 或等于 text 的长度，则称该 position 处于词边界。

3.7. 指示文本匹配

用户代理可以选择在 尝试滚动到片段 步骤中或通过其他机制将文本片段滚动到可见区域；但并不要求必须将匹配滚动到视图中。

用户代理应该以某种方式在视觉上指示被匹配的文本，使用户能够注意到该匹配，例如使用高对比度高亮。

用户代理应向用户提供某种取消匹配指示的方法，使得被匹配的文本不再以视觉方式被指示。

具体的指示外观和机制由用户代理定义。然而，用户代理不得使用任何作者脚本可观察的方式来指示匹配，例如使用文档的 selection。这样做可能允许内容外泄的攻击向量。

用户代理不得以任何方式对提供的上下文项进行可视指示。

由于指示器不是文档内容的一部分，用户代理应考虑将其与页面内容在用户感知上区分开来。

3.7.1. 用户代理功能中的 URL

用户代理为文档的 URL 提供了若干使用场景（不包括像 window.location 这样的程序化 API）。示例包括显示当前可见文档 URL 的地址栏，或当用户请求为当前页面创建书签时使用的 URL。

为避免用户困惑，用户代理在是否在这些 URL 中包含 片段指令 一事上应保持一致。本节为用户代理如何处理这些情况提供一组默认建议。

一般原则是：只有当视觉指示可见（即未被取消）时，URL 才应包含 片段指令。如果用户取消了指示，URL 应通过移除 片段指令 来反映该操作。

如果 URL 包含文本片段但在当前页面未找到匹配，用户代理可以选择在暴露的 URL 中省略它。

下面提供一些常见示例。

3.7.1.1. 地址栏

地址栏的 URL 在被视觉指示时应包含文本片段。当用户取消该指示时，片段指令应从地址栏 URL 中剥离。

建议即便在文档中未找到匹配，也在地址栏的 URL 中显示文本片段。

3.7.1.2. 书签

许多用户代理提供“书签”功能，允许用户在用户代理界面中存储指向当前页面的便捷链接。

新创建的书签默认应当在 URL 中包含 片段指令 当且仅当 已找到匹配并且视觉指示尚未取消。

从书签导航到 URL 应按典型导航的方式处理 片段指令。

3.7.1.3. 分享

一些用户代理提供将当前页面共享给他人的方法，通常是将 URL 提供给另一个应用或消息服务。

在这些情况下提供 URL 时，只有当已找到匹配并且视觉指示尚未取消时，才应包含 片段指令。

3.8. 文档策略集成

本规范在 Document Policy 中定义了名为 "force-load-at-top" 的配置点。其类型为 boolean，默认值 为 false。

Document-Policy: force-load-at-top

该策略对基于片段的滚动阻止在对 滚动到片段 算法的修订中进行了规定，见本文件的 § 3.6 导航到文本片段 部分。

历史滚动恢复通过在 恢复持久化状态 步骤中插入新步骤（在步骤 2 之后）来被阻止：

3. 获取文档策略值 中 "force-load-at-top" 特性的值，针对该 Document。如果结果为 true，则用户代理不应为该 Document 或其任何可滚动区域恢复滚动位置。

3.9. 特性可检测性

为特性可检测性，我们建议添加一个新的 FragmentDirective 接口，当用户代理支持该特性时，通过 document.fragmentDirective 暴露。

[Exposed=Window]
interface FragmentDirective {
};

我们将 Document 接口补充为包含一个 fragmentDirective 属性：

partial interface Document {
    [SameObject] readonly attribute FragmentDirective fragmentDirective;
};

该对象未来可用于暴露有关文本片段或其他片段指令的更多信息。

4. 生成文本片段指令

本节包含建议，供用户代理自动生成带有 文本指令 的 URL 时参考。这些建议并非规范性，但用于确保生成的 URL 在稳定性和可用性上尽可能良好。

4.1. 优先精确匹配而非基于范围的匹配

匹配文本可以作为精确字符串 "text=foo%20bar%20baz" 提供，或作为范围 "text=foo,bar" 提供。

在可行情况下，优先指定整个字符串。这可以确保即使目标页面被删除或更改，预期的目标仍能从 URL 本身推断出来。

The first recorded idea of using digital electronics for computing was the
1931 paper "The Use of Thyratrons for High Speed Automatic Counting of
Physical Phenomena" by C. E. Wynn-Williams.

当引用文本过长且对整个字符串编码会产生难以处理的 URL 时，基于范围的匹配可能有帮助。

建议将短于 300 字符的文本片段使用精确匹配编码。超过该限值时，用户代理可以将字符串编码为基于范围的匹配。

4.2. 仅在必要时使用上下文

上下文项允许 文本指令 对页面上的文本片段进行消歧。然而，它们的使用在某些情况下会使 URL 更脆弱。通常，所需的字符串会在元素边界开始或结束。上下文因此可能存在于相邻元素中。页面结构的变化可能会使上下文与匹配文本不再相邻，从而使 文本指令 失效。

<div class="section">HEADER</div>
<div class="content">Text to quote</div>

text=HEADER-,Text%20to%20quote

当文本片段足够长且唯一时，鼓励用户代理避免添加多余的上下文项。

仅在下列任一情况为真时使用上下文：

• 用户代理判断所引用文本存在歧义
• 所引用文本包含 3 个或更少的单词

4.3. 确定是否需要片段 id

当用户代理导航到包含 文本指令 的 URL 时，如果存在基于元素 id 的常规片段且未找到文本片段，将回退为滚动该元素 id 到视图中。

在文档中更改文本使 文本指令 失效的情况下，这可以作为一种有用的后备。

The earliest known tool for use in computation is the Sumerian abacus

然而，用户代理应当确保回退的元素 id 片段是合适的：

By the late 1960s, computer systems could perform symbolic algebraic
manipulations