文字片段

¥Concepts and usage

从历史上看，网络的关键特性之一始终是它能够在不同文档之间提供链接 - 这使得网络成为一个网络：

¥Historically, one of the web's key features has always been its ability to provide links between different documents — it is what makes the web, a web:

• 你可以通过链接到文档的 URL 来链接到文档的顶部，例如：
  • [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a](/en-US/docs/Web/HTML/Element/a)。
• 你可以通过链接到文档的 URL 加上该部分的文档片段 (ID) 来链接到文档的特定部分，例如：
  • [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#browser_compatibility](/en-US/docs/Web/HTML/Element/a#browser_compatibility)。

链接到特定文档片段的问题是链接页面的作者需要放置一个锚点才能实际链接到。上面的第二个示例链接到 ID 为 browser_compatibility 的 h2 元素：

¥The issue with linking to specific document fragments is that the author of the linked page needs to put an anchor in place to actually link to. The second example above links to an h2 element with an ID of browser_compatibility:

<h2 id="browser_compatibility">
  <a href="#browser_compatibility">Browser compatibility</a>
</h2>

如果更改或删除 ID，则文档片段将被忽略，并且链接仅链接到页面顶部。就优雅降级而言，这是合理的，但如果链接的作者能够完全控制链接到的位置，而不需要依赖页面作者，那么可能会更好。

¥If the ID is changed or removed, the document fragment is ignored, and the link just links through to the top of the page. This is reasonable in terms of graceful degradation, but it would arguably be better if the author of the link had full control over where they link to, without needing to rely on the page author.

文本片段使这成为现实 - 它们允许链接作者以灵活的方式指定要链接的文本内容，而不是文档片段。

¥Text fragments make this a reality — they allow link authors to specify text content to link to, rather than document fragments, in a flexible manner.

¥Syntax

与文档片段类似，文本片段被附加到 URL 上的哈希符号 (#) 之后。然而语法有点不同：

¥In a similar manner to document fragments, text fragments are appended onto a URL after a hash symbol (#). The syntax however is a bit different:

https://example.com#:~:text=[prefix-,]textStart[,textEnd][,-suffix]

需要理解的关键部分如下：

¥The key parts to understand are as follows:

:~:

该字符序列也称为片段指令，它告诉浏览器接下来是一个或多个用户代理指令，这些指令在加载期间从 URL 中剥离，以便作者脚本无法直接与它们交互。用户代理指令也称为指令。

text=

文本指令。这向浏览器提供了一个文本片段，定义了链接文档中要链接到的文本。

textStart

指定链接文本开头的文本字符串。

textEnd Optional

指定链接文本结尾的文本字符串。

prefix- Optional

后跟连字符的文本字符串，指定哪些文本应紧接在链接文本之前，中间只允许有空格。这有助于浏览器在存在多个匹配项的情况下选择正确的链接文本。

-suffix Optional

连字符后跟一个文本字符串，指定哪些文本应紧跟在链接文本之后，中间只允许有空格。这有助于浏览器在存在多个匹配项的情况下选择正确的链接文本。

支持的浏览器将滚动到并高亮链接文档中与指定指令匹配的第一个文本片段。请注意，可以指定多个文本片段在同一 URL 中高亮，方法是用与号 (&) 字符分隔它们。

¥Supporting browsers will scroll to and highlight the first text fragment in the linked document that matches the specified directive. Note that it is possible to specify multiple text fragments to highlight in the same URL by separating them with ampersand (&) characters.

¥Usage notes

• 用于 textStart、textEnd、prefix- 和 -suffix 值的文本字符串必须是 percent-encoded。
• 匹配不区分大小写。
• 各个 textStart、textEnd、prefix- 和 -suffix 字符串需要完全驻留在同一个 块级元素 内，但完整的匹配可以跨越多个元素边界。
• 出于安全原因，该功能要求在 noopener 上下文中打开链接 - 使用此功能时，你需要将 rel="noopener" 添加到 <a> 元素，并将 noopener 添加到 window.open() 调用。
• 仅在完整（非同一页面）、用户启动的导航中调用文本片段。
• 文本片段仅应用于主框架；不会在 <iframe> 内搜索文本，并且 iframe 导航不会调用文本片段。
• 对于希望选择退出的网站，基于 Chromium 的浏览器支持可以发送的 文件政策 标头值，以便用户代理不会处理文本片段：
  http

  Document-Policy: force-load-at-top
  

注意：如果提供的文本片段与链接文档中的任何文本都不匹配，或者浏览器不支持文本片段，则忽略整个文本片段并链接文档的顶部。

¥Note: If the provided text fragment does not match any text in the linked document, or if the browser does not support text fragments, the whole text fragment is ignored and the top of the document is linked.

¥Examples

¥Simple text fragment with textStart

• https://example.com#:~:text=for 滚动到并高亮文档中文本 for 的第一个实例。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=human](/en-US/docs/Web/HTML/Element/a#:~:text=human) 滚动到并高亮文档中文本 human 的第一个实例。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL](/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL) 滚动到并高亮文档中文本 linked URL 的第一个实例。

¥textStart and textEnd

• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=human,URL](/en-US/docs/Web/HTML/Element/a#:~:text=human,url) 滚动到并高亮以 human 开头并以 URL 结尾的文本字符串的第一个实例。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,defining%20a%20value](/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,defining%20a%20value) 滚动到并高亮以 linked URL 开头并以 defining a value 结尾的文本字符串的第一个实例。请注意高亮的文本如何跨越多个块级元素。

¥Examples with prefix- and/or -suffix

• https://example.com#:~:text=asking-,for 滚动到并高亮文档中文本 for 的第二个实例。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=sent-,referrer](/en-US/docs/Web/HTML/Element/a#:~:text=sent-,referrer) 滚动到并高亮文本 referrer 的第一个实例，该实例前面有文本 sent。这是文档中 referrer 的第 5 个实例；如果没有前缀，第一个实例将高亮。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,-'s%20format](/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,-'s%20format) 滚动到并高亮文本 linked URL 的第一个实例，该文本紧随其后是文本 's format。这是文档中 linked URL 的第 5 个实例；如果没有后缀，第一个实例将高亮。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=downgrade:-,The%20Referer,be%20sent,-to%20origins](/en-US/docs/Web/HTML/Element/a#:~:text=downgrade:-,The%20Referer,be%20sent,-to%20origins) 滚动到并高亮文本 The Referer ... be sent 的实例，该实例的前缀为 downgrade:，后缀为 to origins。这说明了一个更复杂的示例，其中前缀/后缀用于定位要链接到的特定文本实例。例如，尝试删除前缀，然后查看匹配的内容。

¥URLs with multiple text fragments

你可以指定多个文本片段在同一 URL 中高亮，方法是用与号 (&) 字符分隔它们。让我们看几个例子：

¥You can specify multiple text fragments to highlight in the same URL by separating them with ampersand (&) characters. Let's look at a couple of examples:

• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=Causes&text=linked](/en-US/docs/Web/HTML/Element/a#:~:text=causes&text=linked) 滚动到并高亮文本字符串 Causes 和 linked 的第一个实例。
• [https://web.nodejs.cn/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,-'s%20format&text=Deprecated-,attributes,attribute](/en-US/docs/Web/HTML/Element/a#:~:text=linked%20URL,-'s%20format&text=Deprecated-,attributes,attribute) 滚动并高亮两个文本实例：
  • 文本 linked URL 的第一个实例，紧随其后的是文本 's format。
  • 以 attributes 开头并以 attribute 结尾的文本字符串的第一个实例，其前缀为 Deprecated。

如果你没有看到一个或多个文本片段高亮，并且你确定语法正确，则你可能只是高亮了与预期不同的实例。它可能会高亮，但在屏幕外。

¥If you don't see one or more of your text fragments highlighted and you are sure you've got the syntax correct, you might just be highlighting a different instance than the one you expected. It might be highlighted, but offscreen.

¥Styling matched text fragments

浏览器可以自由地以他们选择的任何默认方式设置高亮文本的样式。CSS 伪元素模块级别 4 定义了一个伪元素 ::target-text，它允许你指定自定义样式。

¥Browsers are free to style the highlighted text in whatever default way they choose. The CSS Pseudo-Elements Module Level 4 defines a pseudo-element, ::target-text, which allows you to specifying custom styling.

例如，在我们的 滚动到文本演示 中，我们有以下 CSS：

¥For example, in our scroll-to-text demo we have the following CSS:

::target-text {
  background-color: rebeccapurple;
  color: white;
}

尝试在支持的浏览器中点击上面的链接来查看其效果。

¥Try following the above link in a supporting browser to see the effect this has.

¥Feature Detectability

通过 Document.fragmentDirective 属性访问的 FragmentDirective 对象可用于测试浏览器是否支持文本片段。

¥The FragmentDirective object, which is accessed via the Document.fragmentDirective property, can be used to test whether or not text fragments are supported in a browser.

尝试在支持浏览器的开发工具中，在包含一个或多个匹配文本片段的选项卡中运行以下命令：

¥Try running the following in a supporting browser's devtools, in a tab with one or more matched text fragments:

document.fragmentDirective;
// returns an empty FragmentDirective object, if supported
// undefined otherwise

目前该功能主要用于特性检测。将来，FragmentDirective 对象可能包含附加信息。

¥This functionality is mainly intended for feature detection at present. In the future, the FragmentDirective object could include additional information.

¥Reference

FragmentDirective

代表文本片段的对象。目前是空的，主要用于特性检测。

Document.fragmentDirective

返回当前文档的 FragmentDirective。

::target-text

表示当前文档中高亮的文本片段。它允许作者自定义文本片段的样式。

¥Browser compatibility

¥See also

• 大胆链接以前没有人链接过的地方：文本片段