Range.surroundContents 为什么会拒绝跨越部分元素的选区

如果 Range.surroundContents() 在跨元素选区上抛出 InvalidStateError，通常不是因为 Range 不能跨越多个文本节点，而是因为选区“切进了”某个非 Text 元素，却没有把这个元素完整选中。最稳妥的判断方法是先看两个边界点，再决定用完整节点包裹、单文本节点包裹，还是改用 extractContents() 处理复杂片段。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Range/surroundContents

先看异常真正检查的是什么

Range 的两个边界分别由 startContainer/startOffset 和 endContainer/endOffset 描述。边界可以落在文本节点的字符之间，也可以落在元素的子节点索引之间。因此，一个看起来只是“选了一段文字”的操作，底层可能已经只选中了某个 的一半。

MDN 对 surroundContents() 的限制可以归纳为一句话：选区只能包含文本节点和完整选中的节点，不能部分包含非 Text 节点。方法执行时会把选中内容移入新父节点，再把新父节点放回原位置，并让当前 Range 选择这个新父节点。

用 DOM 边界解释“部分包含”

下面的结构足够说明问题：

请阅读 这段重点 内容

假设用户从“请阅读 ”的末尾拖到“这段重点”的中间，Range 的起点在 p 下面的普通 Text 节点，终点在 strong 里面的 Text 节点。此时 strong 只有一部分内容被纳入选区，元素本身也没有被完整选中，所以直接包裹会失败。

反过来，如果边界落在 p 的子节点之间，把整个 strong 当作一个完整子节点选中，或者两个边界都落在同一个 Text 节点中，选区就满足 surroundContents() 的结构要求。这里的关键不是“跨了几个元素”，而是每个非 Text 节点在选区中是完整出现，还是被边界截断。

方案一：单个文本节点内直接包裹

如果产品只需要给同一段连续文本加高亮，最好让起点和终点都落在同一个 Text 节点中。这样 Range 不会部分包含元素，代码也最短：

const textNode = document.querySelector("#article").firstChild;
const range = document.createRange();

// 只在同一个文本节点的字符偏移之间建立选区。
range.setStart(textNode, 0);
range.setEnd(textNode, 4);

const mark = document.createElement("mark");
mark.className = "keyword-highlight";

// 该选区没有切入任何非 Text 元素，因此可以直接包裹。
range.surroundContents(mark);

这类方案适合搜索结果高亮、单段提示词标记等场景。要注意 Text 节点不是元素，不能把 querySelector() 返回的 p 直接当成字符容器；真正的字符偏移应该设置在它的 Text 子节点上。

方案二：完整选中元素时使用 selectNode

如果目标本来就是一个完整的元素，例如希望把整个 strong 再包进 mark，不要手动猜字符偏移，直接用 selectNode() 表达意图：

const strong = document.querySelector("#article strong");
const range = document.createRange();

// 选中 strong 元素本身及其全部内容，而不是只选其中几个字符。
range.selectNode(strong);

const mark = document.createElement("mark");
mark.className = "whole-element-highlight";
range.surroundContents(mark);

这个版本将“完整节点”交给 Range 管理，适合标签式内容、已经分好段的富文本节点和编辑器内部的整节点操作。若需求只是包住元素的子内容，也可以使用 selectNodeContents()，但仍要确认不会因此切入更深层的非 Text 节点。

方案三：复杂跨元素选区改用 extractContents

真正的用户选区经常跨过多个内联标签，而且起点和终点都可能落在不同元素内部。这时继续强行调用 surroundContents()，只会把结构限制转化为异常。更合适的思路是提取片段，再把片段放进新父节点：

function wrapComplexRange(range, tagName = "mark") {
  // 先提取选区；复杂边界由 Range 按 DOM 结构处理。
  const fragment = range.extractContents();
  const wrapper = document.createElement(tagName);

  // 把提取出的 DocumentFragment 放入新父节点，减少手动拆节点。
  wrapper.append(fragment);
  range.insertNode(wrapper);

  // 让后续操作明确指向新插入的包装节点。
  range.selectNode(wrapper);
  return wrapper;
}

const selection = window.getSelection();
if (selection && selection.rangeCount > 0) {
  const range = selection.getRangeAt(0).cloneRange();
  wrapComplexRange(range);
}

extractContents() 会移除选区内容并返回 DocumentFragment。当选区只覆盖某个祖先元素的一部分时，片段中可能出现相应的克隆祖先结构，因此插入后要检查嵌套结果是否符合编辑器的模型。这个方案的优点是能处理复杂边界，代价是 DOM 结构可能被拆分，后续需要统一清理空节点或合并相邻标签。

三个方案怎么选

包装完成后别忘了恢复可用的 Range

surroundContents() 成功后，规范行为会让 Range 选择新父节点；手动组合 extractContents() 和 insertNode() 时则应自己决定 Range 的后续位置。对于编辑器来说，建议把“包装节点”“选区恢复”“空节点清理”作为一次事务完成，避免用户看到高亮已经插入，但光标却跳到文档开头。

如果只是预览选中内容，不要为了读取文本而修改 DOM，可以使用 range.toString() 或 cloneContents()。只有确定要改变文档结构时，才调用会移动节点的 extractContents()。

常见问题

跨越多个 Text 节点一定会报错吗？

不一定。只要中间遇到的非 Text 节点都被完整包含，跨越多个文本节点仍可能满足条件；真正危险的是边界切入了某个元素内部。

为什么 selectNodeContents 仍然可能失败？

它选中的是节点的子内容。如果该节点内部还包含多个元素，而边界最终只覆盖了其中一部分，非 Text 节点的部分包含问题仍然存在。

能不能先 catch 异常再改用 extractContents？

可以，但更建议在调用前根据选区用途做策略选择。异常兜底适合不可预测的用户选区；对于已知的编辑器命令，提前区分“单文本”“整节点”和“复杂片段”更容易维护。

归根结底，surroundContents() 拒绝的不是“跨元素”三个字，而是被选区截断的非 Text 节点。先读清两个边界点，再按结构选择方法，通常就能把异常从运行时问题变成一个明确的 DOM 选型问题。