如何在Google Docs中借助Google Apps Script持续追踪光标位置

为什么你的无限循环方案不可行 #

• Google Apps Script的服务端函数有最长执行时间限制（当前为6分钟），无限循环会很快触发超时终止。
• 服务端脚本无法实时监听客户端的光标移动事件，只能被动调用，无限循环会占用大量资源导致文档卡顿。

正确实现方案：客户端事件监听+服务端存储 #

核心思路是用浏览器原生事件监听光标变化，再调用服务端脚本存储位置信息，具体步骤如下：

1. 服务端脚本（Code.gs） #

负责创建菜单、显示侧边栏、处理位置存储与恢复：

function onOpen() {
  DocumentApp.getUi()
    .createMenu('光标追踪')
    .addItem('启动追踪', 'showSidebar')
    .addItem('恢复上次光标位置', 'restoreCursorPosition')
    .addToUi();
}

// 显示侧边栏，加载客户端监听脚本
function showSidebar() {
  const html = HtmlService.createHtmlOutputFromFile('Sidebar')
    .setTitle('光标追踪');
  DocumentApp.getUi().showSidebar(html);
}

// 存储光标位置到用户属性
function saveCursorPosition(elementId, offset) {
  const userProps = PropertiesService.getUserProperties();
  userProps.setProperty('lastCursor', JSON.stringify({
    elementId: elementId,
    offset: offset
  }));
}

// 获取存储的光标位置
function getSavedCursor() {
  const userProps = PropertiesService.getUserProperties();
  const saved = userProps.getProperty('lastCursor');
  return saved ? JSON.parse(saved) : null;
}

// 恢复光标到存储的位置
function restoreCursorPosition() {
  const saved = getSavedCursor();
  if (!saved) return;

  const doc = DocumentApp.getActiveDocument();
  const targetElement = doc.getElementById(saved.elementId);
  if (targetElement) {
    const cursorPosition = doc.newPosition(targetElement, saved.offset);
    doc.setCursor(cursorPosition);
  }
}

2. 客户端侧边栏（Sidebar.html） #

通过浏览器原生selectionchange事件实时监听光标移动，并调用服务端函数存储位置：

<!DOCTYPE html>
<html>
<head>
  <base target="_top">
  <script>
    // 监听光标/选区变化事件
    document.addEventListener('selectionchange', () => {
      const selection = window.getSelection();
      if (selection.rangeCount === 0) return;

      const range = selection.getRangeAt(0);
      // 找到对应的Google Docs元素（带data-doc-id属性）
      const docElement = range.startContainer.parentElement.closest('[data-doc-id]');
      if (!docElement) return;

      const elementId = docElement.getAttribute('data-doc-id');
      // 计算相对于元素文本内容的偏移量
      let textOffset = 0;
      for (let i = 0; i < range.startOffset; i++) {
        const node = range.startContainer.childNodes[i];
        textOffset += node.textContent ? node.textContent.length : 0;
      }

      // 调用服务端函数存储位置
      google.script.run.saveCursorPosition(elementId, textOffset);
    });
  </script>
</head>
<body>
  <p>光标追踪已启动，移动光标时会自动记录位置</p>
</body>
</html>

关键说明 #

• 事件监听：selectionchange事件会在光标移动、选区修改时触发，是实时追踪的核心。
• 元素标识：Google Docs的每个可编辑元素都带有data-doc-id属性，通过它可以在服务端定位到对应的文档元素。
• 偏移量转换：客户端DOM节点的偏移需要转换成服务端Position对象能识别的文本偏移量，确保恢复位置准确。
• 存储方式：示例中用PropertiesService.getUserProperties()存储位置，数据绑定到当前用户，也可以换成存储到Google表格或其他数据库。

内容的提问来源于stack exchange，提问作者Marco Valerioti