Range API 完全指南：精确控制文档片段的 10 个实用技巧

前言#

Range API 是浏览器提供的强大接口，用于表示文档中的一个片段（可以包含节点与文本节点的一部分）。它能够精确控制 DOM 中的任意片段，而不需要破坏原有结构，是实现富文本编辑器、代码编辑器、PDF 标注工具等应用的核心技术。

本文将通过 10 个实用示例，带你掌握 Range API 的核心用法。

1. 精确插入内容到光标位置#

在可编辑元素中插入内容时，使用 Range API 可以实现精确的光标位置控制，支持插入 HTML 格式的内容。

1
// 在光标位置插入内容（支持 HTML）
2
function insertAtCursor(html) {
3
  const selection = window.getSelection();
4
  if (selection.rangeCount > 0) {
5
    const range = selection.getRangeAt(0);
6
    range.deleteContents(); // 删除选中内容
7

8
    const fragment = range.createContextualFragment(html);
9
    range.insertNode(fragment);
10

11
    // 移动光标到插入内容后面
12
    range.collapse(false);
13
    selection.removeAllRanges();
14
    selection.addRange(range);
15
  }
16
}
17

18
// 使用示例
19
insertAtCursor('<strong>插入的粗体文本</strong>');

核心方法说明：

getRangeAt(0)：获取当前选区的第一个 Range 对象
deleteContents()：删除选中的内容
createContextualFragment()：创建文档片段，可解析 HTML
collapse(false)：将光标移动到插入内容之后

2. 获取选中文本的精确位置坐标#

获取选中文本的边界矩形信息，常用于显示悬浮工具栏（如 Medium 编辑器的工具条）。

1
// 获取选中文本的边界矩形
2
function getSelectionCoords() {
3
  const selection = window.getSelection();
4
  if (selection.rangeCount > 0) {
5
    const range = selection.getRangeAt(0);
6
    const rect = range.getBoundingClientRect();
7

8
    return {
9
      top: rect.top,
10
      left: rect.left,
11
      width: rect.width,
12
      height: rect.height
13
    };
14
  }
15
}
16

17
// 用途：在选中文本旁边显示悬浮工具栏
18
function showToolbar() {
19
  const coords = getSelectionCoords();
20
  const toolbar = document.getElementById('toolbar');
21
  toolbar.style.top = (coords.top - 40) + 'px';
22
  toolbar.style.left = coords.left + 'px';
23
  toolbar.style.display = 'block';
24
}

应用场景：

富文本编辑器的格式化工具栏
划词翻译弹窗定位
批注气泡定位

3. 高亮搜索关键词（不破坏 DOM 结构）#

使用 Range API 可以精确地包裹文本节点，实现搜索高亮功能。

1
function highlightText(searchText) {
2
  const selection = window.getSelection();
3
  selection.removeAllRanges();
4

5
  const range = document.createRange();
6
  const textNode = document.querySelector('#content').firstChild;
7

8
  // 遍历文本节点查找匹配
9
  let startPos = 0;
10
  const text = textNode.textContent;
11

12
  while ((startPos = text.indexOf(searchText, startPos)) !== -1) {
13
    range.setStart(textNode, startPos);
14
    range.setEnd(textNode, startPos + searchText.length);
15

16
    const span = document.createElement('span');
17
    span.style.backgroundColor = 'yellow';
18
    range.surroundContents(span);
19

20
    startPos += searchText.length;
21
  }
22
}

注意事项：

surroundContents() 方法会将选区内容包裹在指定元素中
适用于纯文本节点，复杂 DOM 结构需使用 extractContents() 和 insertNode()

4. 提取选中内容的纯文本或 HTML#

获取用户选中内容的多种格式，用于复制、引用等功能。

1
function getSelectedContent() {
2
  const selection = window.getSelection();
3
  if (selection.rangeCount > 0) {
4
    const range = selection.getRangeAt(0);
5

6
    // 获取纯文本
7
    const text = range.toString();
8

9
    // 获取 HTML（包含标签）
10
    const fragment = range.cloneContents();
11
    const div = document.createElement('div');
12
    div.appendChild(fragment);
13
    const html = div.innerHTML;
14

15
    return { text, html };
16
  }
17
}

方法对比：

toString()：返回纯文本，忽略 HTML 标签
cloneContents()：返回包含所有节点和样式的文档片段

5. 智能选择 - 扩展选区到单词边界#

实现双击或快捷键选择完整单词的功能。

1
// 扩展选区到完整单词
2
function selectWord() {
3
  const selection = window.getSelection();
4
  if (selection.rangeCount > 0) {
5
    const range = selection.getRangeAt(0);
6

7
    // 向前扩展到单词边界
8
    while (range.startOffset > 0) {
9
      range.setStart(range.startContainer, range.startOffset - 1);
10
      if (/\s/.test(range.toString()[0])) {
11
        range.setStart(range.startContainer, range.startOffset + 1);
12
        break;
13
      }
14
    }
15

16
    // 向后扩展到单词边界
17
    const container = range.endContainer;
18
    while (range.endOffset < container.textContent.length) {
19
      range.setEnd(container, range.endOffset + 1);
20
      if (/\s/.test(range.toString().slice(-1))) {
21
        range.setEnd(container, range.endOffset - 1);
22
        break;
23
      }
24
    }
25

26
    selection.removeAllRanges();
27
    selection.addRange(range);
28
  }
29
}

扩展思路：

可进一步扩展为选择句子：以句号、问号、感叹号为边界
选择段落：以换行符或 <p> 标签为边界

6. 虚拟光标 - 在不可编辑区域显示光标#

在只读元素中创建视觉光标，常用于自定义输入框或代码编辑器。

1
function createVirtualCursor(element, offset) {
2
  const range = document.createRange();
3
  range.setStart(element.firstChild, offset);
4
  range.collapse(true);
5

6
  // 创建一个零宽度的 span 作为光标
7
  const cursor = document.createElement('span');
8
  cursor.className = 'virtual-cursor';
9
  cursor.style.cssText = `
10
    display: inline-block;
11
    width: 2px;
12
    height: 1.2em;
13
    background: black;
14
    animation: blink 1s infinite;
15
  `;
16

17
  range.insertNode(cursor);
18
}

配套 CSS 动画：

1
@keyframes blink {
2
  0%, 49% { opacity: 1; }
3
  50%, 100% { opacity: 0; }
4
}

7. 比较两个选区是否相交#

用于判断多个选区之间的关系，常见于协同编辑场景。

1
function rangesIntersect(range1, range2) {
2
  // 使用 compareBoundaryPoints 比较边界
3
  return range1.compareBoundaryPoints(Range.START_TO_END, range2) > 0 &&
4
         range1.compareBoundaryPoints(Range.END_TO_START, range2) < 0;
5
}

compareBoundaryPoints 常量：

Range.START_TO_START (0)：比较两个 Range 的起点
Range.START_TO_END (1)：比较第一个 Range 的起点和第二个的终点
Range.END_TO_END (2)：比较两个 Range 的终点
Range.END_TO_START (3)：比较第一个 Range 的终点和第二个的起点

8. 文本批注/评论功能#

实现类似 Google Docs 的文本批注功能。

1
function addComment(commentText) {
2
  const selection = window.getSelection();
3
  if (selection.rangeCount > 0) {
4
    const range = selection.getRangeAt(0);
5

6
    const mark = document.createElement('mark');
7
    mark.className = 'comment-highlight';
8
    mark.dataset.comment = commentText;
9
    mark.style.backgroundColor = '#ffeb3b';
10
    mark.style.cursor = 'pointer';
11

12
    // 保存原始文本位置信息
13
    mark.dataset.startOffset = range.startOffset;
14
    mark.dataset.endOffset = range.endOffset;
15

16
    range.surroundContents(mark);
17

18
    // 添加点击事件显示评论
19
    mark.addEventListener('click', function() {
20
      alert('评论: ' + this.dataset.comment);
21
    });
22
  }
23
}

生产环境优化：

使用 UUID 作为批注 ID，关联到数据库
支持批注的回复和删除
使用 Popover API 或 Tooltip 替代 alert

9. 计算文本行数和换行位置#

获取文本的实际渲染行数，用于实现行号显示或精确定位。

1
function getLineBreaks(element) {
2
  const range = document.createRange();
3
  const lines = [];
4
  let lastTop = -1;
5

6
  const text = element.textContent;
7

8
  for (let i = 0; i < text.length; i++) {
9
    range.setStart(element.firstChild, i);
10
    range.setEnd(element.firstChild, i + 1);
11

12
    const rect = range.getBoundingClientRect();
13

14
    if (rect.top !== lastTop) {
15
      lines.push({ index: i, top: rect.top });
16
      lastTop = rect.top;
17
    }
18
  }
19

20
  return lines;
21
}

性能优化建议：

对于长文本，可使用二分查找减少计算次数
缓存结果，仅在窗口 resize 时重新计算

10. 实现代码编辑器的括号匹配高亮#

在代码编辑器中高亮显示匹配的括号对。

1
function highlightMatchingBrackets() {
2
  const selection = window.getSelection();
3
  if (selection.rangeCount === 0) return;
4

5
  const range = selection.getRangeAt(0);
6
  const offset = range.startOffset;
7
  const text = range.startContainer.textContent;
8

9
  const char = text[offset];
10
  const pairs = { '(': ')', '[': ']', '{': '}' };
11

12
  if (pairs[char]) {
13
    // 查找匹配的右括号
14
    let count = 1;
15
    for (let i = offset + 1; i < text.length; i++) {
16
      if (text[i] === char) count++;
17
      if (text[i] === pairs[char]) count--;
18

19
      if (count === 0) {
20
        // 高亮两个括号
21
        highlightRange(range.startContainer, offset, offset + 1);
22
        highlightRange(range.startContainer, i, i + 1);
23
        break;
24
      }
25
    }
26
  }
27
}
28

29
function highlightRange(node, start, end) {
30
  const range = document.createRange();
31
  range.setStart(node, start);
32
  range.setEnd(node, end);
33

34
  const span = document.createElement('span');
35
  span.style.backgroundColor = '#e0e0e0';
36
  range.surroundContents(span);
37
}

完善建议：

添加反向括号匹配（从右括号找左括号）
支持多行跨节点匹配
添加未匹配括号的错误提示

实际应用场景#

Range API 在现代 Web 应用中有广泛的应用：

富文本编辑器：Notion、Google Docs、语雀等
代码编辑器：VS Code Web、CodeMirror、Monaco Editor
PDF 标注工具：文本高亮、批注、标记
阅读辅助工具：划词翻译、生词本、阅读进度追踪
协同编辑：多人光标位置显示、实时编辑同步
文本分析工具：语法检查、关键词提取、敏感词过滤

总结#

Range API 的强大之处在于它能够精确控制 DOM 中的任意片段，而不需要破坏原有结构。通过合理使用 Range API，我们可以实现复杂的文本编辑和交互功能。

核心优势：

精确定位：可以精确到字符级别的位置控制
非破坏性操作：不会破坏原有 DOM 结构
灵活性高：支持复杂的选区操作和内容提取
浏览器原生支持：无需引入第三方库

最佳实践：

始终检查 selection.rangeCount 避免空指针错误
大量 DOM 操作时使用 DocumentFragment 提升性能
注意内存泄漏，及时清除事件监听器
考虑浏览器兼容性，必要时使用 polyfill