如何获取Google Docs正文起始索引以调用API添加脚注？

问题背景 #

需要将文档中匹配特定正则表达式的文本替换为包含该文本的脚注，但DocumentApp.findText()返回的是元素内的偏移位置，而Google Docs API创建脚注需要的是文档全局的正文起始索引，如何获取这个全局索引？

解决方案 #

核心思路是计算当前匹配元素之前所有正文内容的总字符数，再加上元素内的起始偏移，得到全局索引。具体实现步骤如下：

1. 预收集所有匹配信息：先遍历找到所有正则匹配项，记录每个匹配在元素内的偏移、文本内容，同时计算对应的全局索引。
2. 从后往前处理：由于修改文档会改变后续内容的索引，从最后一个匹配开始处理，避免位置错乱。
3. 批量执行API请求：将删除原文本、创建脚注、插入脚注内容的操作打包成批量请求，提升执行效率。

修改后的完整代码 #

function makeRef() {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody();
  const documentId = doc.getId();
  const myRegEx = /\([a-zA-Z]+?.+?,.+?[12][0-9]{3}\)/g;

  // 收集所有匹配的全局位置与文本内容
  const matches = [];
  let foundElement = body.findText(myRegEx);

  while (foundElement !== null) {
    const textElement = foundElement.getElement().asText();
    const startInElement = foundElement.getStartOffset();
    const endInElement = foundElement.getEndOffsetInclusive();
    const matchText = textElement.getText().substring(startInElement, endInElement + 1);

    // 计算当前元素之前的所有正文字符总数
    let totalCharsBefore = 0;
    const elements = body.getChildren();
    const targetParentId = textElement.getParent().getId(); // 当前文本所在段落/列表项的ID

    for (const elem of elements) {
      if (elem.getId() === targetParentId) break; // 遍历到当前元素的父元素时停止

      // 累加不同类型元素的文本长度
      switch (elem.getType()) {
        case DocumentApp.ElementType.PARAGRAPH:
          totalCharsBefore += elem.asParagraph().getText().length;
          break;
        case DocumentApp.ElementType.LIST_ITEM:
          totalCharsBefore += elem.asListItem().getText().length;
          break;
        case DocumentApp.ElementType.HEADING_1:
        case DocumentApp.ElementType.HEADING_2:
        case DocumentApp.ElementType.HEADING_3:
          totalCharsBefore += elem.asHeading().getText().length;
          break;
        // 可根据文档实际包含的元素类型补充处理逻辑
      }
    }

    // 全局索引 = 前面元素总字符数 + 元素内起始偏移
    const globalStartIndex = totalCharsBefore + startInElement;
    matches.push({
      start: globalStartIndex,
      end: globalStartIndex + (endInElement - startInElement),
      text: matchText
    });

    foundElement = body.findText(myRegEx, foundElement);
  }

  // 按全局索引从大到小排序，避免修改文档导致后续索引失效
  matches.sort((a, b) => b.start - a.start);

  const requests = [];
  matches.forEach(match => {
    // 1. 删除原匹配文本
    requests.push({
      deleteContentRange: {
        range: { startIndex: match.start, endIndex: match.end + 1 }
      }
    });

    // 2. 在原位置创建脚注
    requests.push({
      createFootnote: {
        location: { index: match.start }
      }
    });

    // 3. 向脚注插入文本（脚注内容起始索引为原位置+1，因脚注标记占用1个索引位）
    requests.push({
      insertText: {
        location: { index: match.start + 1 },
        text: match.text
      }
    });
  });

  if (requests.length > 0) {
    Docs.Documents.batchUpdate({ requests }, documentId);
  }
}

关键说明 #

• 全局索引计算：通过遍历文档正文的所有子元素，累加当前匹配元素之前的所有文本长度，再加上元素内的起始偏移，得到Docs API所需的全局索引。
• 元素类型兼容：针对段落、列表项、标题等常见文本元素分别处理，确保所有前置文本长度都被正确累加；若文档包含其他文本类元素，可在switch分支中补充对应逻辑。
• 处理顺序优化：将匹配项按全局索引从大到小排序，从后往前执行修改操作，避免前面的文本删除、脚注插入等操作导致后续匹配的索引位置错乱。

内容的提问来源于stack exchange，提问作者Serge Valkovsky