JavaScript - Selection API

JavaScript Selection API 允许我们访问和更改用户选择的网页部分。这包括选择要突出显示的文本或元素，并提供与所选项目关联的选项。但需要注意的是，选择 API 在 Web Workers 中不可用，因此它只能在网页的主线程中使用。

JavaScript Selection API 提供了各种必要的 API，允许开发者访问和修改文档的特定部分。这些接口包含 Selection 和 Range 对象，以及在整个选择过程中发生的许多有用事件。

选择接口

Selection 对象显示用户选择的文本区域或光标的当前位置。每个文档都被赋予一个唯一的选择对象，可以通过 document.getSelection() 检索该对象，或者可以使用 Window.getSelection() 进行检查和修改。

用户可以在从左到右和从右到左之间进行选择。锚点是用户开始选择的位置，而焦点是用户结束选择的位置。当您使用桌面鼠标进行选择时，锚点会设置在您按下鼠标按钮的位置，而焦点会设置在您松开鼠标按钮的位置。

实例属性

以下是可供您参考的实例属性表 -

实例方法

下表列出了 Selection 接口的实例方法及其说明。

Document.getSelection()

Document 接口的 getSelection() 方法返回此文档的 Selection 对象，该对象表示用户选择的文本范围或插入符号的当前位置。它的作用类似于 window.getSelection()。

语法

以下是 Document.getSelection() 的语法 -

document.getSelection()

参数

此方法无需任何参数即可运行。

返回值

此方法基本上返回一个 Selection 对象，如果没有浏览上下文(例如，未附加的 <iframe>)，则返回 null。

示例

以下是展示 Document.getSelection() 对象用法的示例 -

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Document.getSelection Example</title>
</head>
<body>
   <p>Select some text in this paragraph and check the console.</p>
   <button onclick="getSelectedText()">Get Selected Text</button>
   
   <script>
      function getSelectedText() {
         let selection = document.getSelection();
         if (selection.rangeCount > 0) {
            document.write("Selected text: " + selection.toString());
         } else {
            document.write("No text selected.");
         }
      }
   </script>
</body>
</html>

输出

要查看消息，请使用浏览器的开发者工具(通常按 F12 键)并选择"控制台"选项卡。

在浏览器中运行上述代码后，在控制台上检查以下消息 -

Selected text: paragraph and check

Window.getSelection()

Window 接口的 getSelection() 方法返回与窗口文档关联的 Selection 对象，该对象表示用户选择的文本范围或插入符号的当前位置。

语法

以下是 Window.getSelection() 的语法 -

window.getSelection()

参数

此方法不需要任何参数。

返回值

此方法返回一个 Selection 对象，如果连接的文档具有浏览上下文(例如，如果窗口是未连接的 <iframe>)，则返回 null。

当 <iframe> 未显示时(例如，display: none)，Firefox 会返回 null，而其他浏览器会提供一个 Selection.type 设置为 None 的 Selection 对象。

示例

以下示例展示了 Window.getSelection() 对象的用法 -

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Window.getSelection Example</title>
</head>
<body>
   <p>Select some text in this paragraph and check the console.</p>
   <button onclick="getSelectedText()">Get Selected Text</button>

   <script>
      function getSelectedText() {
         let selection = window.getSelection();
         if (selection.rangeCount > 0) {
            document.write("Selected text: " + selection.toString());
         } else {
            document.write("No text selected.");
         }
      }
   </script>
</body>
</html>

输出

因此，当您在浏览器中运行上述 HTML 代码时，将会出现一个带有"获取选定文本"按钮的文本框。因此，当您选择一些文本并按下按钮后，在检查元素后，您会在控制台上看到以下消息 -

Selected text: this paragraph

Document: selectionchange 事件

当 Document 的当前 Selection 发生更改时，将触发 Selection API 的 selectionchange 事件。此事件无法取消，也不会冒泡。

可以通过为 selectionchange 注册事件监听器或使用 onselectionchange 事件处理程序来处理此事件。

语法

在 addEventListener() 等方法中使用事件名称，或设置事件处理程序属性。

addEventListener("selectionchange", (event) => {});
onselectionchange = (event) => {};

事件类型

这是一个通用事件。

示例

以下是 selectionchange 事件的示例 -

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Selection Change Example</title>
</head>
<body>
   <h1>Text Selection Example</h1>
   <p>Select some text in this paragraph to see the console messages about selection changes.</p>
   <p>Try selecting different parts of this text to see how it updates!</p>

   <script>
      // 使用 addEventListener 跟踪选择变化
      document.addEventListener("selectionchange", () => {
         document.write("Selection has changed:", document.getSelection().toString());
      });
        
      // 使用 onselectionchange 来处理选择变化
      document.onselectionchange = () => {
         document.write("Updated selection:", document.getSelection().toString());
      };
   </script>
</body>
</html>

输出

当您选择这些段落中的任何文本时，它会向控制台发送消息，告诉您您的选择已更改，并显示当前选定的材料。

[Log] Selection has changed: - "" (example.html, line 16)
[Log] Updated selection: - "" (example.html, line 21)
[Log] Selection has changed: - "" (example.html, line 16)
[Log] Updated selection: - "" (example.html, line 21)
[Log] Selection has changed: - "" (example.html, line 16)
[Log] Updated selection: - "" (example.html, line 21)
[Log] Selection has changed: - "Selection" (example.html, line 16)
[Log] Updated selection: - "Selection" (example.html, line 21)

节点:selectstart 事件

此事件在用户开始进行新的选择时发生。例如，用户可以点击并拖动以突出显示文本。假设该事件已被取消，则选择不会改变。

语法

在 addEventListener() 等方法中使用事件名称，或设置事件处理程序属性。

addEventListener("selectstart", (event) => {});
onselectstart = (event) => {};

事件类型

它也是一个通用事件。

示例

以下是 selectstart 事件的示例 -

<!DOCTYPE html>
<html lang="en">
<head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Select Start Example</title>
</head>
<body>
   <h1>Text Selection Example</h1>
   <p>Choose some text in this paragraph to check the console messages.</p>
   <p>Try different parts of this text!</p>

    <script>
      // 使用 addEventListener 跟踪文本选择何时开始
      document.addEventListener("selectstart", () => {
         document.write("Selection started");
      });
      
      // 使用 onselectstart 来处理文本选择何时开始
      document.onselectstart = () => {
         document.write("Selection started.");
      };
   </script>
</body>
</html>

输出

当您选择这些段落中的任意文本时，终端上将显示"选择已开始"和"选择已开始。"。

[Log] Selection started (example.html, line 16)
[Log] Selection started. (example.html, line 21)
[Log] Selection started (example.html, line 16)
[Log] Selection started. (example.html, line 21)
[Log] Selection started (example.html, line 16)
[Log] Selection started. (example.html, line 21)
[Log] Selection started (example.html, line 16)
[Log] Selection started. (example.html, line 21)
[Log] Selection started (example.html, line 16)
[Log] Selection started. (example.html, line 21)