Selection:setBaseAndExtent() 方法

Baseline 已广泛支持

该特性已非常成熟,可在多种设备和浏览器版本上使用。自 2017 年 4 月以来,它已在各大浏览器上可用。

Selection 接口的 setBaseAndExtent() 方法设置选区为一个范围,该范围包含两个指定 DOM 节点的所有部分或部分内容,以及它们之间的任何内容。

锚点和焦点节点可以位于 Shadow tree 中,如果浏览器支持的话。

语法

js
setBaseAndExtent(anchorNode, anchorOffset, focusNode, focusOffset)

参数

anchorNode

选区开始处的节点。

anchorOffset

从锚点节点开始需要排除的子节点数量。因此,例如,如果值为 0,则包含整个节点。如果值为 1,则包含整个节点减去第一个子节点。依此类推。

如果 anchorNode 是一个 Text 节点,则偏移量指的是从 Node.textContent 开始需要从选区中排除的字符数。

focusNode

选区结束处的节点。

focusOffset

从焦点节点开始需要包含在选区中的子节点数量。因此,例如,如果值为 0,则整个节点被排除。如果值为 1,则包含第一个子节点。依此类推。

如果 focusNode 是一个 Text 节点,则偏移量指的是从 Node.textContent 开始需要包含在选区中的字符数。

注意: 如果焦点位置在文档中出现在锚点位置之前,则选区的方向会反转——光标会放置在文本的开头而不是结尾,这对任何后续的键盘命令都很重要。例如,Shift + ➡︎ 会导致选区从开头收窄而不是在结尾增长。

返回值

无(undefined)。

异常

IndexSizeError DOMException

如果 anchorOffset 大于 anchorNode 中的子节点数量,或者 focusOffset 大于 focusNode 中的子节点数量,则会抛出此错误。

示例

在此示例中,我们有两个段落,其中包含 span 元素,每个 span 包含一个单词。第一个被设置为 anchorNode,第二个被设置为 focusNode。我们还有一个额外的段落位于这两个节点之间。

接下来,我们有两个表单输入框,允许您设置 anchorOffsetfocusOffset — 它们都具有默认值 0。

我们还有一个按钮,按下时会调用一个函数,该函数使用指定的偏移量运行 setBaseAndExtent() 方法,并将选区复制到 HTML 最底部的输出段落中。

html
<h1>setBaseAndExtent example</h1>
<div>
  <p class="one">
    <span>Fish</span><span>Dog</span><span>Cat</span><span>Bird</span>
  </p>
  <p>MIDDLE</p>
  <p class="two">
    <span>Car</span><span>Bike</span><span>Boat</span><span>Plane</span>
  </p>
</div>

<div>
  <p>
    <label for="aOffset">Anchor offset</label>
    <input id="aOffset" name="aOffset" type="number" value="0" />
  </p>
  <p>
    <label for="fOffset">Focus offset</label>
    <input id="fOffset" name="fOffset" type="number" value="0" />
  </p>
  <p><button>Capture selection</button></p>
</div>

<p><strong>Output</strong>: <span class="output"></span></p>

注意: <p class="one"><p class="two"> 的开始标签及其后面的 <span> 开始标签之间故意没有 空格 — 以避免出现会影响预期子节点数量的文本节点。(即使这些文本节点只包含空格,它们仍然是额外的子节点;更多信息请参阅 Node.firstChild 示例)。

JavaScript 代码如下:

js
const one = document.querySelector(".one");
const two = document.querySelector(".two");

const aOffset = document.getElementById("aOffset");
const fOffset = document.getElementById("fOffset");

const button = document.querySelector("button");

const output = document.querySelector(".output");

let selection;

button.onclick = () => {
  try {
    selection = document.getSelection();
    selection.setBaseAndExtent(one, aOffset.value, two, fOffset.value);
    const text = selection.toString();
    output.textContent = text;
  } catch (e) {
    output.textContent = e.message;
  }
};

请尝试下面的实时示例,设置不同的偏移量值,看看它们如何影响选区。

注意: 您可以在 GitHub 上找到此示例也可以在线查看)。

规范

规范
Selection API
# dom-selection-setbaseandextent

浏览器兼容性

另见