HTMLRange.surroundContents使用教程及示例

实操建议：

• 先用 range.startContainer === range.endContainer && range.startContainer.nodeType === Node.TEXT_NODE 做前置校验，不满足就别调 surroundContents
• 如果用户选中了跨标签文本（比如从

  Hello world! 中选中 “o world”），surroundContents 必然失败 —— 这时候得换思路，用 extractContents + 插入新元素 + insertNode 手动拼

• 注意：即使只选中纯文本，若光标在换行符或空格前后（尤其来自 pre 或 white-space: pre），也可能触发边界落在不同文本节点上

怎么安全地用 surroundContents 包裹纯文本选区？

只适用于「整段连续、未被 HTML 标签打断」的文本，比如

这是一段没有内联标签的普通文字

实操步骤：

• 获取当前选区：const selection = window.getSelection(); const range = selection.getRangeAt(0);
• 确认范围合法：if (range.startContainer.nodeType === Node.TEXT_NODE && range.startContainer === range.endContainer)
• 创建包裹元素，例如：const span = document.createElement('span'); span.className = 'highlight';
• 调用：range.surroundContents(span); —— 此时原选中文本会变成 span 的子节点

注意：surroundContents 会自动把原内容移出并塞进新元素，不需要手动 deleteContents；但一旦执行，原 Range 就失效了，后续操作需重新获取选区。

为什么 surroundContents 不支持包裹已有的 inline 元素？

因为它的设计语义是「将纯字符内容整体封装」，而非「套一层 DOM 容器」。如果选区里已有 、 等，range.startContainer 和 range.endContainer 很可能分别是两个不同的 Text 节点（比如 "foobarbaz" 中选中 "obarba"，起点在第一个文本节点末尾，终点在第二个文本节点中间），违反同节点约束。